API-referanse for GQL-spørring

Kjør GQL-spørringer mot egenskapsgrafer i grafen i Microsoft Fabric ved hjelp av en RESTful HTTP-API. Denne referansen beskriver HTTP-kontrakten: forespørsels- og svarformater, godkjenning, JSON-resultatkoding og feilbehandling.

Viktig!

Denne artikkelen bruker utelukkende eksempeldatasett for sosiale nettverk.

Oversikt

GQL Query API-en er ett enkelt endepunkt (RPC over HTTP) som godtar GQL-spørringer som JSON-nyttelaster og returnerer strukturerte, innskrevne resultater. API-en er tilstandsløs, håndterer godkjenning og gir omfattende feilrapportering.

Hovedfunksjoner

  • Enkelt endepunkt – Alle operasjoner bruker HTTP POST til én URL-adresse.
  • JSON-basert – Nyttelaster for forespørsel og svar bruker JSON med rik koding av innskrevne GQL-verdier.
  • Stateless – ingen økttilstand kreves mellom forespørsler.
  • Skriv sikker - Sterk, GQL-kompatibel skriving med diskriminerte fagforeninger for verdirepresentasjon.

Forutsetning

Autentisering

GQL Query API krever godkjenning via bærertokener.

Inkluder tilgangstokenet i autorisasjonshodet for alle forespørsler:

Authorization: Bearer <your-access-token>

Generelt kan du skaffe bærertokener ved hjelp av Microsoft Authentication Library (MSAL) eller andre godkjenningsflyter som er kompatible med Microsoft Entra.

Bærertokener oppnås vanligvis gjennom to hovedbaner:

Brukerdelegert tilgang

Du kan hente bærertokener for brukerdelegerte tjenestekall fra kommandolinjen via Azure CLIverktøyet az.

Få et bærertoken for brukerdelegerte anrop fra kommandolinjen ved å:

  • Kjøre az login
  • Da az account get-access-token --resource https://api.fabric.microsoft.com

Dette bruker verktøyet Azure CLIaz.

Når du bruker az rest til å utføre forespørsler, hentes bærertokener automatisk.

Programtilgang

Du kan skaffe bærertokener for programmer som er registrert i Microsoft Entra. Se hurtigstart for Fabric API for mer informasjon.

API-endepunkt

API-en bruker ett enkelt endepunkt som godtar alle spørringsoperasjoner:

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

Hvis du vil hente {workspaceId} arbeidsområdet, kan du vise alle tilgjengelige arbeidsområder ved hjelp av az rest:

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

Hvis du vil skaffe {graphId}deg , kan du vise alle tilgjengelige grafer i et arbeidsområde ved hjelp av az rest:

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

Du kan bruke flere parametere til å begrense spørringsresultatene ytterligere:

  • --query 'value[?displayName=='My Workspace'] for å vise bare elementer med en displayName av My Workspace.
  • --query 'value[starts_with(?displayName='My')] for å vise bare elementer som displayName starter med My.
  • --query '{query}' for å vise bare elementer som samsvarer med den angitte JMESPath {query}. Se dokumentasjonen Azure CLI på JMESPath angående den støttede syntaksen for {query}.
  • -o table for å produsere et tabellresultat.

Note

Se delen om hvordan du bruker az-rest eller inndelingen om hvordan du utfører spørringer via API-endepunktet fra et kommandolinjeskall.

Forespørselshoder

Hode Verdi Required
Content-Type application/json Ja
Accept application/json Ja
Authorization Bearer <token> Ja

Forespørselsformat

Alle forespørsler bruker HTTP POST med en JSON-nyttelast.

Grunnleggende forespørselsstruktur

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

Forespørselsfelt

Felt Type Required Beskrivelse
query streng Ja GQL-spørringen som skal kjøres

Svarformat

Alle svar for vellykkede forespørsler bruker HTTP 200-status med JSON-nyttelast som inneholder utførelsesstatus og resultater.

Responsstruktur

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

Statusobjekt

Hvert svar inkluderer et statusobjekt med kjøringsinformasjon:

Felt Type Beskrivelse
code streng Statuskode på seks tegn (0000000 = vellykket)
description streng Statusmelding som kan leses av mennesker
diagnostics objekt Detaljerte diagnoseposter
cause objekt Valgfritt underliggende årsaksstatusobjekt

Statuskoder

Statuskoder følger et hierarkisk mønster:

  • 00xxxx – Fullført suksess
  • 01xxxx – Vellykket med advarsler
  • 02xxxx – Vellykket uten data
  • 03xxxx – Vellykket med informasjon
  • 04xxxx og høyere – feil og unntaksbetingelser

Hvis du vil ha mer informasjon, kan du se referansen for GQL-statuskoder.

Diagnoseposter

Diagnoseposter kan inneholde andre nøkkelverdipar som nærmere beskriver statusobjektet. Taster som starter med et understrekingstegn (_) er spesifikke for grafen. GQL-standarden foreskriver alle andre nøkler.

Note

Verdier i diagnoseposten for nøkler som er spesifikke for grafen, er JSON-kodede GQL-verdier. Se verdityper og koding.

Årsaker

Statusobjekter inkluderer et valgfritt cause felt når en underliggende årsak er kjent.

Andre statusobjekter

Noen resultater kan rapportere andre statusobjekter som en liste i (valgfritt) additionalStatuses feltet.

