GQL-query-API-verwijzing

Voer GQL-query's uit op eigenschapsgrafieken in grafiek in Microsoft Fabric met behulp van een RESTful HTTP-API. In deze verwijzing wordt het HTTP-contract beschreven: aanvraag- en antwoordindelingen, verificatie, JSON-resultaatcodering en foutafhandeling.

Belangrijk

Dit artikel gebruikt uitsluitend de voorbeeldgrafiekdataset van sociale netwerken.

Overzicht

De GQL Query API biedt een REST-eindpunt dat GQL-query's accepteert als JSON-payloads en gestructureerde, getypeerde resultaten teruggeeft. Het ondersteunt continuümpolling voor queries die niet worden afgerond tijdens het eerste verzoek.

Belangrijkste kenmerken

Eén eindpunt : alle bewerkingen gebruiken HTTP POST naar één URL.
JSON-gebaseerde nettoladingen voor aanvragen en antwoorden gebruiken JSON met uitgebreide codering van getypeerde GQL-waarden.
Continuationpolling - Langlopende queries kunnen doorgaan over meerdere HTTP-verzoeken.
Type veilig - Sterk, GQL-compatibel typen met gediscrimineerde samenvoegingen voor waardeweergave.

Vereiste voorwaarden

U hebt een grafiek nodig die gegevens bevat, inclusief knooppunten en randen (relaties). Zie de snelstartgids voor grafieken om een voorbeeldgrafiek te maken en te laden.
U moet bekend zijn met eigenschappengrafieken en basiskennis van GQL, inclusief de structuur van uitvoeringsresultaten en resultaten.
U moet het hulpprogramma Azure CLI installeren en instellen az om u aan te melden bij uw organisatie. Voorbeelden van opdrachtregels in dit artikel gaan uit van het gebruik van een POSIX-compatibele opdrachtregelshell, zoals bash.

Authenticatie

De GQL-query-API vereist verificatie via bearer-tokens.

Neem uw toegangstoken op in de autorisatieheader van elke aanvraag:

Authorization: Bearer <your-access-token>

Over het algemeen kunt u bearer-tokens verkrijgen met behulp van Microsoft Authentication Library (MSAL) of andere verificatiestromen die compatibel zijn met Microsoft Entra.

Bearer-tokens worden meestal verkregen via twee belangrijke paden:

Door de gebruiker gedelegeerde toegang

U kunt bearer-tokens verkrijgen voor door de gebruiker gedelegeerde serviceaanroepen vanaf de opdrachtregel via het hulpprogramma Azure CLIaz.

Haal een Bearer-token op voor door de gebruiker gedelegeerde aanroepen vanaf de opdrachtregel door:

Voer az login uit
Dan az account get-access-token --resource https://api.fabric.microsoft.com

Dit maakt gebruik van het hulpprogramma Azure CLIaz.

Wanneer u gebruikt az rest voor het uitvoeren van aanvragen, worden bearer-tokens automatisch verkregen.

Toegang tot toepassingen

U kunt bearer-tokens verkrijgen voor toepassingen die zijn geregistreerd in Microsoft Entra. Raadpleeg de snelstartgids voor de Fabric-API voor meer informatie.

API-eindpunt

De API maakt gebruik van één eindpunt dat alle querybewerkingen accepteert:

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

De Query API is in bèta en wordt niet aanbevolen voor productiegebruik. Stel de vereiste beta queryparameter in op true. De oudere preview=true parameter blijft ondersteund voor achterwaartse compatibiliteit, maar wordt gebruikt beta=true voor nieuwe integraties.

Als u de {workspaceId} werkruimte wilt verkrijgen, kunt u alle beschikbare werkruimten weergeven met behulp van az rest:

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

Als u de {graphModelId}lijst wilt verkrijgen, kunt u alle beschikbare grafieken in een werkruimte weergeven met behulp van az rest:

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

Je kunt Azure CLI-uitvoeropties gebruiken om de antwoorden van deze lijstverzoeken te filteren of te formatteren. Deze opties draaien in de Azure CLI-client; het zijn geen Query API-parameters:

--query "value[?displayName=='My Workspace']" Vermeldt alleen items met een displayName van My Workspace.
--query "value[?starts_with(displayName, 'My')]" Vermeldt alleen items waarvan de displayName start met My.
--query "{query}" vermeldt alleen items die overeenkomen met de verstrekte JMESPath {query}. Zie Query Azure CLI-commandresultaten voor de ondersteunde syntaxis.
-o table voor het produceren van een tabelresultaat.

