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.

Viktigt!

Denna artikel använder uteslutande dataset för sociala nätverk som exempel på graf.

Ö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

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.

Anmärkning

Se avsnittet om hur du använder az-rest eller avsnittet om hur du använder curl för att köra frågor via API-slutpunkten från ett kommandoradsgränssnitt.

Frågeparametrar

Parameter Typ Krävs Description
beta boolean Yes Ställ in på true att använda beta-Query API:et.
continuationToken snöre No Token från result.nextPage när en fråga fortfarande körs. Skicka in samma frågetext när du använder token.

Förfrågningsrubriker

Header Värde Krävs
Content-Type application/json Yes
Accept application/json Yes
Authorization Bearer <token> Yes

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

Fält Typ Krävs Description
query snöre Yes GQL-frågan som ska köras

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:

Fält Typ Description
code snöre Fem tecken lång offentlig API-statuskod.
description snöre Mänskligt läsbar statusbeskrivning.
diagnostics objekt Detaljerad diagnostisk journal, inklusive den kanoniska frågemotorns GQLSTATUS när den finns tillgänglig.
cause objekt Valfritt underliggande orsaksstatusobjekt.

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.

Anmärkning

Diagnostiken _graphaneGqlStatus innehåller den kanoniska femteckens GQLSTATUS som rapporteras av frågemotorn. Varje diagnostisk medlem med underpoängsprefix innehåller antingen null eller ett JSON-kodat GQL-värde. Till exempel _graphaneGqlStatus använder STRING, medan felklassificeringsdiagnostik använder BOOL. Se Värdetyper och kodning.

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.

Anmärkning

JSON-formatet för tabellresultat förverkligar det diskriminerade unionsmönstret genom att gqlType separera och value uppnå en mer kompakt representation. Se Tabell serialiseringsoptimering.

Värdestruktur

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

Primitiva typer

GQL-typ Example Description
BOOL {"gqlType": "BOOL", "value": true} Internt JSON-booleskt värde
STRING {"gqlType": "STRING", "value": "Hello"} UTF-8-sträng

Numeriska typer

Heltalstyper

GQL-typ Räckvidd JSON-serialisering Example
INT64 -2⁶³ till 2⁶³-1 Tal eller sträng* {"gqlType": "INT64", "value": -9237}
UINT64 0 till 2⁶⁴-1 Tal eller sträng* {"gqlType": "UINT64", "value": 18467}

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

GQL-typ Räckvidd JSON-serialisering Example
FLOAT64 IEEE 754 binär64 JSON-nummer eller -sträng {"gqlType": "FLOAT64", "value": 3.14}

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:

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

Referenstyper för Graph-element

GQL-typ Description Example
NODE Referens för grafnod {"gqlType": "NODE", "value": "node-123"}
EDGE Graph Edge-referens {"gqlType": "EDGE", "value": "edge_abc#def"}

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:

HTTP-statuskod Meaning
200 API:et behandlade förfrågan. Inspektera status.code eftersom resultatet kan representera framgång, inga rader, en pågående fråga eller ett användarkorrigerbart fel.
408 Förfrågansökningen översteg den totala timeouten på 20 minuter. Felkoden är QueryTimeout.
429 Gränsen för tjänstfrekvens överskreds. Vänta på varaktigheten i Retry-After headern innan du försöker igen.
499 Uppringaren avbröt förfrågan. Felkoden är ClientCancelled.
Andra 4xx eller 5xx Begäran eller tjänsten misslyckades innan den returnerade ett GQL-exekveringsresultat. Granska HTTP-felsvaret.

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"

Tips/Råd

Se avsnittet om autentisering för hur du hämtar en giltig ägartoken.

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

  • Uppdaterades senast