Tutorial: Kør flere ECATERE-sætninger med PowerShell

I denne vejledning bruger du PowerShell til at indsende en enkelt Execute DAX Queries REST API-anmodning , der indeholder flere EVALUATE sætninger, og derefter parse det multi-result-satte Apache Arrow-svar. Dette mønster lader dig hente flere relaterede resultatsæt på én rundtur fra et PowerShell-automatiseringsscript.

Diagram, der viser én HTTP POST-anmodning, der indeholder tre EVALUATE-sætninger i sin forespørgselskrop, og Arrow IPC-svaret, der indeholder tre resultatsæt i samme rækkefølge.

Hvorfor indsende flere EVALUATE-udsagn i én anmodning

Execute DAX Queries API accepterer en enkelt query streng, der kan indeholde flere EVALUATE sætninger. Hver sætning returnerer sit eget resultatsæt, og svarkroppen er sammenkædningen af én Arrow IPC-strøm pr. EVALUATE sætning i deklarationsrækkefølge. At indsende relaterede forespørgsler sammen undgår den overhead pr. anmodning, der følger med separate HTTP-kald, herunder ekstra validering af Microsoft Entra-token og initialisering af DAX-motoren. At sende flere EVALUATE udsagn i én forespørgsel kan også hjælpe med at mindske virkningen af anmodningsbegrænsning. Power BI begrænser kaldere til 120 forespørgselsanmodninger pr. minut pr. bruger for forespørgselsoperationer med semantiske modeller.

Hvad du bygger

I ét PowerShell-script, du:

  1. Erhverv en Microsoft Entra adgangstoken.
  2. Byg en anmodningskropp, der query indeholder tre EVALUATE sætninger.
  3. Send anmodningen og optag den rå Arrow IPC-responsstrøm.
  4. Parse svaret i ét resultatsæt pr. EVALUATE sætning.
  5. Vis hvert resultatsæt som PowerShell-objekter.

Forudsætninger

  • PowerShell 7.4 eller nyere. Windows PowerShell 5.1 understøttes ikke, fordi pakken, der Apache.Arrow bruges i denne tutorial, er i konflikt med assemblyen, der System.Memory er inkluderet i PowerShell 5.1.
  • Et Power BI-arbejdsområde på Premium- eller Fabric-kapacitet med mindst én semantisk model.
  • Bygge- og læsetilladelser på den semantiske model.
  • MicrosoftPowerBIMgmt-modulet til autentificering. Cmdlets bruger Microsoft's førsteparts Power BI-klientapp, så du behøver ikke registrere din egen app i Microsoft Entra.
  • Apache.Arrow og Apache.Arrow.Compression .NET-bibliotekerne for at deserialisere svaret. Execute DAX Queries REST API komprimerer Arrow-buffere med LZ4-rammekomprimering, så Apache.Arrow.Compression og dens afhængigheder (K4os.Compression.LZ4, K4os.Compression.LZ4.Streams, K4os.Hash.xxHash, ZstdSharp.Port) er nødvendige. Næste trin viser, hvordan man downloader dem.
  • Følgende lejerindstillinger aktiveret i Power BI admin-portalen:
    • Dataset Execute Queries REST API (under udviklerindstillinger).
    • Tillad XMLA-endepunkter og analyser i Excel med on-premises semantiske modeller (under Integrationsindstillinger).

Installer PowerShell 7.4 eller nyere ved at bruge winget:

winget install --id Microsoft.PowerShell --source winget

Efter installationen lanceres den nye skal med pwsh. Kør de resterende kommandoer i denne tutorial fra den session.

Installer MicrosoftPowerBIMgmt-modulet. Flaget -Force accepterer PowerShell Gallery untrusted-repository-prompten.

Install-Module -Name MicrosoftPowerBIMgmt -Scope CurrentUser -Force

