GQL Query API-referencia

GQL-lekérdezések futtatása tulajdonságdiagramokon a Microsoft Fabric gráfjában RESTful HTTP API használatával. Ez a hivatkozás a HTTP-szerződést írja le: kérelem- és válaszformátumokat, hitelesítést, JSON-eredmények kódolását és hibakezelést.

Fontos

Ez a cikk kizárólag a közösségi hálózati példa gráfdatasetet használja.

Áttekintés

A GQL Query API egy egyetlen végpont (RPC HTTP-n keresztül), amely JSON hasznos adatként fogadja a GQL-lekérdezéseket, és strukturált, beírt eredményeket ad vissza. Az API állapot nélküli, kezeli a hitelesítést, és átfogó hibajelentést biztosít.

Legfontosabb funkciók

Egyetlen végpont – Minden művelet HTTP POST-et használ egy URL-címre.
JSON-alapú – A kérelmek és válaszok hasznos adatai a JSON-t használják a beírt GQL-értékek gazdag kódolásával.
Állapot nélküli – Nincs szükség munkamenet-állapotra a kérések között.
Type safe – Erős, GQL-kompatibilis gépelés diszkriminált egyesítésekkel az értékábrázoláshoz.

Előfeltételek

Olyan gráfra van szüksége, amely adatokat tartalmaz, beleértve a csomópontokat és éleket (kapcsolatokat). Mintadiagram létrehozásához és betöltéséhez tekintse meg a gráf gyorsútmutatót .
Ismernie kell a tulajdonsággráfokat, és ismernie kell a GQL alapszintű ismereteit, beleértve a végrehajtási eredmények és eredmények szerkezetét.
A Azure CLI eszköz az telepítéséhez és beállításához be kell jelentkeznie a szervezetbe. A cikkben szereplő parancssori példák feltételezik, hogy POSIX-kompatibilis parancssori rendszerhéjat használnak, például basht.

Authentication

A GQL Query API tulajdonosi jogkivonatokon keresztüli hitelesítést igényel.

A hozzáférési jogkivonatot minden kérés engedélyezési fejlécében adja meg:

Authorization: Bearer <your-access-token>

A tulajdonosi jogkivonatokat általában Microsoft Authentication Library (MSAL) vagy más, Microsoft Entra kompatibilis hitelesítési folyamatokkal szerezheti be.

A tulajdonosi jogkivonatok általában két fő útvonalon érhetők el:

Felhasználó által delegált hozzáférés

A felhasználó által delegált szolgáltatáshívások tulajdonosi jogkivonatait a parancssorból szerezheti be a Azure CLI eszköz az.

Szerezze be a felhasználó által delegált hívások tulajdonosi jogkivonatát a parancssorból:

Az az login parancs futtatása
Akkor az account get-access-token --resource https://api.fabric.microsoft.com

Ez a Azure CLI eszközt használja az.

Amikor kérések végrehajtására használja az rest , a rendszer automatikusan lekéri a tulajdonosi jogkivonatokat.

Alkalmazáshozzáférés

A tulajdonosi jogkivonatokat a Microsoft Entra regisztrált alkalmazásokhoz szerezheti be. További részletekért tekintse meg a Fabric API rövid útmutatójában .

API-végpont

Az API egyetlen végpontot használ, amely minden lekérdezési műveletet elfogad:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true

{workspaceId} A munkaterület beszerzéséhez az összes elérhető munkaterületet a következővel az restlistázhatja:

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

A lekéréshez listázhatja a {graphId}munkaterületen elérhető összes gráfot a következővel az rest:

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

További paraméterekkel tovább szűkítheti a lekérdezési eredményeket:

--query 'value[?displayName=='My Workspace']csak olyan elemek listázása esetén, amelyek közül adisplayName.My Workspace
--query 'value[starts_with(?displayName='My')] csak azokat az elemeket sorolja fel, amelyek displayName a következővel kezdődnek My: .
--query '{query}' csak a megadott JMESPath-nak {query}megfelelő elemek listázása esetén. A JMESPath Azure CLI dokumentációja a támogatott szintaxisával kapcsolatban.
-o table táblaeredmény előállításához.

Megjegyzés:

Tekintse meg az az-rest használatáról szóló szakaszt , vagy a curl használatával kapcsolatos szakaszt , amely bemutatja, hogyan hajthat végre lekérdezéseket az API-végponton keresztül egy parancssori rendszerhéjból.

HTTP-kérés fejlécek

Header	Érték	Kötelező
`Content-Type`	`application/json`	Igen
`Accept`	`application/json`	Igen
`Authorization`	`Bearer <token>`	Igen

