Opastus: Rakenna .NET-keskitasoinen palvelu Execute DAX Queries REST API:lla

Tässä opetusohjelmassa suoritat Microsoft. Samples.XMLA.ExecuteQueries sample — .NET Web API, joka välittää DAX-kyselyt XMLA-päätepisteen kautta ADOMDn avulla.NET ja muokkaa sitä käyttämään Execute DAX Queries REST API -tiedostoa, joka palauttaa tulokset Apache Arrow IPC -muodossa. Otos tarjoaa keskitason viitekehyksen (reititys, nopeusrajoitus, terveyskoetin). Tämä opas näyttää, miten korvata XMLA/ADOMD-kyselyjen suoritusputki REST API -kutsuilla ja Arrow IPC -vastauskäsittelyllä.

edellytykset

• .NET 8 SDK tai uudempi.
• Power BI-työtila Premium- tai Fabric-kapasiteetilla, jossa on vähintään yksi semanttinen malli.
• Microsoft Entra -sovelluksen rekisteröinti asiakassalaisuudella.
• Palvelupäähenkilö lisättiin työtilan jäseneksi, jolla on Contributor (tai korkeampi) rooli.
• Seuraavat vuokralaisasetukset käytössä:
  • Dataset Execute Queries REST API ja Salli palvelupäähenkilöiden käyttää Power BI API (Developer settings).
  • Salli XMLA-päätepisteet ja analysoi Excel paikallisilla semanttisilla malleilla (kohdassa Integraatioasetukset).

Lisätietoja esimerkkipalveluarkkitehtuurista löytyy sample README.

Alkuvalmistelut

Esimerkkipalvelu käyttää XMLA-päätepistettä ADOMD.NET:n kanssa. Tämä opas muuntaa sen käyttämään Execute DAX Queries REST API:a, joka palauttaa tulokset Apache Arrow IPC -muodossa. Molemmat lähestymistavat mahdollistavat DAX-kyselyjen ajamisen Power BI:n semanttisia malleja vastaan, mutta ne eroavat toisistaan merkittävillä tavoilla.

Valitse Execute DAX Queries REST API kun rakennat uutta palvelua tai alavirran käyttäjät voivat hyötyä Arrow IPC:stä (esimerkiksi analytiikkaputket, Python notebookit tai sarakkeiden tietokannat). Pidä XMLA/ADOMD , jos tarvitset MDX-tukea tai luotat istuntotason ominaisuuksiin, kuten laskettuun jäseneen, joka on määritelty istuntoon.

1 - Kloonaa ja varmista näyte

Kloonaa tietovarasto ja varmista, että se kääntää:

git clone https://github.com/dbrownems/Microsoft.Samples.XMLA.ExecuteQueries.git
cd Microsoft.Samples.XMLA.ExecuteQueries
dotnet build

Ratkaisu sisältää kaksi projektia: keskitasoisen palvelun (Microsoft.Samples.XMLA.ExecuteQueries) ja kuormitustestiasiakkaan (Tester). Alkuperäistä palvelua ei tarvitse ajaa live-työtilassa — varmista vain, että buildin onnistuu ennen muutosten tekemistä.

2 - Päivitä NuGet-riippuvuudet

Microsoft.Samples.XMLA.ExecuteQueries-projektissa poista ADOMD.NET-paketti ja lisää paketteja Arrow API:lle:

cd Microsoft.Samples.XMLA.ExecuteQueries
dotnet remove package Microsoft.AnalysisServices.AdomdClient.NetCore.retail.amd64
dotnet add package Apache.Arrow
dotnet add package Microsoft.Identity.Client

Pidä Microsoft.PowerBI.Api-paketti, jos haluat käyttää uudelleen sen pyyntö/vastaus-mallityyppejä; muuten poista se ja määrittele omat DTO:si.

3 - Korvaa ADOMD-yhteyspoolaus MSAL-token-välimuistilla