Download de nødvendige NuGet-pakker og udpak deres assemblies til C:\Tools\Apache.Arrow\. En fil er et ZIP-arkiv, så Expand-Archive den .nupkg arbejder direkte på det. Løkken vælger den højeste netX.0 målmappe i hver pakke, så assemblies forbliver kompatible, efterhånden som pakkerne offentliggør nyere mål.

$dest = "C:\Tools\Apache.Arrow"
New-Item -ItemType Directory -Force -Path $dest | Out-Null

$packages = @(
    "Apache.Arrow",
    "Apache.Arrow.Compression",
    "K4os.Compression.LZ4",
    "K4os.Compression.LZ4.Streams",
    "K4os.Hash.xxHash",
    "ZstdSharp.Port"
)

foreach ($pkg in $packages) {
    $nupkg  = Join-Path $env:TEMP "$pkg.nupkg"
    $expand = Join-Path $env:TEMP $pkg
    if (Test-Path $expand) { Remove-Item $expand -Recurse -Force }

    Invoke-WebRequest -Uri "https://www.nuget.org/api/v2/package/$pkg" -OutFile $nupkg
    Expand-Archive -Path $nupkg -DestinationPath $expand -Force

    $libDirs = Get-ChildItem (Join-Path $expand "lib") -Directory
    $best = $libDirs | Where-Object { $_.Name -match "^net\d" } |
            Sort-Object Name -Descending | Select-Object -First 1
    if (-not $best) {
        $best = $libDirs | Sort-Object Name -Descending | Select-Object -First 1
    }

    Get-ChildItem (Join-Path $best.FullName "*.dll") |
        Copy-Item -Destination $dest -Force
}

1 - Autentificér

Log interaktivt ind på Power BI-tjeneste, og udtræk derefter et adgangstok. CMDLET'en Connect-PowerBIServiceAccount kræver ikke, at du registrerer din egen app i Microsoft Entra.

Connect-PowerBIServiceAccount -WarningAction SilentlyContinue
$accessToken = (Get-PowerBIAccessToken).Authorization -replace '^Bearer\s+',''

2 - Byg en forespørgsel med flere EVALUATE-sætninger

Definer workspace- og semantiske modelmål. Derefter bygger du anmodningskroppen. Egenskaben query er en enkelt streng, der indeholder tre EVALUATE sætninger adskilt af tomme linjer.

$groupId   = "YOUR_WORKSPACE_ID"
$datasetId = "YOUR_DATASET_ID"

$query = @"
EVALUATE
ROW("RowCount", COUNTROWS('Sales'))

EVALUATE
TOPN(10, 'Sales', 'Sales'[Amount], DESC)

EVALUATE
SUMMARIZECOLUMNS(
    'Date'[Year],
    "TotalSales", SUM('Sales'[Amount]))
"@

$body = @{
    query                  = $query
    resultsetRowcountLimit = 500000
} | ConvertTo-Json

3 - Send anmodningen og fang den rå responsstrøm

Send POST-forespørgslen og læs svarets krop som en binær strøm. Brug HttpWebRequest i stedet for Invoke-RestMethod, Invoke-PowerBIRestMethod, eller Invoke-WebRequest. Svaret er en binær Arrow IPC-strøm. De højere niveau PowerShell-cmdlets fortolker responskroppe som tekst, hvilket korrumperer binært indhold. HttpWebRequest returnerer den rå strøm uændret.

$url = "https://api.powerbi.com/v1.0/myorg/groups/$groupId" +
       "/datasets/$datasetId/executeDaxQueries"

$request = [System.Net.HttpWebRequest]::Create($url)
$request.Method      = "POST"
$request.ContentType = "application/json"
$request.Accept      = "application/vnd.apache.arrow.stream"
$request.Timeout     = 180000   # milliseconds
$request.Headers.Add("Authorization", "Bearer $accessToken")

$bodyBytes     = [System.Text.Encoding]::UTF8.GetBytes($body)
$requestStream = $request.GetRequestStream()
$requestStream.Write($bodyBytes, 0, $bodyBytes.Length)
$requestStream.Close()

$response       = $request.GetResponse()
$responseStream = $response.GetResponseStream()

