Referens för GQL Query API

Kör GQL-frågor mot egenskapsdiagram i grafen i Microsoft Fabric med hjälp av ett RESTful HTTP-API. Den här referensen beskriver HTTP-kontraktet: format för begäran och svar, autentisering, JSON-resultatkodning och felhantering.

Översikt

GQL Query API exponerar en REST-endpoint som accepterar GQL-frågor som JSON-payloads och returnerar strukturerade, typade resultat. Den stöder fortsättningspolling för frågor som inte avslutas under den initiala förfrågan.

Viktiga funktioner

• Enskild slutpunkt – Alla åtgärder använder HTTP POST till en URL.
• JSON-baserad – Nyttolaster för begäran och svar använder JSON med omfattande kodning av typade GQL-värden.
• Continuation polling – Långvariga frågor kan fortsätta över flera HTTP-förfrågningar.
• Typsäker – Stark, GQL-kompatibel typning med diskriminerade fackföreningar för värderepresentation.

Förutsättningar

• Du behöver ett diagram som innehåller data, inklusive noder och kanter (relationer). Se grafens snabbstart för att skapa och läsa in ett exempeldiagram.
• Du bör känna till egenskapsdiagram och en grundläggande förståelse för GQL, inklusive strukturen för körningsresultat och resultat.
• Du måste installera och konfigurera verktyget Azure CLIaz för att logga in på din organisation. Kommandoradsexempel i den här artikeln förutsätter användning av ett POSIX-kompatibelt kommandoradsgränssnitt, till exempel bash.

Authentication

GQL Query API kräver autentisering via ägartoken.

Inkludera din åtkomsttoken i auktoriseringshuvudet för varje begäran:

Authorization: Bearer <your-access-token>

I allmänhet kan du hämta ägartoken med hjälp av Microsofts autentiseringsbibliotek (MSAL) eller andra autentiseringsflöden som är kompatibla med Microsoft Entra.

Ägartoken erhålls ofta via två huvudsakliga sökvägar:

Användardelegering

Du kan hämta ägartoken för användardelegaterade tjänstanrop från kommandoraden via verktyget Azure CLIaz.

Hämta en ägartoken för användardelegaterade anrop från kommandoraden genom att:

• Kör az login
• Då az account get-access-token --resource https://api.fabric.microsoft.com

Detta använder verktyget Azure CLIaz.

När du använder az rest för att utföra begäranden hämtas ägartoken automatiskt.

Programåtkomst

Du kan hämta ägartoken för program som registrerats i Microsoft Entra. Mer information finns i snabbstarten för Infrastruktur-API :et.

API-slutpunkt

API:et använder en enda slutpunkt som accepterar alla frågeåtgärder:

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

Query API är i beta och rekommenderas inte för produktionsbruk. Sätt den nödvändiga beta frågeparametern till true. Den äldre preview=true parametern stöds fortfarande för bakåtkompatibilitet, men används beta=true för nya integrationer.

Om du vill hämta {workspaceId} för din arbetsyta kan du visa en lista över alla tillgängliga arbetsytor med hjälp av az rest:

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

Om du vill hämta {graphModelId}kan du visa en lista över alla tillgängliga diagram på en arbetsyta med hjälp 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 använda Azure CLI-utdata för att filtrera eller formatera svaren från dessa listförfrågningar. Dessa alternativ körs i Azure CLI-klienten; de är inte Query API-parametrar:

• --query "value[?displayName=='My Workspace']" listar endast objekt med ett displayName av My Workspace.
• --query "value[?starts_with(displayName, 'My')]" listar endast objekt vars displayName börjar med My.
• --query "{query}" listar endast föremål som matchar den tillhandahållna JMESPath {query}. Se Query Azure CLI-kommandoresultat för den stödda syntaxen.
• -o table för att producera ett tabellresultat.

Frågeparametrar

Förfrågningsrubriker

Begärandeformat

Alla begäranden använder HTTP POST med en JSON-nyttolast.

Grundläggande struktur för begäranden

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

Fält för begäran

Svarsformat

Alla svar för lyckade begäranden använder HTTP 200-status med JSON-nyttolast som innehåller körningsstatus och resultat.

Svarsstruktur

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

Varje svar innehåller ett statusobjekt med körningsinformation:

Statuskoder

Den primära status.code använder dessa publika API-kategorier:

• 00000 - Lyckad komplettering med minst en rad.
• 00001 - Lyckad slutförande med utelämnat resultat. Reserverat för framtida DDL- och DML-stöd.
• 01000 - Varning eller informationstillstånd.
• 02000 - Inga rader är för närvarande tillgängliga från en radproducerande fråga.
• 42000 - Syntax-, access-rule eller annat användarkorrigerbart frågefel.
• 50000 - System- eller oklassificerat fel.

Mer information finns i referensen för GQL-statuskoder.

Diagnostikposter

Diagnostikposter kan innehålla andra nyckel/värde-par som ytterligare beskriver statusobjektet. Nycklar som börjar med ett understreck (_) är specifika för diagram. GQL-standarden föreskriver alla andra nycklar.

Orsaker

Statusobjekt innehåller ett valfritt cause fält när en underliggande orsak är känd.

Andra statusobjekt

Vissa resultat kan rapportera andra statusobjekt som en lista i det valfria additionalStatuses fältet.

Primärstatusen är det mest kritiska registrerade tillståndet. Varje ytterligare status och nästlad orsak har sin egen publika API-kod och kanoniska GQLSTATUS-diagnostik.

