Veiledning: Kjør flere SEEVALU-setninger med PowerShell

I denne veiledningen bruker du PowerShell til å sende inn en enkelt Execute DAX Queries REST API-forespørsel som inneholder flere EVALUATE setninger, og deretter parser du Apache Arrow-svaret med flere resultater. Dette mønsteret lar deg hente flere relaterte resultatsett i én rundtur fra et PowerShell-automatiseringsskript.

Diagram som viser én HTTP POST-forespørsel som inneholder tre EVALUATE-setninger i spørringskroppen, og Arrow IPC-svaret som inneholder tre resultatsett i samme rekkefølge.

Hvorfor sende inn flere EVALUATE-erklæringer i én forespørsel

Execute DAX Queries API aksepterer en enkelt query streng som kan inneholde flere EVALUATE setninger. Hvert statement returnerer sitt eget resultatsett, og responskroppen er sammenkoblingen av én Arrow IPC-strøm per EVALUATE statement i deklarasjonsrekkefølge. Å sende relaterte spørringer sammen unngår overhead per forespørsel ved separate HTTP-kall, inkludert ekstra Microsoft Entra-tokenvalidering og DAX-motorinitialisering. Å sende flere EVALUATE setninger i én forespørsel kan også bidra til å dempe virkningen av forespørselsbegrensning. Power BI begrenser innkallere til 120 spørringsforespørsler per minutt per bruker for spørringsoperasjoner med semantiske modeller.

Hva du bygger

I ett PowerShell-skript gjør du:

  1. Skaff deg en Microsoft Entra-tilgangstoken.
  2. Bygg en forespørselskropp som query inneholder tre EVALUATE setninger.
  3. Send forespørselen og fang den rå Arrow IPC-responsstrømmen.
  4. Analyser svaret i ett resultatsett per EVALUATE utsagn.
  5. Vis hvert resultatsett som PowerShell-objekter.

Forutsetninger

  • PowerShell 7.4 eller nyere. Windows PowerShell 5.1 støttes ikke fordi Apache.Arrow pakken som brukes i denne veiledningen er i konflikt med System.Memory assembleren som følger med PowerShell 5.1.
  • Et Power BI-arbeidsområde på Premium- eller Fabric-kapasitet med minst én semantisk modell.
  • Bygge- og lesetillatelser på den semantiske modellen.
  • MicrosoftPowerBIMgmt-modulen for autentisering. Cmdletene bruker Microsoft sin førsteparts Power BI-klientapp, så du trenger ikke å registrere din egen app i Microsoft Entra.
  • Apache.Arrow og Apache.Arrow.Compression .NET-bibliotekene for å deserialisere responsen. Execute DAX Queries REST API komprimerer Arrow-buffere med LZ4-rammekomprimering, så Apache.Arrow.Compression og dens avhengigheter (K4os.Compression.LZ4, K4os.Compression.LZ4.Streams, K4os.Hash.xxHash, ZstdSharp.Port) er nødvendige. Neste steg viser hvordan du laster dem ned.
  • Følgende leietakerinnstillinger aktivert i Power BI-administrasjonsportalen:
    • Dataset Execute Queries REST API (under utviklerinnstillinger).
    • Tillat XMLA-endepunkter og analyser i Excel med on-premises semantiske modeller (under Integrasjonsinnstillinger).

Installer PowerShell 7.4 eller nyere ved å bruke winget:

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

Etter installasjon lanseres det nye skallet med pwsh. Kjør de resterende kommandoene i denne veiledningen fra den økten.

Installer MicrosoftPowerBIMgmt-modulen. Flagget -Force aksepterer PowerShell Gallery untrusted-repository-prompten.

Install-Module -Name MicrosoftPowerBIMgmt -Scope CurrentUser -Force

Last ned de nødvendige NuGet-pakkene og pakk ut deres sammensetninger til C:\Tools\Apache.Arrow\. En fil er et ZIP-arkiv, så Expand-Archive den .nupkg fungerer direkte på den. Løkken velger den høyeste netX.0 målmappen i hver pakke slik at samlingene forblir kompatible når pakkene publiserer 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 - Autentiserer

