Reference til GQL-forespørgsels-API

Kør GQL-forespørgsler mod egenskabsgrafer i grafen 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.

Vigtigt

Denne artikel bruger udelukkende datasættet for eksempelgrafer på sociale netværk.

Oversigt

GQL Query API eksponerer et REST-endpoint, der accepterer GQL-forespørgsler som JSON-payloads og returnerer strukturerede, typede resultater. Den understøtter continuation polling for forespørgsler, der ikke afsluttes under den indledende anmodning.

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.
  • Continuation polling - Langvarige forespørgsler kan fortsætte på tværs af flere HTTP-forespørgsler.
  • Type safe – Stærk, GQL-kompatibel indtastning med diskriminerede fagforeninger for værdirepræsentation.

Forudsætninger

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 værktøjet Azure CLIaz.

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 værktøjet Azure CLIaz.

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

Programadgang

Du kan få ihændehavertokens for ansøgninger, 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?beta=true

Query API'en er i beta og anbefales ikke til produktionsbrug. Sæt den nødvendige beta forespørgselsparameter til .true Den ældre preview=true parameter understøttes fortsat for bagudkompatibilitet, men bruges beta=true til nye integrationer.

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 {graphModelId}, 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 Azure CLI-outputmuligheder til at filtrere eller formatere svarene fra disse listeanmodninger. Disse muligheder kører i Azure CLI-klienten; de er ikke Query API-parametre:

  • --query "value[?displayName=='My Workspace']" lister kun elementer med et displayName af My Workspace.
  • --query "value[?starts_with(displayName, 'My')]" lister kun elementer, hvis displayName starter med My.
  • --query "{query}" lister kun genstande, der matcher den angivne JMESPath {query}. Se Query Azure CLI-kommandoresultater for den understøttede syntaks.
  • -o table til at producere et tabelresultat.

Notat

Se afsnittet om brug af az-rest eller afsnittet om brug af krøller for at få oplysninger om, hvordan du udfører forespørgsler via API-slutpunktet fra en kommandolinje shell.

Forespørgselsparametre

Parameter Type Required Beskrivelse
beta boolesk Ja Sæt til true at bruge beta Query API'en.
continuationToken streng Nej Token fra result.nextPage , når en forespørgsel stadig kører. Indsend den samme forespørgselstekst, når du bruger tokenet.

Anmodningsoverskrifter

Overskrift Værdi Required
Content-Type application/json Ja
Accept application/json Ja
Authorization Bearer <token> Ja

Anmodningsformat

Alle anmodninger bruger HTTP POST med en JSON-nyttedata.

Grundlæggende anmodningsstruktur

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

Anmod om felter

Felt Type Required Beskrivelse
query streng Ja Den GQL-forespørgsel, der skal udføres

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

Statusobjekt

Hvert svar indeholder et statusobjekt med udførelsesoplysninger:

Felt Type Beskrivelse
code streng Fem tegn offentlig API-statuskode.
description streng Menneskeligt læsbar statusbeskrivelse.
diagnostics objekt Detaljeret diagnostisk optegnelse, inklusive den kanoniske forespørgselsmotor GQLSTATUS, når den er tilgængelig.
cause objekt Valgfrit underliggende årsagsstatusobjekt.

Statuskoder

Den primære status.code bruger disse offentlige API-kategorier:

  • 00000 - Vellykket gennemførelse med mindst én række.
  • 00001 - Vellykket gennemførelse med udeladt resultat. Reserveret til fremtidig DDL- og DML-support.
  • 01000 - Advarsel eller informationsbetingelse.
  • 02000 - Der er i øjeblikket ingen rækker tilgængelige fra en rækkeproducerende forespørgsel.
  • 42000 - Syntaks-, adgangsregel eller anden brugerkorrigerbar forespørgselsfejl.
  • 50000 - System- eller uklassificeret fejl.

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. GQL-standarden foreskriver alle andre nøgler.

Notat

Diagnosen _graphaneGqlStatus indeholder den kanoniske fem-tegns GQL-status, som forespørgselsmotoren rapporterer. Hvert underscore-præfikseret diagnostisk medlem indeholder enten null eller en JSON-kodet GQL-værdi. For eksempel _graphaneGqlStatus bruger STRING, mens fejlklassifikationsdiagnostik bruger BOOL. Se Værdityper og kodning.

Å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 det valgfrie additionalStatuses felt.

Primærstatus er den mest kritiske registrerede tilstand. Hver ekstra status og indlejret årsag har sin egen offentlige API-kode og kanoniske GQLSTATUS-diagnostik.

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

Langvarige forespørgsler

Hvis en forespørgsel ikke afsluttes under den nuværende HTTP-forespørgsel, returnerer API'en HTTP 200 med offentlig statuskode 02000, en tom tabel og et nextPage token:

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