Resultattyper

Resultaten använder ett diskriminerat unionsmönster med fältet kind :

Tabellresultat

För frågor som returnerar 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
    }
  ]
}

Tidskrävande frågor

Om en fråga inte avslutas under den aktuella HTTP-förfrågan returnerar API:et HTTP 200 med publik statuskod 02000, en tom tabell och en nextPage token:

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

Poll för fullbordan genom att skicka samma förfråganarkam och lägga till token i URL:en:

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

Behandla nextPage det som ett ogenomskinligt värde. Procentkoda den exakt en gång enligt RFC 3986 innan du använder den som continuationToken frågeparametervärde. Avkoda, inspektera eller ändra inte tokenen.

Fortsätt tills svaret inte längre innehåller nextPage. Frågeexekveringen kan fortsätta i upp till 20 minuter från den initiala förfrågan. Om den överskrider den totala varaktigheten returnerar API:et HTTP 408 med felkod QueryTimeout.

Förkortade resultat

Grafen förkortar ett frågesvar när dess interna binära representation överstiger 64 MB. API:et returnerar de rader som passar och lägger till en status till additionalStatuses. Den ytterligare statusen använder offentlig kod 01000 och bevarar kanonisk GQL-status 01M11 i _graphaneGqlStatus.

Truncering ger nextPage ingen token för de utelämnade raderna. Begränsa frågan med filter, specifika projektioner eller LIMIT, och kör sedan igen.

Utelämnade resultat

Responsschemat kan representera en operation vars formulering aldrig ger rader, oberoende av data eller utvärderingsresultat. Detta resultat använder statuskod 00001:

{
  "kind": "NOTHING"
}

Detta utelämnade resultat skiljer sig från en tabell utan rader. En tom tabell är resultatet av att utvärdera en radproducerande fråga som för närvarande inte har några rader att returnera.

Graph reserverar denna resultatform och statuskod för framtida data definition language (DDL) och data manipulation language (DML) satsstöd. Aktuella frågesatser returnerar alltid tabellresultat.

Värdetyper och kodning

API:et använder ett omfattande typsystem för att representera GQL-värden med exakta semantik. JSON-formatet för GQL-värden följer ett diskriminerat unionsmönster.

Värdestruktur

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

Primitiva typer

Numeriska typer

Heltalstyper

Stora heltal utanför JavaScripts säkra intervall (-9 007 199 254 740 991 till 9 007 199 254 740 991) serialiseras som strängar:

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

Flyttalstyper

Flyttalsvärden stöder IEEE 754-specialvärden:

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

Temporala typer

Tidstyper som stöds använder ISO 8601-strängformat:

Referenstyper för Graph-element

Komplexa typer

De komplexa typerna består av andra GQL-värden.

Lists

Listor innehåller matriser med null-värden med konsekventa elementtyper:

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

Särskilda listtyper:

• LIST<ANY> – Blandade typer (varje element innehåller fullständig typinformation)
• LIST<NULL> – Endast null-värden tillåts
• LIST<NOTHING> - Alltid tom matris

Paths

Sökvägar kodas som listor över referensvärden för grafelement.

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

Se Tabell serialiseringsoptimering.

Optimering av tabell serialisering

För tabellresultat optimeras värde serialisering baserat på kolumntypsinformation:

• Kända typer – Endast raw-värdet serialiseras
• ANY-kolumner – Fullständigt värdeobjekt med typdiskriminering

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

Felhantering

Transportfel

HTTP-status och GQL-status beskriver olika lager av svaret:

Programfel

Ett felmeddelande på applikationsnivå kan returnera HTTP 200 med felinformation i statusobjektet. Till exempel använder division med noll den publika API-koden 42000 och bevarar kanonisk GQL-status 22012 i diagnosposten:

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

För att avgöra det breda utfallet, kontrollera allmänheten status.code. Använd _graphaneGqlStatus när din applikation behöver skilja på ett specifikt frågemotorvillkor, såsom numeriskt överflöd (22003) från division med noll (22012).

Komplett exempel med az rest

Kör en fråga med kommandot az rest för att undvika att behöva hämta ägartoken manuellt, så här:

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 exempel med curl

I exemplet i det här avsnittet används curl verktyget för att utföra HTTPS-begäranden från gränssnittet.

Vi antar att du har en giltig åtkomsttoken lagrad i en gränssnittsvariabel, så här:

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

Kör en fråga så här:

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

Metodtips

Följ dessa metodtips när du använder GQL-fråge-API:et.

Felhantering

• Kontrollera alltid statuskoder – Anta inte att det lyckas baserat på HTTP 200.
• Parsa felinformation – Använd diagnostik och orsakskedjor för felsökning.

Security

• Använd HTTPS – Skicka aldrig autentiseringstoken via okrypterade anslutningar.
• Rotera token – Implementera korrekt tokenuppdatering och förfallohantering.
• Validera indata – Validera och korrekt evakuera alla användargenererade värden som din applikation infogar i frågetexten.

Värderepresentation

• Hantera stora heltalsvärden – Heltal kodas som strängar om de inte kan representeras som JSON-tal internt.
• Hantera speciella flyttalsvärden – API:et serialiserar positiv oändlighet, negativ oändlighet, icke-ett tal och minus noll som "Inf", "-Inf", "NaN", och "-0".
• Hantera null-värden – JSON null representerar GQL null.

Relaterat innehåll

• diagramdatamodeller
• Språkguide för GQL
• GQL-värden och värdetyper
• Referens för GQL-statuskoder