Logg inn interaktivt på Power Bi-tjeneste, og hent deretter ut en tilgangstoken. CMDLET-en Connect-PowerBIServiceAccount krever ikke at du registrerer din egen app i Microsoft Entra.

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

2 - Bygg en forespørsel med flere EVALUATE-setninger

Definer arbeidsområdet og de semantiske modellmålene. Deretter bygger du forespørselskroppen. Egenskapen query er en enkelt streng som inneholder tre EVALUATE setninger adskilt av blanke 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 forespørselen og fang den rå responsstrømmen

Send POST-forespørselen, og les svaret som en binær strøm. Bruk HttpWebRequest i stedet for Invoke-RestMethod, Invoke-PowerBIRestMethod, eller Invoke-WebRequest. Svaret er en binær Arrow IPC-strøm. De høyere PowerShell-cmdletene tolker svarkropper som tekst, noe som korrumperer binært innhold. HttpWebRequest returnerer råstrømmen uendret.

$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 - Analyser responsen med flerresultatsett

Responsorganet er sammenslåingen av én Apache Arrow IPC-strøm per EVALUATE uttalelse. PowerShell leveres ikke med en Arrow-parser, så dette steget laster inn .NET-biblioteket Apache.Arrow gjennom en liten innebygd C#-hjelper lagt til med Add-Type. Å holde stream-loop-logikken i C# holder kallstedet kort og returnerer en liste med resultatsett som PowerShell-skriptet ditt kan iterere. Hjelperen åpner en ny ArrowStreamReader etter hver end-of-stream-markør, slik at den samme løkken håndterer et vilkårlig antall resultatsett i responsen.

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 - Arbeid med hvert resultatsett

Konverter hvert resultatsett til PSCustomObject rader. Nå kan du sende radene gjennom Where-Object, Group-Object, Export-Csv, eller en hvilken som helst annen 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 inneholder radene fra den tilsvarende EVALUATE setningen, i den rekkefølgen setningene vises i forespørselen.

Feilsøking

  • 401 Unauthorized — Den bufrede tokenen utløp. Kjør Connect-PowerBIServiceAccount igjen for å oppdatere den, og les $accessToken deretter på nytt fra Get-PowerBIAccessToken.
  • MSAL-varsler under Connect-PowerBIServiceAccount — MicrosoftPowerBIMgmt bundler en eldre MSAL.NET som sender ut interne sporingsmeldinger (for eksempel SetAuthorityUri, TryNormalizeRealm, MsaDeviceOperationProvider is not available) ved advarselsalvorlighetsgrad. De er trygge å ignorere så lenge cmdleten skriver ut blokkenEnvironmentUserName / TenantId / . For å undertrykke dem, passer -WarningAction SilentlyContinue.
  • HTTP 200 med et feilresultatsett — HTTP-forespørselen lyktes, men Arrow-strømmen bærer en feil. Inspiser skjemametadataene for IsError=true, og les FaultCode og FaultString. For detaljer, se Beste praksis for Execute DAX Queries REST API.
  • Invoke-RestMethod returnerer utydelig tekst — Ikke bruk Invoke-RestMethod, Invoke-PowerBIRestMethod, eller Invoke-WebRequest med dette API-et. Svaret er binært; Bruk HttpWebRequest som vist i steg 3.
  • Add-Type Feiler å laste Apache.Arrow.dll — På Windows PowerShell 5.1 Apache.Arrow kolliderer pakken med assemblersamlingen i innboksenSystem.Memory. Bruk PowerShell 7.4 eller nyere.
  • Ingen eller færre resultatsett returnerte enn EVALUATE setninger — Bekreft at hver EVALUATE setning er syntaktisk gyldig for seg selv. En enkelt ugyldig EVALUATE melding får API-et til å returnere en feil i stedet for et delvis svar med flere resultater.

Relatert innhold

  • Last updated on