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 eksponerer et REST-endepunkt som aksepterer GQL-spørringer som JSON-payloads og returnerer strukturerte, typede resultater. Den støtter continuation polling for spørringer som ikke fullføres under den første forespørselen.

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.
  • Fortsettelsespolling – Langvarige spørringer kan fortsette på tvers av flere HTTP-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?beta=true

Query API er i beta og anbefales ikke for produksjonsbruk. Sett den nødvendige beta spørringsparameteren til true. Den eldre preview=true parameteren støttes fortsatt for bakoverkompatibilitet, men brukes beta=true for nye integrasjoner.

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 {graphModelId}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 Azure CLI-utdataalternativer for å filtrere eller formatere svarene fra disse listeforespørslene. Disse alternativene kjører i Azure CLI-klienten; de er ikke Query API-parametere:

  • --query "value[?displayName=='My Workspace']" lister kun opp elementer med a displayName av My Workspace.
  • --query "value[?starts_with(displayName, 'My')]" lister kun opp elementer som displayName starter med My.
  • --query "{query}" lister kun gjenstander som samsvarer med den oppgitte JMESPath {query}. Se Query Azure CLI-kommandoresultater for den støttede syntaksen.
  • -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.

Spørringsparametere

Parameteren Type Required Beskrivelse
beta boolsk Ja Sett til true å bruke beta Query API.
continuationToken streng Nei Token fra result.nextPage når en spørring fortsatt kjører. Send inn samme forespørselstekst når du bruker tokenet.

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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Statusobjekt

Hvert svar inkluderer et statusobjekt med kjøringsinformasjon:

Felt Type Beskrivelse
code streng Fem-tegns offentlig API-statuskode.
description streng Menneskelesbar statusbeskrivelse.
diagnostics objekt Detaljert diagnostisk opptegnelse, inkludert den kanoniske spørringsmotoren GQLSTATUS når tilgjengelig.
cause objekt Valgfritt underliggende årsaksstatusobjekt.

Statuskoder

Den primære status.code bruker disse offentlige API-kategoriene:

  • 00000 - Vellykket fullføring med minst én rad.
  • 00001 - Vellykket fullføring med utelatt resultat. Reservert for fremtidig DDL- og DML-støtte.
  • 01000 - Advarsel eller informasjonsbetingelse.
  • 02000 - Ingen rader er for øyeblikket tilgjengelige fra en radproduserende spørring.
  • 42000 - Syntaks-, tilgangsregel eller annen brukerkorrigerbar spørringsfeil.
  • 50000 - System- eller uklassifisert feil.

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

Diagnostikken _graphaneGqlStatus inneholder den kanoniske fem-tegns GQLSTATUS rapportert av spørringsmotoren. Hvert underscore-prefiks diagnostisk medlem inneholder enten null eller en JSON-kodet GQL-verdi. For eksempel _graphaneGqlStatus bruker STRING, mens feilklassifiseringsdiagnostikk bruker BOOL. 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 det valgfrie additionalStatuses feltet.

Primærstatusen er den mest kritiske registrerte tilstanden. Hver ekstra status og nestede årsak har sin egen offentlige API-kode og kanoniske GQLSTATUS-diagnose.

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": "INT64",
      "jsonType": "number|string"
    }
  ],
  "isOrdered": false,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Langvarige spørringer

Hvis en spørring ikke fullføres under den nåværende HTTP-forespørselen, returnerer API-et HTTP 200 med offentlig statuskode 02000, en tom tabell og en nextPage token:

{
  "status": {
    "code": "02000",
    "description": "No data available, retry with continuation token"
  },
  "result": {
    "kind": "TABLE",
    "columns": [],
    "data": [],
    "nextPage": "{continuationToken}"
  }
}

Poll for fullføring ved å sende samme forespørselskropp og legge til tokenet i URL-en:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true&continuationToken={continuationToken}

Behandle nextPage som en ugjennomsiktig verdi. Prosentkoder den nøyaktig én gang i henhold til RFC 3986 før du bruker den som continuationToken spørringsparameterverdi. Ikke dekod, inspiser eller modifiser tokenet.