Näytettä käytetään AdomdConnectionPool.cs XMLA-yhteyksien yhdistämiseen. Arrow-API on tilaton REST-päätelaite, joten yhteyspoolaus korvataan MSAL-token-välimuistilla.

Luo uusi tiedosto TokenService.cs:

using Microsoft.Identity.Client;

public class TokenService
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes =
        { "https://analysis.windows.net/powerbi/api/.default" };

    public TokenService(IConfiguration config)
    {
        _app = ConfidentialClientApplicationBuilder
            .Create(config["PowerBI:ClientId"])
            .WithClientSecret(config["PowerBI:ClientSecret"])
            .WithAuthority(AzureCloudInstance.AzurePublic,
                config["PowerBI:TenantId"])
            .Build();
    }

    public async Task<string> GetAccessTokenAsync()
    {
        var result = await _app
            .AcquireTokenForClient(_scopes).ExecuteAsync();
        return result.AccessToken;
    }
}

MSAL välimuistittaa tokenit automaattisesti — seuraavat kutsut palauttavat välimuistitetun tokenin siihen asti, kunnes se vanhenee.

Poista AdomdConnectionPool.cs ja AdomdExtensions.cs. Niitä ei enää tarvita.

4 - Päivitä kyselyn käsittelijä kutsumaan Arrow-rajapintaa

Korvaa Handlers.csADOMD-kyselyn suoritus HTTP-kutsulla Execute DAX Queries -päätepisteelle.

Poista kaikki ADOMD-viittaukset (AdomdConnectionPool, AdomdConnection, AdomdCommand, WrappedConnection). Muuta käsittelijän injektoidut TokenService riippuvuudet yhteyspooleihin ja työtilahakuihin ja HttpClient niiden sijaan.

Rakenna REST API URL työtilasta ja datasetin GUID-tiedostoista, jotka ovat jo saatavilla reittiparametreissa:

var url = $"https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}"
        + $"/datasets/{datasetId}/executeDaxQueries";

POST DAX-kysely JSON-pyyntörungolla:

var token = await tokenService.GetAccessTokenAsync();

using var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent(
    JsonSerializer.Serialize(new { query, queryTimeout = 120 }),
    Encoding.UTF8, "application/json");