Kérelem formája

Minden kérés a HTTP POST-et használja JSON-hasznos adatokkal.

Egyszerű kérelemstruktúra

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

Mezők kérése

szakterület	Típus	Kötelező	Description
`query`	karakterlánc	Igen	A végrehajtandó GQL-lekérdezés

Válaszformátum

A sikeres kérelmekre adott válaszok a HTTP 200 állapotot használják a JSON hasznos adataival, amelyek végrehajtási állapotot és eredményeket tartalmaznak.

Válaszstruktúra

{
  "status": {
    "code": "00000",
    "description": "note: successful completion", 
    "diagnostics": {
      "OPERATION": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Állapotobjektum

Minden válasz tartalmaz egy végrehajtási adatokat tartalmazó állapotobjektumot:

szakterület	Típus	Description
`code`	karakterlánc	hat karakteres állapotkód (0000000 = siker)
`description`	karakterlánc	Emberi olvasásra alkalmas állapotüzenet
`diagnostics`	objektum	Részletes diagnosztikai rekordok
`cause`	objektum	Nem kötelező alapul szolgáló okállapot-objektum

Állapotkódok

Az állapotkódok hierarchikus mintát követnek:

00xxxx - Teljes siker
01xxxx - Sikeresség figyelmeztetésekkel
02xxxx - Sikeresség adatok nélkül
03xxxx - Siker információval
04xxxx és magasabb – Hibák és kivételfeltételek

További információ: GQL állapotkódok referenciája.

Diagnosztikai rekordok

A diagnosztikai rekordok tartalmazhatnak más kulcs-érték párokat is, amelyek részletesebben részletezik az állapotobjektumot. Az aláhúzással (_) kezdődő kulcsok a gráfra vonatkoznak. A GQL szabvány minden más kulcsot előír.

Megjegyzés:

A gráfra jellemző kulcsok diagnosztikai rekordjában szereplő értékek JSON-kódolású GQL-értékek. Lásd : Értéktípusok és kódolás.

Okok

Az állapotobjektumok egy választható cause mezőt is tartalmaznak, ha ismert a mögöttes ok.

Egyéb állapotobjektumok

Egyes eredmények más állapotobjektumokat is jelenthetnek listaként a (nem kötelező) additionalStatuses mezőben.

Ha igen, akkor az elsődleges állapotobjektum mindig a GQL szabvány által előírt legkritikusabb állapotobjektum (például kivételfeltétel) lesz.

Eredménytípusok

Az eredmények megkülönböztetett egyesítési mintát használnak a kind mezővel:

Táblaeredmények

Táblázatos adatokat visszaadó lekérdezések esetén:

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

Kihagyott eredmények

Olyan műveletek esetén, amelyek nem adnak vissza adatokat (például katalógus és/vagy adatfrissítések):

{
  "kind": "NOTHING"
}

Értéktípusok és kódolás

Az API egy gazdag típusú rendszert használ a GQL-értékek pontos szemantikával való ábrázolására. A GQL-értékek JSON formátuma diszkriminált egyesítési mintát követ.

Megjegyzés:

A táblázatos eredmények JSON-formátuma a megkülönböztetett egyesítési mintát a szétválasztással és gqlType a kompaktabb ábrázolás value elérésével valósítja meg. Lásd a táblázat szerializálásának optimalizálását.

Értékstruktúra

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

Primitív típusok

GQL-típus	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Natív JSON logikai érték
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 sztring

Numerikus típusok

Egész számtípusok

GQL-típus	Tartomány	JSON-szerializálás	Example
`INT64`	-2⁶³–2⁶³-1	Szám vagy sztring*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0-2⁶⁴-1	Szám vagy sztring*	`{"gqlType": "UINT64", "value": 18467}`

A JavaScript biztonságos tartományán kívül eső nagy egész számok (-9 007 199 254 740 991 és 9 007 199 254 740 991) sztringként vannak szerializálva:

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

Lebegőpontos típusok

GQL-típus	Tartomány	JSON-szerializálás	Example
`FLOAT64`	IEEE 754 bináris64	JSON-szám vagy sztring	`{"gqlType": "FLOAT64", "value": 3.14}`

A lebegőpontos értékek támogatják az IEEE 754 speciális értékeit:

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

Időbeli típusok

A támogatott időbeli típusok ISO 8601 sztringformátumokat használnak:

GQL-típus	Formátum	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Gráfelem referenciatípusai

GQL-típus	Description	Example
`NODE`	Gráfcsomópont-referencia	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Gráfszélek referenciája	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Összetett típusok

Az összetett típusok más GQL-értékekből állnak.

Lists

A listák null értékű tömböket tartalmaznak konzisztens elemtípusokkal:

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

Speciális listatípusok:

LIST<ANY> - Vegyes típusok (minden elem teljes típusinformációt tartalmaz)
LIST<NULL> – Csak null értékek engedélyezettek
LIST<NOTHING> - Mindig üres tömb

Paths

Az elérési utak gráfelem-referenciaértékek listájaként vannak kódolva.

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

Lásd a táblázat szerializálásának optimalizálását.

Táblázat szerializálásának optimalizálása

A táblaeredmények esetében az érték szerializálása oszloptípus-információk alapján van optimalizálva:

Ismert típusok – Csak a nyers érték szerializálva van
BÁRMELY oszlop – Teljes értékű objektum típuskriminatív használatával

{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Hibakezelés

Átviteli hibák

A hálózati és HTTP-átviteli hibák szabványos HTTP-hibaállapot-kódokat eredményeznek (4xx, 5xx).

Alkalmazáshibák

Az alkalmazásszintű hibák mindig HTTP 200-t adnak vissza az állapotobjektum hibainformációival:

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

Állapot ellenőrzése

A sikeresség megállapításához ellenőrizze az állapotkódot:

00A ,, 010203 a sikerességet jelző kódok (lehetséges figyelmeztetésekkel)
Minden más kód hibát jelez

Teljes példa az rest használatával

Futtasson egy lekérdezést a az rest paranccsal, hogy ne kelljen manuálisan beszereznie a tulajdonosi jogkivonatokat, például:

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

Teljes példa a curl használatával

Az ebben a szakaszban szereplő példa az eszközt használja a curl rendszerhéjból érkező HTTPS-kérések végrehajtásához.

Feltételezzük, hogy rendelkezik egy érvényes hozzáférési jogkivonattal, amely egy rendszerhéjváltozóban van tárolva, például:

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

Jótanács

Tekintse meg az érvényes tulajdonosi jogkivonat beszerzésének módját a hitelesítésről szóló szakaszban .

Futtasson egy lekérdezést a következőképpen:

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

Ajánlott eljárások

Kövesse ezeket az ajánlott eljárásokat a GQL Query API használatakor.

Hibakezelés

Mindig ellenőrizze az állapotkódokat – Ne feltételezze a HTTP 200 alapján a sikert.
Hiba részleteinek elemzése – Diagnosztikák és hibakeresési láncok használata.

Biztonság

HTTPS használata – Soha ne küldjön hitelesítési jogkivonatokat titkosítatlan kapcsolatokon keresztül.
Jogkivonatok elforgatása – A jogkivonatok megfelelő frissítésének és lejárati kezelésének megvalósítása.
Bemenetek ellenőrzése – A felhasználó által megadott lekérdezési paraméterek megtisztítása és megfelelő kikerülése a lekérdezésbe.

Értékábrázolás

Nagy egész számértékek kezelése – Az egész számok sztringekként vannak kódolva, ha natív JSON-számként nem jeleníthetők meg.
Speciális lebegőpontos értékek kezelése – A lekérdezésekből visszaadott lebegőpontos értékek lehetnek Infinity, -Infinityvagy NaN (nem számértékek).
Null értékek kezelése – A JSON null a GQL null értéket jelöli.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-20

GQL Query API-referencia

Áttekintés

Legfontosabb funkciók

Előfeltételek

Authentication

Felhasználó által delegált hozzáférés

Alkalmazáshozzáférés

API-végpont

HTTP-kérés fejlécek

Kérelem formája

Egyszerű kérelemstruktúra

Mezők kérése

Válaszformátum

Válaszstruktúra

Állapotobjektum

Állapotkódok

Diagnosztikai rekordok

Okok

Egyéb állapotobjektumok

Eredménytípusok

Táblaeredmények

Kihagyott eredmények

Értéktípusok és kódolás

Értékstruktúra

Primitív típusok

Numerikus típusok

Egész számtípusok

Lebegőpontos típusok

Időbeli típusok

Gráfelem referenciatípusai

Összetett típusok

Lists

Paths

Táblázat szerializálásának optimalizálása

Hibakezelés

Átviteli hibák

Alkalmazáshibák

Állapot ellenőrzése

Teljes példa az rest használatával

Teljes példa a curl használatával

Ajánlott eljárások

Hibakezelés

Biztonság

Értékábrázolás

Kapcsolódó tartalom

Visszajelzés

További források