Fortsett til svaret ikke lenger inneholder nextPage. Spørringsutførelsen kan fortsette i opptil 20 minutter fra den første forespørselen. Hvis den overstiger denne totale varigheten, returnerer API-et HTTP 408 med feilkode QueryTimeout.

Avkortede resultater

Grafen avkorter et spørringssvar når dens interne binære representasjon overstiger 64 MB. API-et returnerer radene som passer og legger til en status til additionalStatuses. Den tilleggsstatusen bruker offentlig kode 01000 og bevarer kanonisk GQLSTATUS 01M11 i _graphaneGqlStatus.

Trunkering gir ikke en nextPage token for de utelatte radene. Avgrens spørringen med filtre, spesifikke projeksjoner, eller LIMIT, og kjør den deretter igjen.

Utelatte resultater

Responsskjemaet kan representere en operasjon hvis utsagn aldri produserer rader, uavhengig av data eller evalueringsresultat. Dette utfallet bruker statuskode 00001:

{
  "kind": "NOTHING"
}

Dette utelatte resultatet skiller seg fra en tabell uten rader. En tom tabell er resultatet av å evaluere en radproduserende spørring som for øyeblikket ikke har rader å returnere.

Graph reserverer denne resultatformen og statuskoden for fremtidig støtte for datadefinisjonsspråk (DDL) og datamanipulasjonsspråk (DML). Nåværende spørringssetninger returnerer alltid tabellresultater.

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
{
  "kind": "TABLE",
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "amount", "gqlType": "INT64", "jsonType": "number|string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "object"}
  ],
  "data": [
    {
      "name": "Alice",
      "amount": "123",
      "mixed": {"gqlType": "INT64", "value": "1"}
    }
  ]
}

Feilbehandling

Transportfeil

HTTP-status og GQL-status beskriver ulike lag av responsen:

HTTP-status Betydning
200 API-et behandlet forespørselen. Inspect status.code fordi resultatet kan representere suksess, ingen rader, en spørring som fortsatt pågår, eller en brukerkorrigerbar spørringsfeil.
408 Spørringsutførelsen oversteg den totale timeouten på 20 minutter. Feilkoden er QueryTimeout.
429 Grensen for tjenestesats ble overskredet. Vent på varigheten i Retry-After headeren før du prøver på nytt.
499 Innringeren kansellerte forespørselen. Feilkoden er ClientCancelled.
Andre 4xx eller 5xx Forespørselen eller tjenesten feilet før den returnerte et GQL-utførelsesresultat. Sjekk HTTP-feilresponsen.

Programfeil

En feil på applikasjonsnivå kan returnere HTTP 200 med feilinformasjon i statusobjektet. For eksempel bruker divisjon med null den offentlige API-koden 42000 og bevarer kanonisk GQLSTATUS 22012 i diagnoseposten:

{
  "status": {
    "code": "42000",
    "description": "error: data exception - division by zero",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "22012"
      },
      "_graphaneIsUserError": {
        "gqlType": "BOOL",
        "value": true
      },
      "_graphaneIsTransientError": {
        "gqlType": "BOOL",
        "value": false
      }
    }
  }
}

Statuskontroll

For å avgjøre det brede utfallet, sjekk publikum status.code. Bruk _graphaneGqlStatus når applikasjonen din trenger å skille en spesifikk spørringsmotorbetingelse, som numerisk overløp (22003) fra divisjon med null (22012).

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?beta=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?beta=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 input – Valider og fjern korrekt alle brukeroppgitte verdier som applikasjonen din setter inn i spørringsteksten.

Verdipresentasjon

  • Håndter store heltallsverdier – Heltall kodes som strenger hvis de ikke kan representeres som JSON-tall opprinnelig.
  • Håndter spesielle flyttallsverdier – API-et serialiserer positiv uendelig, negativ uendelig, ikke-ettall og minus null som "Inf", "-Inf", "NaN", og "-0".
  • Håndter nullverdier – JSON null representerer GQL null.

Beslektet innhold

  • Sist oppdatert