var response = await httpClient.SendAsync(
    request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();

Käytä HttpCompletionOption.ResponseHeadersRead niin, että vastekappale virtaa ilman puskurointia — tämä on tärkeää suurille tulosjoukoille.

5 - Käsittele Arrow IPC:n vastaus

Execute DAX Queries API palauttaa yhden tai useamman Arrow IPC -virtaa, jotka on yhdistetty vastausrunkoon. Jokainen virta sisältää skeeman metatiedot, jotka osoittavat sen tarkoituksen:

• Datan tulokset — kyselytulokset (ei erityisiä metatietomerkkejä).
• Virhetulos — IsError=true skeeman metatiedoissa, arvoilla FaultCode ja FaultString
• Suoritusmittarit — IsExecMetrics=true (jos pyysit mittareita parametrin kautta executionMetrics ).

Korvaa DataResult.cs logiikka, joka käsittelee nuolivastetta. Jos keskitasosi vain välittää Arrow IPC:n alavirran kuluttajille, striimaa tavut ilman deserialisointia:

context.Response.ContentType = "application/vnd.apache.arrow.stream";
await response.Content.CopyToAsync(context.Response.Body);

Jos tarvitset tuloksia tai muuntaa muotoja, deserialisoi Arrow-virta seuraavasti ArrowStreamReader:

using var stream = await response.Content.ReadAsStreamAsync();
using var reader = new ArrowStreamReader(stream);

while (true)
{
    var batch = await reader.ReadNextRecordBatchAsync();
    if (batch == null) break;
    // Process batch — convert to JSON, filter rows, etc.
}

Tarkista skeeman metatiedot virhevasteiden havaitsemiseksi:

var metadata = reader.Schema.Metadata;
if (metadata.TryGetValue("IsError", out var isError)
    && isError == "true")
{
    var faultCode = metadata.GetValueOrDefault(
        "FaultCode", "Unknown");
    var faultString = metadata.GetValueOrDefault(
        "FaultString", "Unknown error");
    // Return error to caller
}

6 - Työtilan konfiguroinnin yksinkertaistaminen

Näytteet appsettings.json konfiguroivat XMLA-päätepisteet ja aineiston nimihakuja, koska ADOMD yhdistää katalogin nimen perusteella. Arrow REST API käyttää työtila- ja tietosetin GUID-tiedostoja suoraan pyyntö-URL:stä, joten konfigurointi on yksinkertaisempaa.

Päivitä appsettings.json palvelupäähenkilön tunnoksilla ja poista XMLA-kohtaiset kentät:

{
  "PowerBI": {
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_APP_CLIENT_ID",
    "ClientSecret": "YOUR_CLIENT_SECRET"
  }
}

Osio Workspaces , jossa XmlaEndpoint on ja Datasets taulukot, ei ole enää tarpeen. Voit poistaa Workspace.cs ja Dataset.cs, tai käyttää listan Datasets uudelleen sallittujen listojen hallintaan (rajoittaen, mitä tietoaineistoja palvelu voi kysyä).

7 - Palveluiden rekisteröinti ja reitityksen päivittäminen

Korvaa Program.csADOMD-poolin ja työtilan rekisteröinnit uusilla palveluilla:

builder.Services.AddSingleton<TokenService>();
builder.Services.AddHttpClient();

Päivitä reitti vastaamaan Execute DAX Queries -päätepistemallia:

app.MapPost(
    "/v1.0/myorg/groups/{workspaceId:Guid}"
    + "/datasets/{datasetId:Guid}/executeDaxQueries",
    Handlers.ExecuteDaxQueriesInGroup);

Nykyinen nopeusrajoitin, terveysanturi ja pyyntölaskuri näytteestä ovat edelleen hyödyllisiä as-is.

8 - Testaa palvelu

Suorita palvelu:

dotnet run --project Microsoft.Samples.XMLA.ExecuteQueries

Lähetä toiselta päätteeltä DAX-kysely:

curl -X POST https://localhost:3000/v1.0/myorg/groups/YOUR_WORKSPACE_ID/datasets/YOUR_DATASET_ID/executeDaxQueries \
  -H "Content-Type: application/json" \
  -d '{"query": "EVALUATE TOPN(5, '\''DimProduct'\'')"}'

Vastaus on binäärinen Arrow IPC -virta. Tallenna se tiedostoksi ja tutki Python:lla:

curl -s -o result.arrow https://localhost:3000/v1.0/myorg/groups/YOUR_WORKSPACE_ID/datasets/YOUR_DATASET_ID/executeDaxQueries \
  -H "Content-Type: application/json" \
  -d '{"query": "EVALUATE TOPN(5, '\''DimProduct'\'')"}'

python -c "
import pyarrow as pa
reader = pa.ipc.open_stream('result.arrow')
table = reader.read_all()
print(table.schema)
print(table.to_pandas())
"

Muutosten yhteenveto

Puhdista resurssit

Kun testaus on valmis:

1. Pysäytä paikallinen palvelu (paina Ctrl+C terminaalissa).
2. Jos loit Microsoft Entra-sovelluksen rekisteröinnin vain tätä opetusta varten, siirry Azure-portaaliin ja poista se.
3. Poista palveluperiaate Power BI-työtilasta, jos sitä ei enää tarvita.

Liittyvä sisältö

• Ymmärrä Execute DAX Queries API
• Aloita Execute DAX Queries REST API:n käyttö
• Opetus: Suurivolyymi Python poiminta data-analytiikalle
• Parhaat käytännöt Execute DAX Queries REST API:lle
• Microsoft. Samples.XMLA.ExecuteQueries sample (GitHub)