Del via

API-referanse for GQL-spørring

Note

Denne funksjonen er for øyeblikket i offentlig forhåndsversjon. Denne forhåndsvisningen leveres uten en tjenesteavtale, og anbefales ikke for produksjonsarbeidsbelastninger. Enkelte funksjoner støttes kanskje ikke eller kan ha begrensede funksjoner. Hvis du vil ha mer informasjon, kan du se Supplerende vilkår for bruk for Microsoft Azure Previews.

Kjør GQL-spørringer mot egenskapsgrafer 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 få bæretokener 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 CLI-verktøyetaz,

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 Azure CLI-verktøyetaz.

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 Azure CLI-dokumentasjonen 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 graf for Microsoft Fabric. GQL-standarden foreskriver alle andre nøkler.

Note

Verdier i diagnoseposten for nøkler som er spesifikke for grafen i Microsoft Fabric, 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