# Buffer the response into memory so the parser can iterate over multiple Arrow IPC streams.
$memoryStream = New-Object System.IO.MemoryStream
$responseStream.CopyTo($memoryStream)
$responseStream.Close()
$response.Close()
$memoryStream.Position = 0

4 - Parse multi-resultat-sæt-svaret

Responsorganet er sammenkædningen af én Apache Arrow IPC-strøm pr. EVALUATE erklæring. PowerShell leveres ikke med en Arrow-parser, så dette trin indlæser .NET-biblioteket Apache.Arrow gennem en lille inline C#-hjælper, der er tilføjet med Add-Type. Hvis du beholder stream-loop-logikken i C#, forbliver kaldsstedet kort og returnerer en liste over resultatsæt, som dit PowerShell-script kan iterere. Hjælperen åbner en ny ArrowStreamReader efter hver end-of-stream-markør, så den samme løkke håndterer et vilkårligt antal resultatsæt i svaret.

Add-Type -Path "C:\Tools\Apache.Arrow\Apache.Arrow.dll"
Add-Type -Path "C:\Tools\Apache.Arrow\Apache.Arrow.Compression.dll"

# Reference the full .NET reference set that ships with PowerShell 7 so the
# inline C# below can resolve BCL types such as List<T> and Dictionary<,>.
$refs  = Get-ChildItem "$PSHOME\ref\*.dll" | ForEach-Object FullName
$refs += Get-ChildItem "C:\Tools\Apache.Arrow\*.dll" | ForEach-Object FullName

Add-Type -ReferencedAssemblies $refs -IgnoreWarnings -WarningAction SilentlyContinue -TypeDefinition @"
using System;
using System.Collections.Generic;
using System.IO;
using Apache.Arrow;
using Apache.Arrow.Compression;
using Apache.Arrow.Ipc;

public class DaxResultSet
{
    public List<string> ColumnNames = new List<string>();
    public List<Dictionary<string, object>> Rows =
        new List<Dictionary<string, object>>();
}

public static class DaxMultiResultReader
{
    public static List<DaxResultSet> ReadAll(Stream stream)
    {
        var results = new List<DaxResultSet>();
        var codecFactory = new CompressionCodecFactory();
        while (stream.Position < stream.Length)
        {
            var rs = new DaxResultSet();
            bool gotSchema = false;
            using (var reader = new ArrowStreamReader(stream, codecFactory, leaveOpen: true))
            {
                RecordBatch batch;
                while ((batch = reader.ReadNextRecordBatch()) != null)
                {
                    using (batch)
                    {
                        if (!gotSchema)
                        {
                            foreach (var f in batch.Schema.FieldsList)
                                rs.ColumnNames.Add(f.Name);
                            gotSchema = true;
                        }
                        for (int r = 0; r < batch.Length; r++)
                        {
                            var row = new Dictionary<string, object>();
                            for (int c = 0; c < batch.ColumnCount; c++)
                                row[rs.ColumnNames[c]] = GetValue(batch.Column(c), r);
                            rs.Rows.Add(row);
                        }
                    }
                }
            }
            if (gotSchema) results.Add(rs);
        }
        return results;
    }

