Veiledning: Bygg en .NET mid-tier tjeneste med Execute DAX Queries REST API-et

I denne veiledningen tar du Microsoft. Samples.XMLA.ExecuteQueries sample — et .NET Web API som proxyer DAX-spørringer gjennom XMLA-endepunktet ved bruk av ADOMD.NET — og modifiserer det til å bruke Execute DAX Queries REST API, som returnerer resultater i Apache Arrow IPC-format. Utvalget gir mellomnivå-rammeverket (ruting, rate limiting, health probe). Denne veiledningen viser deg hvordan du kan erstatte XMLA/ADOMD-spørringsutførelsen med REST API-kall og Arrow IPC-responshåndtering.

Forutsetninger

• .NET 8 SDK eller nyere.
• Et Power BI-arbeidsområde på Premium- eller Fabric-kapasitet med minst én semantisk modell.
• En Microsoft Entra-appregistrering med en klienthemmelighet.
• Tjenesteansvarlig lagt til som et arbeidsområdemedlem med Bidragsyter (eller høyere) rolle.
• Følgende leietakerinnstillinger aktivert:
  • Dataset Execute Queries REST API og Tillat tjenesteledere å bruke Power BI APIer (under Developer settings).
  • Tillat XMLA-endepunkter og analyser i Excel med on-premises semantiske modeller (under Integrasjonsinnstillinger).

For detaljer om eksempel-tjenestearkitekturen, se sample README.

Før du starter

Eksempeltjenesten bruker XMLA-endepunktet med ADOMD.NET. Denne veiledningen konverterer den til å bruke Execute DAX Queries REST API, som returnerer resultater i Apache Arrow IPC-format. Begge tilnærmingene lar deg kjøre DAX-spørringer mot Power BI-semantiske modeller, men de skiller seg på viktige måter.

Velg Execute DAX Queries REST API når du bygger en ny tjeneste eller dine nedstrømsbrukere kan dra nytte av Arrow IPC (for eksempel analysepipelines, Python notatbøker eller kolonnedatabaser). Behold XMLA/ADOMD hvis du trenger MDX-støtte eller stoler på funksjoner på økt nivå, som kalkulerte medlemmer begrenset til en økt.

1 - Klone og verifisere prøven

Klon repositoriet og bekreft at det kompilerer:

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

Løsningen inneholder to prosjekter: mellomnivåtjenesten (Microsoft.Samples.XMLA.ExecuteQueries) og en lasttestklient (Tester). Du trenger ikke å kjøre den opprinnelige tjenesten mot et levende arbeidsområde — bare sjekk at bygget lykkes før du gjør endringer.

2 - Oppdater NuGet-avhengigheter

I Microsoft.Samples.XMLA.ExecuteQueries-prosjektet, fjern ADOMD.NET-pakken og legg til pakker for Arrow API:

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

Behold Microsoft.PowerBI.Api-pakken hvis du vil gjenbruke dens forespørsels-/svarmodelltyper; ellers fjern det og definer dine egne DTO-er.

3 - Erstatt ADOMD-tilkoblingspooling med MSAL-token-caching

Eksempelet brukes AdomdConnectionPool.cs til å samle XMLA-tilkoblinger. Arrow API er et stateless REST-endepunkt, så du erstatter tilkoblingspooling med MSAL-tokencaching.

Opprett en ny fil 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 cacher tokens automatisk — påfølgende anrop returnerer den bufrede tokenen til den utløper.

Slett AdomdConnectionPool.cs og AdomdExtensions.cs. De er ikke lenger nødvendige.

4 - Oppdater spørringshåndtereren til å kalle Arrow API

I Handlers.cs, erstatter ADOMD-spørringsutførelsen med et HTTP-kall til Execute DAX Queries-endepunktet.

Fjern alle ADOMD-referanser (AdomdConnectionPool, AdomdConnection, AdomdCommand, WrappedConnection). Endre handlerens injiserte avhengigheter til og HttpClient i stedet for TokenService tilkoblingspooler og arbeidsområdeoppslag.

Bygg REST API-URL-fra arbeidsområdets og datasettets GUID-er som allerede er tilgjengelige i ruteparametrene:

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

POST DAX-spørringen med en JSON-forespørselskropp:

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();

Bruk HttpCompletionOption.ResponseHeadersRead slik at responskroppen strømmer uten buffering — dette er viktig for store resultatsett.

5 - Håndter Arrow IPC-responsen

Execute DAX Queries API returnerer en eller flere Arrow IPC-strømmer som er sammenkoblet i svarkroppen. Hver strøm inkluderer skjemametadata som angir dens formål:

• Dataresultat — spørringsresultatene (ingen spesielle metadataflagg).
• Feilresultat — IsError=true i skjemametadataene, med FaultCode og FaultString verdier.
• Utførelsesmetrikker — IsExecMetrics=true (hvis du ba om metrikker via parameteren executionMetrics ).

Erstatt DataResult.cs med logikk som håndterer Arrow-responsen. Hvis mellomlageret ditt bare videresender Arrow IPC til nedstrøms forbrukere, strømmer bytene gjennom uten deserialisering:

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

Hvis du trenger å inspisere resultater eller konvertere formater, deserialiser pilstrømmen med 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.
}

Sjekk skjemametadataene for å oppdage feilsvar:

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 - Forenkle konfigurasjonen av arbeidsområdet

Eksemplaret konfigurerer appsettings.json XMLA-endepunkter og oppslag av datasettnavn fordi ADOMD kobler til katalognavn. Arrow REST API bruker arbeidsområde- og datasett-GUID-er direkte fra forespørsels-URL-en, så konfigurasjonen er enklere.

Oppdater appsettings.json med dine tjenesteprincipal-legitimasjoner og fjern de XMLA-spesifikke feltene:

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

Seksjonen Workspaces med XmlaEndpoint og Datasets arrays er ikke lenger nødvendig. Du kan slette Workspace.cs og Dataset.cs, eller ombruke Datasets listen som en tillatelsesliste for styring (og begrense hvilke datasett tjenesten kan spørre i).

7 - Registrer tjenester og oppdater ruting

I Program.cs, erstatter ADOMD-poolen og arbeidsplassregistreringene med de nye tjenestene:

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

Oppdater ruten slik at den matcher endepunktsmønsteret Execute DAX Queries:

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

Den eksisterende hastighetsbegrenseren, helseproben og forespørselsteller fra prøven forblir nyttige as-is.

8 - Test tjenesten

Kjør tjenesten:

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

Fra en annen terminal, send en DAX-spørring:

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'\'')"}'

Svaret er en binær Arrow IPC-strøm. Lagre det i en fil og inspiser med Python:

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())
"

Oversikt over endringer

Rydde opp ressurser

Når du er ferdig med testingen:

1. Stopp den lokale tjenesten (trykk Ctrl+C i terminalen).
2. Hvis du opprettet en Microsoft Entra-appregistrering kun for denne veiledningen, gå til portalen Azure og slett den.
3. Fjern tjenesteprinsippet fra Power BI-arbeidsområdet hvis det ikke lenger trengs.

Relatert innhold

• Forstå Execute DAX Query API-et
• Kom i gang med Execute DAX Queries REST API-et
• Veiledning: Ekstraksjon med høyt volum Python for data science
• Beste praksis for Execute DAX Queries REST API
• Microsoft. Samples.XMLA.ExecuteQueries sample (GitHub)