Reference til GQL-forespørgsels-API

Kør GQL-forespørgsler mod egenskabsgrafer i Microsoft Fabric ved hjælp af en RESTful HTTP-API. I denne reference beskrives HTTP-kontrakten: anmodnings- og svarformater, godkendelse, JSON-resultatkodning og fejlhåndtering.

Oversigt

GQL-forespørgsels-API'en er et enkelt slutpunkt (RPC via HTTP), der accepterer GQL-forespørgsler som JSON-nyttedata og returnerer strukturerede, indtastede resultater. API'en er tilstandsløs, håndterer godkendelse og leverer omfattende fejlrapportering.

Nøglefunktioner

• Enkelt slutpunkt – Alle handlinger bruger HTTP POST til én URL-adresse.
• JSON-baseret – nyttedata for anmodninger og svar bruger JSON med omfattende kodning af indtastede GQL-værdier.
• Stateless – Der kræves ingen sessionstilstand mellem anmodninger.
• Type safe – Stærk, GQL-kompatibel indtastning med diskriminerede fagforeninger for værdirepræsentation.

Forudsætninger

• Du skal bruge en graf i Microsoft Fabric, der indeholder data – herunder noder og kanter (relationer). Se grafens hurtige start for at oprette og indlæse en eksempelgraf.
• Du bør være bekendt med egenskabsgrafer og en grundlæggende forståelse af GQL, herunder strukturen af udførelsesresultater og resultater.
• Du skal installere og konfigurere Azure CLI-værktøjetaz for at logge på din organisation. Kommandolinjeeksempler i denne artikel forudsætter brug af en POSIX-kompatibel kommandolinje shell, f.eks. bash.

Godkendelse

GQL-forespørgsels-API'en kræver godkendelse via ihændehavertokens.

Medtag dit adgangstoken i godkendelsesheaderen for hver anmodning:

Authorization: Bearer <your-access-token>

Generelt kan du hente ihændehavertokens ved hjælp af Microsoft Authentication Library (MSAL) eller andre godkendelsesflows, der er kompatible med Microsoft Entra.

Ihændehavertokens opnås ofte via to overordnede stier:

Brugerdelegeret adgang

Du kan hente ihændehavertokens til brugerdelegerede tjenestekald fra kommandolinjen via Azure CLI-værktøjetaz,

Hent et ihændehavertoken for brugerdelegerede kald fra kommandolinjen ved at:

• Kør az login
• Derpå az account get-access-token --resource https://api.fabric.microsoft.com

Dette bruger Azure CLI-værktøjetaz.

Når du bruger az rest til at udføre anmodninger, hentes ihændehavertokens automatisk.

Programadgang

Du kan hente ihændehavertokens til programmer, der er registreret i Microsoft Entra. Du kan finde flere oplysninger i Den hurtige introduktion til Fabric API .

API-slutpunkt

API'en bruger et enkelt slutpunkt, der accepterer alle forespørgselshandlinger:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true

Hvis du vil hente {workspaceId} for dit arbejdsområde, kan du få vist alle tilgængelige arbejdsområder ved hjælp af az rest:

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

Hvis du vil hente {graphId}, kan du få vist alle tilgængelige grafer i et arbejdsområde ved hjælp af az rest:

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels"

Du kan bruge flere parametre til yderligere at indsnævre forespørgselsresultater:

• --query 'value[?displayName=='My Workspace'] til kun at vise elementer med en displayName af My Workspace.
• --query 'value[starts_with(?displayName='My')] til kun at vise elementer, hvis displayName starter med My.
• --query '{query}' til kun at vise elementer, der svarer til den angivne JMESPath {query}. Se dokumentationen til Azure CLI på JMESPath vedrørende den understøttede syntaks for {query}.
• -o table til at producere et tabelresultat.

Anmodningsoverskrifter

Anmodningsformat

Alle anmodninger bruger HTTP POST med en JSON-nyttedata.

Grundlæggende anmodningsstruktur

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

Anmod om felter

Svarformat

Alle svar på vellykkede anmodninger bruger HTTP 200-status med JSON-nyttedata, der indeholder udførelsesstatus og resultater.

Svarstruktur

