Dela via

Referens för GQL Query API

Anmärkning

Den här funktionen är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och rekommenderas inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Kör GQL-frågor mot egenskapsdiagram 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-fråge-API:et är en enskild slutpunkt (RPC via HTTP) som accepterar GQL-frågor som JSON-nyttolaster och returnerar strukturerade, inskrivna resultat. API:et är tillståndslöst, hanterar autentisering och tillhandahåller omfattande felrapportering.

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.
  • Tillståndslös – Inget sessionstillstånd krävs mellan begäranden.
  • 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 Microsoft Authentication Library (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 Azure CLI-verktygetaz,

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 Azure CLI-verktygetaz.

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?preview=true

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 {graphId}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 fler parametrar för att ytterligare begränsa frågeresultat:

  • --query 'value[?displayName=='My Workspace'] för att endast visa objekt med en displayName av My Workspace.
  • --query 'value[starts_with(?displayName='My')] för att endast visa objekt vars displayName börjar med My.
  • --query '{query}' för att endast visa objekt som matchar den angivna JMESPath {query}. Se Azure CLI-dokumentationen på JMESPath om syntaxen som stöds för {query}.
  • -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.

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

Statusobjekt

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

Fält Typ Description
code snöre statuskod med sex tecken (000000 = lyckades)
description snöre Statusmeddelande som kan läsas av människor
diagnostics objekt Detaljerade diagnostikposter
cause objekt Valfritt objekt för underliggande orsaksstatus

Statuskoder

Statuskoder följer ett hierarkiskt mönster:

  • 00xxxx – Slutfört lyckat
  • 01xxxx – Lyckades med varningar
  • 02xxxx – Lyckades utan data
  • 03xxxx – Lyckades med information
  • 04xxxx och högre – Fel och undantagsvillkor

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 för Microsoft Fabric. GQL-standarden föreskriver alla andra nycklar.

Anmärkning

Värden i diagnostikposten för nycklar som är specifika för grafen i Microsoft Fabric är JSON-kodade GQL-värden. 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 fältet (valfritt). additionalStatuses

I så fall bestäms det primära statusobjektet alltid vara det mest kritiska statusobjektet (till exempel ett undantagsvillkor) enligt GQL-standarden.

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

Utelämnade resultat

För åtgärder som inte returnerar data (till exempel katalog- och/eller datauppdateringar):

{
  "kind": "NOTHING"
}

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
{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Felhantering

Transportfel

Nätverks- och HTTP-transportfel resulterar i standardstatuskoder för HTTP-fel (4xx, 5xx).

Programfel

Fel på programnivå returnerar alltid HTTP 200 med felinformation 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

Kontrollera statuskoden för att avgöra om det lyckades:

  • Koder som börjar med 00, 01, 02, 03 indikerar lyckade (med möjliga varningar)
  • Alla andra koder indikerar fel

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

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.
  • Verifiera indata – Sanera och undvik alla användarspecifika frågeparametrar som matas in i frågan.

Värderepresentation

  • Hantera stora heltalsvärden – Heltal kodas som strängar om de inte kan representeras som JSON-tal internt.
  • Hantera särskilda flyttalsvärden – Flyttalvärden som returneras från frågor kan vara Infinity, -Infinityeller NaN (inte ett tal).
  • Hantera null-värden – JSON null representerar GQL null.

Relaterat innehåll

  • Last updated on