Opmerking

Zie de sectie over het gebruik van az-rest of de sectie over het gebruik van curl voor het uitvoeren van query's via het API-eindpunt vanuit een opdrachtregelshell.

Parameters voor zoekopdrachten

Parameter	Typologie	Verplicht	Description
`beta`	boolean	Yes	Stel in om `true` de beta Query API te gebruiken.
`continuationToken`	touw	No	Token van `result.nextPage` wanneer een query nog draait. Stuur dezelfde querytekst in wanneer je het token gebruikt.

Headers aanvragen

Header	Waarde	Verplicht
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

Aanvraagindeling

Alle aanvragen gebruiken HTTP POST met een JSON-nettolading.

Basisaanvraagstructuur

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

Aanvraagvelden

Veld	Typologie	Verplicht	Description
`query`	touw	Yes	De GQL-query die moet worden uitgevoerd

Antwoordindeling

Alle antwoorden voor geslaagde aanvragen gebruiken de HTTP 200-status met JSON-nettolading met de uitvoeringsstatus en resultaten.

Antwoordstructuur

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

Statusobject

Elk antwoord bevat een statusobject met uitvoeringsinformatie:

Veld	Typologie	Description
`code`	touw	Vijf tekens tellende openbare API-statuscode.
`description`	touw	Mensleesbare statusbeschrijving.
`diagnostics`	Voorwerp	Gedetailleerd diagnostisch record, inclusief de canonieke query-engine GQLSTATUS indien beschikbaar.
`cause`	Voorwerp	Optioneel onderliggende oorzaakstatusobject.

Statuscodes

De primaire status.code gebruikt deze publieke API-categorieën:

00000 - Succesvolle voltooiing met ten minste één rij.
00001 - Succesvolle voltooiing met een weggelaten resultaat. Gereserveerd voor toekomstige DDL- en DML-ondersteuning.
01000 - Waarschuwing of informatieve toestand.
02000 - Er zijn momenteel geen rijen beschikbaar vanuit een rij-producerende query.
42000 - Syntaxis-, toegangsregel- of andere door de gebruiker corrigeerbare queryfout.
50000 - Systeem- of niet-geclassificeerde fout.

Zie de referentie voor GQL-statuscodes voor meer informatie.

Diagnostische records

Diagnostische records kunnen andere sleutel-waardeparen bevatten waarmee het statusobject verder wordt gedetailleerd beschreven. Sleutels die beginnen met een onderstrepingsteken (_) zijn specifiek voor grafieken. De GQL-standaard schrijft alle andere sleutels voor.

Opmerking

De _graphaneGqlStatus diagnose bevat de canonieke vijf-teken GQLSTATUS die door de query-engine wordt gerapporteerd. Elk diagnostisch lid met een onderscorevoorvoegsel bevat ofwel null een JSON-gecodeerde GQL-waarde. Bijvoorbeeld, _graphaneGqlStatus gebruikt STRING, terwijl foutclassificatiediagnostiek .BOOL Zie waardetypen en codering.

Oorzaken

Statusobjecten bevatten een optioneel cause veld wanneer een onderliggende oorzaak bekend is.

Andere statusobjecten

Sommige resultaten kunnen andere statusobjecten als een lijst in het optionele additionalStatuses veld rapporteren.

De primaire status is de meest kritieke geregistreerde aandoening. Elke extra status en geneste oorzaak heeft zijn eigen publieke API-code en canonieke GQLSTATUS-diagnose.

Resultaattypen

Resultaten gebruiken een gediscrimineerd samenvoegpatroon met het kind veld:

Tabelresultaten

Voor query's die tabelgegevens retourneren:

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

Langlopende queries

Als een query niet wordt afgerond tijdens het huidige HTTP-verzoek, retourneert de API HTTP 200 met publieke statuscode 02000, een lege tabel en een nextPage token:

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

Poll op voltooiing door hetzelfde verzoeklichaam te verzenden en het token toe te voegen aan de URL:

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

Behandel nextPage het als een ondoorzichtige waarde. Conform RFC 3986 per procent codeer het exact één keer voordat je het als continuationToken queryparameterwaarde gebruikt. Decodeer, inspecteer of verander de token niet.