{
  "status": {
    "code": "00000",
    "description": "note: successful completion", 
    "diagnostics": {
      "OPERATION": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Statusobjekt

Hvert svar indeholder et statusobjekt med udførelsesoplysninger:

Statuskoder

Statuskoder følger et hierarkisk mønster:

• 00xxxx - Fuldførelse af succes
• 01xxxx - Lykkedes med advarsler
• 02xxxx – Lykkedes uden data
• 03xxxx - Succes med oplysninger
• 04xxxx og højere – fejl- og undtagelsesbetingelser

Du kan få flere oplysninger i referencen til GQL-statuskoder.

Diagnosticeringsposter

Diagnosticeringsposter kan indeholde andre nøgleværdipar, der yderligere angiver statusobjektet. Taster, der starter med et understregningstegn (_), er specifikke for grafen for Microsoft Fabric. GQL-standarden foreskriver alle andre nøgler.

Årsager

Statusobjekter omfatter et valgfrit cause felt, når en underliggende årsag er kendt.

Andre statusobjekter

Nogle resultater kan rapportere andre statusobjekter som en liste i feltet (valgfrit). additionalStatuses

Hvis det er tilfældet, bestemmes det primære statusobjekt altid for at være det mest kritiske statusobjekt (f.eks. en undtagelsesbetingelse) som foreskrevet i GQL-standarden.

Resultattyper

Resultaterne bruger et forskelsbehandling foreningsmønster med feltet kind :

Tabelresultater

For forespørgsler, der returnerer tabeldata:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT32",
      "jsonType": "number"
    }
  ],
  "isOrdered": true,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Udeladte resultater

For handlinger, der ikke returnerer data (f.eks. katalog- og/eller dataopdateringer):

{
  "kind": "NOTHING"
}

Værdityper og kodning

API'en bruger et avanceret typesystem til at repræsentere GQL-værdier med præcis semantik. JSON-formatet for GQL-værdier følger et diskrimineret foreningsmønster.

Værdistruktur

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

Primitive typer

Numeriske typer

Heltalstyper

Store heltal uden for JavaScripts sikre område (-9.007.199.254.740.991 til 9.007.199.254.740.991) serialiseres som strenge:

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

Flydende taltyper

Flydende tal-værdier understøtter IEEE 754-specialværdier:

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

Tidsmæssige typer

Understøttede tidsmæssige typer bruger ISO 8601-strengformater:

Referencetyper for grafelementer

Komplekse typer

De komplekse typer består af andre GQL-værdier.

Lister

Lister indeholder matrixer med værdier, der kan være null, med ensartede elementtyper:

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

Særlige listetyper:

• LIST<ANY> – Blandede typer (hvert element indeholder oplysninger om fuld type)
• LIST<NULL> - Der må kun angives null-værdier
• LIST<NOTHING> - Altid tom matrix

Stier

Stier kodes som lister over referenceværdier for grafelementer.

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

Se Optimering af tabel serialisering.

Optimering af tabel serialisering

I forbindelse med tabelresultater optimeres værdi serialisering baseret på oplysninger om kolonnetype:

• Kendte typer – Kun råværdien serialiseres
• ANY columns – objekt med fuld værdi med typediskriminator

{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Fejlhåndtering

Transportfejl

Netværksfejl og HTTP-transportfejl resulterer i standard-HTTP-fejlstatuskoder (4xx, 5xx).

Programfejl

Fejl på programniveau returnerer altid HTTP 200 med fejloplysninger i statusobjektet:

{
  "status": {
    "code": "42001",
    "description": "error: syntax error or access rule violation",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_errorLocation": {
        "gqlType": "STRING",
        "value": "line 1, column 15"
      }
    },
    "cause": {
      "code": "22007",
      "description": "error: data exception - invalid date, time, or, datetime
format",
      "diagnostics": {
        "OPERATION": "query",
        "OPERATION_CODE": "0",
        "CURRENT_SCHEMA": "/"
      }
    }
  }
}

Statuskontrol

Hvis du vil finde ud af, om det lykkedes, skal du kontrollere statuskoden:

• Koder, der starter med 00, 01, 02, angiver, 03 om det lykkedes (med mulige advarsler)
• Alle andre koder angiver fejl

Komplet eksempel med az rest

Kør en forespørgsel ved hjælp af az rest kommandoen for at undgå at skulle hente ihændehavertokens manuelt, f.eks.:

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

Komplet eksempel med krøller

I eksemplet i dette afsnit bruges værktøjet curl til at udføre HTTPS-anmodninger fra shell.

Vi antager, at du har et gyldigt adgangstoken gemt i en shellvariabel, f.eks.:

export ACCESS_TOKEN="your-access-token-here"

Kør en forespørgsel på følgende måde:

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

Bedste praksis

Følg disse bedste fremgangsmåder, når du bruger GQL-forespørgsels-API'en.

Fejlhåndtering

• Kontrollér altid statuskoder – Antag ikke, at det lykkedes baseret på HTTP 200.
• Fortolkning af fejloplysninger – Brug diagnosticering og årsagskæder til fejlfinding.

Security

• Brug HTTPS – Send aldrig godkendelsestokens over ukrypterede forbindelser.
• Roter tokens – Implementer korrekt tokenopdatering og udløbshåndtering.
• Valider input – Sanitize og escaper korrekt alle brugerindgivne forespørgselsparametre, der sprøjtes ind i forespørgslen.

Værdirepræsentation

• Håndter store heltalsværdier – Heltal kodes som strenge, hvis de ikke kan repræsenteres som JSON-tal oprindeligt.
• Håndter specielle flydende talværdier – Flydende talværdier, der returneres fra forespørgsler, kan være Infinityværdier af typen , -Infinityeller NaN (ikke et tal).
• Handle null-værdier – JSON null repræsenterer GQL null.

Relateret indhold

• Grafér datamodeller
• GQL-sprogvejledning
• GQL-værdier og værdityper
• Reference til GQL-statuskoder