I så fall er det primære statusobjektet alltid fastslått å være det mest kritiske statusobjektet (for eksempel en unntaksbetingelse) som foreskrevet av GQL-standarden.

Resultattyper

Resultatene bruker et diskriminert unionsmønster med feltet kind :

Tabellresultater

For spørringer som returnerer tabelldata:

{
  "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
    }
  ]
}

Utelatte resultater

For operasjoner som ikke returnerer data (for eksempel katalog- og/eller dataoppdateringer):

{
  "kind": "NOTHING"
}

Verdityper og koding

API-en bruker et rikt typesystem til å representere GQL-verdier med presise semantikk. JSON-formatet med GQL-verdier følger et diskriminert unionsmønster.

Note

JSON-formatet med tabellresultater innser det diskriminerte unionsmønsteret ved å gqlType skille og value oppnå en mer kompakt representasjon. Se optimaliseringsoptimalisering for tabell.

Verdistruktur

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

Primitive typer

GQL-type Eksempel Beskrivelse
BOOL {"gqlType": "BOOL", "value": true} Opprinnelig JSON boolsk
STRING {"gqlType": "STRING", "value": "Hello"} UTF-8-streng

Numeriske typer

Heltallstyper

GQL-type Område JSON Serialisering Eksempel
INT64 -2⁶³ til 2⁶³-1 Tall eller streng* {"gqlType": "INT64", "value": -9237}
UINT64 0 til 2⁶⁴-1 Tall eller streng* {"gqlType": "UINT64", "value": 18467}

Store heltall utenfor JavaScripts sikre område (-9 007 199 254 740 991 til 9 007 199 254 740 991) serialiseres som strenger:

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

Flyttallstyper

GQL-type Område JSON Serialisering Eksempel
FLOAT64 IEEE 754 binær64 JSON-nummer eller -streng {"gqlType": "FLOAT64", "value": 3.14}

Flyttallsverdier støtter IEEE 754 spesialverdier:

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

Tidstyper

Støttede tidstyper bruker ISO 8601-strengformater:

GQL-type Format Eksempel
ZONED DATETIME ÅÅÅÅÅ-MM-DDTHH:MM:SS[.ffffff]±HH:MM {"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}

Referansetyper for grafelement

GQL-type Beskrivelse Eksempel
NODE Referanse for grafnode {"gqlType": "NODE", "value": "node-123"}
EDGE Referanse for grafkant {"gqlType": "EDGE", "value": "edge_abc#def"}

Komplekse typer

De komplekse typene består av andre GQL-verdier.

Lister

Lister inneholder matriser med verdier som kan nullstilles med konsekvente elementtyper:

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

Spesielle listetyper:

  • LIST<ANY> – Blandede typer (hvert element inneholder fullstendig typeinformasjon)
  • LIST<NULL> – Bare nullverdier er tillatt
  • LIST<NOTHING> – Alltid tom matrise

Baner

Baner kodes som lister over referanseverdier for grafelementer.

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

Se optimaliseringsoptimalisering for tabell.

Optimalisering av tabellserier

For tabellresultater er verdiserieisering optimalisert basert på kolonnetypeinformasjon:

  • Kjente typer – bare råverdien serialiseres
  • ALLE kolonner – Objekt med full verdi med typediskriminator
{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Feilbehandling

Transportfeil

Nettverks- og HTTP-transportfeil resulterer i standard HTTP-feilstatuskoder (4xx, 5xx).

Programfeil

Feil på programnivå returnerer alltid HTTP 200 med feilinformasjon 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": "/"
      }
    }
  }
}

Statuskontroll

Hvis du vil finne ut hvordan du lykkes, kontrollerer du statuskoden:

  • Koder som starter med 00, 01, 0203 angir vellykket (med mulige advarsler)
  • Alle andre koder indikerer feil

Komplett eksempel med az rest

Kjør en spørring ved hjelp av az rest kommandoen for å unngå å måtte hente bærertokener manuelt, slik som dette:

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

Komplett eksempel med krøll

Eksemplet i denne delen bruker curl verktøyet til å utføre HTTPS-forespørsler fra skallet.

Vi antar at du har et gyldig tilgangstoken lagret i en skallvariabel, slik som dette:

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

Tips

Se delen om godkjenning for hvordan du får et gyldig bærertoken.

Kjør en spørring på samme måte:

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

Anbefalte fremgangsmåter

Følg disse anbefalte fremgangsmåtene når du bruker GQL Query-API-en.

Feilbehandling

  • Kontroller alltid statuskoder – Ikke anta vellykket basert på HTTP 200.
  • Analyser feildetaljer – Bruk diagnostikk og forårsake kjeder for feilsøking.

Security

  • Bruk HTTPS – Send aldri godkjenningstokener over ukrypterte tilkoblinger.
  • Roter tokener – Implementere riktig tokenoppdatering og utløpshåndtering.
  • Valider inndata – Sanitize og unnslippe alle brukerdefinerte spørringsparametere som settes inn i spørringen.

Verdipresentasjon

  • Håndter store heltallsverdier – Heltall kodes som strenger hvis de ikke kan representeres som JSON-tall opprinnelig.
  • Håndter spesielle flyttallsverdier – flyttallsverdier som returneres fra spørringer, kan være Infinityverdier , -Infinityeller NaN (ikke et tall).
  • Håndter nullverdier – JSON null representerer GQL null.

Beslektet innhold

  • Last updated on