    private static object GetValue(IArrowArray a, int i)
    {
        if (a == null) return null;
        if (a is DictionaryArray da)
        {
            // Resolve the dictionary index, then look up the value in the dictionary.
            int dictIndex;
            switch (da.Indices)
            {
                case Int32Array idx32: if (idx32.IsNull(i)) return null; dictIndex = idx32.GetValue(i).Value;       break;
                case Int16Array idx16: if (idx16.IsNull(i)) return null; dictIndex = idx16.GetValue(i).Value;       break;
                case Int8Array  idx8:  if (idx8.IsNull(i))  return null; dictIndex = idx8.GetValue(i).Value;        break;
                case Int64Array idx64: if (idx64.IsNull(i)) return null; dictIndex = (int)idx64.GetValue(i).Value;  break;
                default: return da.Indices.ToString();
            }
            return GetValue(da.Dictionary, dictIndex);
        }
        if (a is StringArray sa)      return sa.GetString(i);
        if (a is BooleanArray ba)     return ba.IsNull(i) ? (object)null : ba.GetValue(i);
        if (a is Int64Array i64)      return i64.IsNull(i) ? (object)null : i64.GetValue(i);
        if (a is Int32Array i32)      return i32.IsNull(i) ? (object)null : i32.GetValue(i);
        if (a is DoubleArray d)       return d.IsNull(i)   ? (object)null : d.GetValue(i);
        if (a is Decimal128Array dec) return dec.GetValue(i);
        if (a is Date32Array d32)     return d32.GetDateTime(i);
        if (a is Date64Array d64)     return d64.GetDateTime(i);
        if (a is TimestampArray ts)   return ts.GetTimestamp(i);
        return a.ToString();
    }
}
"@

$results = [DaxMultiResultReader]::ReadAll($memoryStream)
Write-Host "Received $($results.Count) result sets."

5 - Arbejd med hvert resultatsæt

Konverter hvert resultatsæt til PSCustomObject rækker. Nu kan du sende rækkerne gennem Where-Object, Group-Object, Export-Csv, eller en hvilken som helst anden PowerShell-cmdlet.

function ConvertTo-PSObjectRows {
    param([Parameter(Mandatory)] $ResultSet)
    foreach ($row in $ResultSet.Rows) {
        $obj = [ordered]@{}
        foreach ($col in $ResultSet.ColumnNames) { $obj[$col] = $row[$col] }
        [PSCustomObject]$obj
    }
}

$rowCount    = ConvertTo-PSObjectRows -ResultSet $results[0]
$topProducts = ConvertTo-PSObjectRows -ResultSet $results[1]
$yearTotals  = ConvertTo-PSObjectRows -ResultSet $results[2]

$rowCount    | Format-Table
$topProducts | Format-Table
$yearTotals  | Format-Table

Hver variabel indeholder rækkerne fra den tilsvarende EVALUATE sætning, i den rækkefølge som sætningerne optræder i anmodningen.

Fejlfinding

  • 401 Unauthorized — Den cachede token udløb. Kør Connect-PowerBIServiceAccount igen for at opdatere den, og læs $accessToken så fra Get-PowerBIAccessToken.
  • MSAL-advarsler under Connect-PowerBIServiceAccount — MicrosoftPowerBIMgmt bundler en ældre MSAL.NET, der udsender interne sporingsbeskeder (for eksempel SetAuthorityUri, TryNormalizeRealm, MsaDeviceOperationProvider is not available) med advarselssvårhedsgrad. De er sikre at ignorere, så længe cmdlet'en printer blokkenEnvironmentUserName / TenantId / . For at undertrykke dem, overhal -WarningAction SilentlyContinue.
  • HTTP 200 med et fejlresultatsæt — HTTP-anmodningen lykkedes, men pilstrømmen indeholder en fejl. Inspicer skemametadata for IsError=true, og læs FaultCode og FaultString. For detaljer, se Best practices for Execute DAX Queries REST API.
  • Invoke-RestMethod returnerer forvansket tekst — Brug ikke Invoke-RestMethod, Invoke-PowerBIRestMethod, eller Invoke-WebRequest med dette API. Svaret er binært; HttpWebRequest Brug som vist i trin 3.
  • Add-Type fejler i at indlæse Apache.Arrow.dll — På Windows PowerShell 5.1 konflikter pakken Apache.Arrow med den indbyggede System.Memory assembly. Brug PowerShell 7.4 eller nyere.
  • Ingen eller færre resultatsæt returneret end EVALUATE udsagn — Bekræft, at hver EVALUATE sætning er syntaktisk gyldig i sig selv. En enkelt ugyldig EVALUATE fejl får API'et til at returnere en fejl i stedet for et delvist multi-resultat-sæt svar.

Relateret indhold

  • Last updated on