Ga door totdat het antwoord niet langer bevat nextPage. De uitvoering van een query kan tot 20 minuten doorgaan vanaf het eerste verzoek. Als deze die totale duur overschrijdt, retourneert de API HTTP 408 met foutcode QueryTimeout.

Afgeknotte resultaten

Graph kapt een query-antwoord af wanneer de interne binaire representatie meer dan 64 MB is. De API geeft de rijen terug die passen en voegt een status toe aan additionalStatuses. De aanvullende status gebruikt publieke code 01000 en behoudt de canonieke GQLSTATUS 01M11 in _graphaneGqlStatus.

Truncatie levert geen nextPage token op voor de weggelaten rijen. Verfijn de zoekopdracht met filters, specifieke projecties, of LIMIT, en voer het vervolgens opnieuw uit.

Weggelaten resultaten

Het responsschema kan een operatie voorstellen waarvan de stelling nooit rijen produceert, onafhankelijk van de data of evaluatie-uitkomst. Deze uitkomst gebruikt statuscode 00001:

{
  "kind": "NOTHING"
}

Dit weggelaten resultaat verschilt van een tabel zonder rijen. Een lege tabel is het resultaat van het evalueren van een rij-producerende query die momenteel geen rijen heeft om terug te geven.

Graph reserveert deze resultaatvorm en statuscode voor toekomstige ondersteuning voor data definition language (DDL) en data manipulation language (DML) statements. Huidige query-instructies geven altijd tabelresultaten terug.

Waardetypen en codering

De API maakt gebruik van een uitgebreid typesysteem om GQL-waarden met nauwkeurige semantiek weer te geven. De JSON-indeling van GQL-waarden volgt een gediscrimineerd samenvoegingspatroon.

Opmerking

De JSON-indeling van tabellaire resultaten realiseert het gediscrimineerde samenvoegingspatroon door een gqlTypevalue compactere representatie te bereiken. Zie Optimalisatie van tabelserialisatie.

Waardestructuur

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

Primitieve typen

GQL-type	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Systeemeigen JSON-booleaanse waarde
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8-tekenreeks

Numerieke typen

Typen gehele getallen

GQL-type	Bereik	JSON-serialisatie	Example
`INT64`	-2⁶³ tot 2⁶³-1	Getal of tekenreeks*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 tot 2⁶⁴-1	Getal of tekenreeks*	`{"gqlType": "UINT64", "value": 18467}`

Grote gehele getallen buiten het veilige bereik van JavaScript (-9.007.199.254.740.991 tot 9.007.199.254.740.991) worden geserialiseerd als tekenreeksen:

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

Typen drijvende komma

GQL-type	Bereik	JSON-serialisatie	Example
`FLOAT64`	IEEE 754 binair64	JSON-nummer of tekenreeks	`{"gqlType": "FLOAT64", "value": 3.14}`

Waarden voor drijvende komma ondersteunen speciale IEEE 754-waarden:

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

Tijdelijke typen

Ondersteunde tijdelijke typen maken gebruik van ISO 8601-tekenreeksindelingen:

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

Verwijzingstypen voor grafiekelementen

GQL-type	Description	Example
`NODE`	Naslaginformatie over grafiekknooppunten	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Graph Edge-verwijzing	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Complexe typen

De complexe typen bestaan uit andere GQL-waarden.

Lists

Lijsten bevatten matrices met null-waarden met consistente elementtypen:

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

Speciale lijsttypen:

LIST<ANY> - Gemengde typen (elk element bevat informatie over het volledige type)
LIST<NULL> - Alleen toegestane null-waarden
LIST<NOTHING> - Altijd lege matrix

Paths

Paden worden gecodeerd als lijsten met verwijzingswaarden voor grafiekelementen.

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

Zie Optimalisatie van tabelserialisatie.

Optimalisatie van tabelserialisatie

Voor tabelresultaten is waardeserialisatie geoptimaliseerd op basis van gegevens van het kolomtype:

Bekende typen : alleen de onbewerkte waarde wordt geserialiseerd
ANY-kolommen - Object met volledige waarde met typediscriminator

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

Foutafhandeling

Transportfouten

HTTP-status en GQL-status beschrijven verschillende lagen van de respons:

HTTP-status	Meaning
200	De API verwerkte het verzoek. Inspecteren `status.code` omdat het resultaat succes kan vertegenwoordigen, geen rijen, een nog lopende query of een door de gebruiker corrigeerbare queryfout.
408	De uitvoering van de query overschreed de totale time-out van 20 minuten. De foutcode is `QueryTimeout`.
429	De servicesnelheidslimiet is overschreden. Wacht tot de duur in de `Retry-After` header voordat je het opnieuw probeert.
499	De beller annuleerde het verzoek. De foutcode is `ClientCancelled`.
Andere 4xx of 5xx	Het verzoek of de service faalde voordat het GQL-uitvoeringsresultaat werd teruggegeven. Controleer de HTTP-foutrespons.

Toepassingsfouten

Een fout op applicatieniveau kan HTTP 200 teruggeven met foutinformatie in het statusobject. Bijvoorbeeld, deling door nul gebruikt de publieke API-code 42000 en behoudt canonieke GQLSTATUS 22012 in het diagnostische record:

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

Statuscontrole

Om de algemene uitkomst te bepalen, controleer het publiek status.code. Gebruik _graphaneGqlStatus wanneer je applicatie een specifieke query-engine-conditie, zoals numerieke overflow (22003) moet onderscheiden van deling door nul (22012).

Volledig voorbeeld met az rest

Voer een query uit met behulp van de az rest opdracht om te voorkomen dat bearer-tokens handmatig moeten worden verkregen, zoals:

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

Volledig voorbeeld met curl

In het voorbeeld in deze sectie wordt het hulpprogramma gebruikt voor het curl uitvoeren van HTTPS-aanvragen vanuit de shell.

We gaan ervan uit dat u een geldig toegangstoken hebt opgeslagen in een shellvariabele, zoals:

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

Aanbeveling

Zie de sectie over verificatie voor het verkrijgen van een geldig bearer-token.

Voer als volgt een query uit:

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

Beste praktijken

Volg deze aanbevolen procedures bij het gebruik van de GQL-query-API.

Foutafhandeling

Controleer altijd de statuscodes . Ga er niet van uit dat de statuscodes zijn geslaagd op basis van HTTP 200.
Foutdetails parseren : gebruik diagnostische gegevens en oorzaakketens voor foutopsporing.

Security

Https gebruiken : nooit verificatietokens verzenden via niet-versleutelde verbindingen.
Tokens roteren : de juiste verwerking van het vernieuwen en verlopen van tokens implementeren.
Valideer invoer - Valideer en verwijder correct alle door de gebruiker verstrekte waarden die je applicatie in de querytekst invoegt.

Waardeweergave

Grote gehele getallen verwerken: gehele getallen worden gecodeerd als tekenreeksen als ze niet systeemeigen als JSON-getallen kunnen worden weergegeven.
Behandel speciale floating-pointwaarden - De API serialiseert positieve oneindig, negatieve oneindig, niet-een-getal en negatieve nul als "Inf", "-Inf", "NaN", en "-0".
Null-waarden verwerken - JSON null vertegenwoordigt GQL null.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-09-29

GQL-query-API-verwijzing

Overzicht

Belangrijkste kenmerken

Vereiste voorwaarden

Authenticatie

Door de gebruiker gedelegeerde toegang

Toegang tot toepassingen

API-eindpunt

Parameters voor zoekopdrachten

Headers aanvragen

Aanvraagindeling

Basisaanvraagstructuur

Aanvraagvelden

Antwoordindeling

Antwoordstructuur

Statusobject

Statuscodes

Diagnostische records

Oorzaken

Andere statusobjecten

Resultaattypen

Tabelresultaten

Langlopende queries

Afgeknotte resultaten

Weggelaten resultaten

Waardetypen en codering

Waardestructuur

Primitieve typen

Numerieke typen

Typen gehele getallen

Typen drijvende komma

Tijdelijke typen

Verwijzingstypen voor grafiekelementen

Complexe typen

Lists

Paths

Optimalisatie van tabelserialisatie

Foutafhandeling

Transportfouten

Toepassingsfouten

Statuscontrole

Volledig voorbeeld met az rest

Volledig voorbeeld met curl

Beste praktijken

Foutafhandeling

Security

Waardeweergave

Verwante inhoud

Feedback

Aanvullende resources