Poll for fuldførelse ved at sende den samme anmodningstekst og tilføje tokenet til URL'en:

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

Behandl nextPage det som en uigennemsigtig værdi. Percent-encode det præcis én gang ifølge RFC 3986, før det bruges som continuationToken forespørgselsparameterværdi. Lad være med at dekode, inspicere eller ændre tokenet.

Fortsæt, indtil svaret ikke længere indeholder nextPage. Forespørgselsudførelsen kan fortsætte i op til 20 minutter fra den oprindelige anmodning. Hvis den overstiger denne samlede varighed, returnerer API'et HTTP 408 med fejlkode QueryTimeout.

Afkortede resultater

Grafen afkorter et forespørgselssvar, når dens interne binære repræsentation overstiger 64 MB. API'et returnerer de rækker, der passer, og tilføjer en status til additionalStatuses. Den ekstra status bruger offentlig kode 01000 og bevarer kanonisk GQL-status 01M11 i _graphaneGqlStatus.

Trunkering giver ikke en nextPage token for de udeladte rækker. Indsnævre forespørgslen med filtre, specifikke projektioner eller LIMIT, og kør den så igen.

Udeladte resultater

Responsskemaet kan repræsentere en operation, hvis udsagn aldrig producerer rækker, uafhængigt af data eller evalueringsresultat. Dette resultat bruger statuskode 00001:

{
  "kind": "NOTHING"
}

Dette udeladte resultat adskiller sig fra en tabel uden rækker. En tom tabel er resultatet af evaluering af en rækkeproducerende forespørgsel, som i øjeblikket ikke har rækker at returnere.

Graph reserverer denne resultatform og statuskode til fremtidig understøttelse af datadefinitionsprog (DDL) og datamanipulationssprog (DML). Nuværende forespørgselsudsagn returnerer altid tabellresultater.

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.

Notat

JSON-formatet for tabelresultater realiserer det diskriminerede foreningsmønster ved at gqlType adskille og value opnå en mere kompakt repræsentation. Se Optimering af tabel serialisering.

Værdistruktur

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

Primitive typer

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

Numeriske typer

Heltalstyper

GQL-type Interval JSON-serialisering Eksempel
INT64 -2⁶³ til 2⁶³-1 Tal eller streng* {"gqlType": "INT64", "value": -9237}
UINT64 0 til 2⁶⁴-1 Tal eller streng* {"gqlType": "UINT64", "value": 18467}

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

GQL-type Interval JSON-serialisering Eksempel
FLOAT64 IEEE 754 binær64 JSON-nummer eller -streng {"gqlType": "FLOAT64", "value": 3.14}

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:

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

Referencetyper for grafelementer

GQL-type Beskrivelse Eksempel
NODE Grafnodereference {"gqlType": "NODE", "value": "node-123"}
EDGE Grafkantreference {"gqlType": "EDGE", "value": "edge_abc#def"}

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

Fejlhåndtering

Transportfejl

HTTP-status og GQL-status beskriver forskellige lag af svaret:

HTTP-status Betydning
200 API'et behandlede anmodningen. Inspekter status.code , fordi resultatet kan repræsentere succes, ingen rækker, en forespørgsel stadig i gang, eller en brugerkorrigerbar forespørgselsfejl.
408 Forespørgselsudførelsen oversteg den samlede 20-minutters timeout. Fejlkoden er QueryTimeout.
429 Grænsen for tjenestetakst blev overskredet. Vent på varigheden i Retry-After headeren, før du prøver igen.
499 Opkalderen annullerede anmodningen. Fejlkoden er ClientCancelled.
Andre 4xx eller 5xx Anmodningen eller tjenesten mislykkedes, før den returnerede et GQL-udførelsesresultat. Undersøg HTTP-fejlsvaret.

Programfejl

En fejl på applikationsniveau kan returnere HTTP 200 med fejlinformation i statusobjektet. For eksempel bruger division med nul den offentlige API-kode 42000 og bevarer kanonisk GQL-status 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
      }
    }
  }
}

Statuskontrol

For at fastslå det overordnede udfald, tjek offentligheden status.code. Brug _graphaneGqlStatus den, når din applikation skal skelne mellem en specifik forespørgselsmotorbetingelse, såsom numerisk overflow (22003) fra division med nul (22012).

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

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"

Tips

Se afsnittet om godkendelse for at få et gyldigt ihændehavertoken.

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

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

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 - Valider og fjern korrekt alle brugerindtastede værdier, som din applikation indsætter i forespørgselsteksten.

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 kommatal-værdier - API'en serialiserer positiv uendelig, negativ uendelig, ikke-et tal og minus nul som "Inf", "-Inf", "NaN", og "-0".
  • Handle null-værdier – JSON null repræsenterer GQL null.

Relateret indhold

  • Sidst opdateret den