Referenční informace k rozhraní API dotazů GQL

Spouštění dotazů GQL na grafy vlastností v grafu v Microsoft Fabric pomocí rozhraní RESTful HTTP API Tento odkaz popisuje kontrakt HTTP: formáty požadavků a odpovědí, ověřování, kódování výsledků JSON a zpracování chyb.

Důležité

Tento článek výhradně používá datovou sadu grafů ze sociálních sítí.

Přehled

GQL Query API zpřístupňuje REST endpoint, který přijímá GQL dotazy jako JSON payloady a vrací strukturované, typované výsledky. Podporuje pokračující dotazování u dotazů, které nedokončí během počáteční žádosti.

Klíčové funkce

Jeden koncový bod – Všechny operace používají HTTP POST k jedné adrese URL.
Založené na formátu JSON – Datové části požadavků a odpovědí používají JSON s bohatým kódováním hodnot GQL typu.
Pokračující dotazování – Dlouhodobé dotazy mohou pokračovat přes více HTTP požadavků.
Typ bezpečný - Silné, GQL kompatibilní psaní s diskriminovanými sjednoceními pro reprezentaci hodnot.

Požadavky

Potřebujete graf, který obsahuje data, včetně uzlů a hran (relací). Pokud chcete vytvořit a načíst ukázkový graf, podívejte se na rychlý start grafu .
Měli byste znát grafy vlastností a základní znalosti GQL, včetně struktury výsledků provádění a výsledků.
Musíte nainstalovat a nastavit nástroj Azure CLIaz pro přihlášení k vaší organizaci. Příklady příkazového řádku v tomto článku předpokládají použití prostředí příkazového řádku kompatibilního s POSIX, jako je bash.

Autentizace

Rozhraní API pro dotazy GQL vyžaduje ověřování prostřednictvím nosných tokenů.

Do autorizační hlavičky každého požadavku zahrňte přístupový token:

Authorization: Bearer <your-access-token>

Obecně platí, že nosné tokeny můžete získat pomocí Identity a ověřování Microsoftu (MSAL) nebo jiných toků ověřování kompatibilních s Microsoft Entra.

Nosné tokeny se běžně získávají prostřednictvím dvou hlavních cest:

Uživatelem delegovaný přístup

Nosné tokeny pro volání služby delegované uživatelem můžete získat z příkazového řádku prostřednictvím nástroje Azure CLIaz.

Získejte nosný token pro uživatelsky delegovaná volání z příkazového řádku pomocí:

Spusťte příkaz az login.
Potom az account get-access-token --resource https://api.fabric.microsoft.com

Používá se nástroj Azure CLIaz.

Při použití az rest k provádění požadavků se automaticky získají nosné tokeny.

Přístup k aplikacím

Nosné tokeny můžete získat pro aplikace zaregistrované v Microsoft Entra. Další podrobnosti najdete v rychlém startu k rozhraní API fabric .

Koncový bod rozhraní API

Rozhraní API používá jeden koncový bod, který přijímá všechny operace dotazů:

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

Query API je v beta verzi a není doporučeno pro produkční použití. Nastavte požadovaný beta dotazovací parametr na .true Starší preview=true parametr zůstává podporován pro zpětnou kompatibilitu, ale používá beta=true se pro nové integrace.

Pokud chcete získat pracovní {workspaceId} prostor, můžete zobrazit seznam všech dostupných pracovních prostorů pomocí az rest:

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

Pokud chcete získat {graphModelId}seznam všech dostupných grafů v pracovním prostoru, az restpoužijte:

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

Můžete použít výstupní možnosti Azure CLI k filtrování nebo formátování odpovědí z těchto požadavků na seznam. Tyto možnosti běží v klientu Azure CLI; nejsou to parametry Query API:

--query "value[?displayName=='My Workspace']"uvádí pouze položky s a displayName .My Workspace
--query "value[?starts_with(displayName, 'My')]" uvádí pouze položky, které začínají displayName na My.
--query "{query}" uvádí pouze položky, které odpovídají poskytnutému JMESPath {query}. Viz výsledky příkazů Query Azure CLI pro podporovanou syntaxi.
-o table pro vytvoření výsledku tabulky.

Poznámka:

Informace o spouštění dotazů prostřednictvím koncového bodu rozhraní API z prostředí příkazového řádku najdete v části o použití příkazu az-rest nebo oddílu o používání nástroje curl .

Parametry dotazu

Parametr	Typ	Povinné	Description
`beta`	boolean	Ano	Nastavte na `true` použití beta Query API.
`continuationToken`	řetězec	Ne	Token z `result.nextPage` doby, kdy dotaz stále běží. Při použití tokenu odesílejte stejný dotazovací text.

Hlavičky žádosti

Header	Hodnota	Povinné
`Content-Type`	`application/json`	Ano
`Accept`	`application/json`	Ano
`Authorization`	`Bearer <token>`	Ano

Formát požadavku

Všechny požadavky používají HTTP POST s datovou částí JSON.

Struktura základního požadavku

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

Pole žádosti

Obor	Typ	Povinné	Description
`query`	řetězec	Ano	Dotaz GQL ke spuštění

Formát odpovědi

Všechny odpovědi na úspěšné žádosti používají stav HTTP 200 s datovou částí JSON obsahující stav spuštění a výsledky.

Struktura odpovědi

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

Stavový objekt

Každá odpověď obsahuje stavový objekt s informacemi o spuštění:

Obor	Typ	Description
`code`	řetězec	Pětiznakový veřejný API stavový kód.
`description`	řetězec	Popis stavu čtivý pro člověka.
`diagnostics`	objekt	Podrobný diagnostický záznam, včetně kanonického dotazovacího enginu GQLSTATUS, pokud je k dispozici.
`cause`	objekt	Volitelný objekt stavu základní příčiny.

Stavové kódy

Primární status.code používá tyto kategorie veřejných API:

00000 - Úspěšné dokončení alespoň jedním řádkem.
00001 - Úspěšné dokončení s vynechaným výsledkem. Vyhrazeno pro budoucí podporu DDL a DML.
01000 - Varovný nebo informační stav.
02000 - V současné době nejsou k dispozici žádné řádky z dotazu generujícího řádky.
42000 - Chyba syntaxe, přístupového pravidla nebo jiné uživatelsky opravitelné chyby dotazu.
50000 - Systémová nebo neklasifikovaná chyba.

Další informace najdete v referenčních informacích ke stavových kódům GQL.

Diagnostické záznamy

Diagnostické záznamy můžou obsahovat další páry klíč-hodnota, které dále podrobně uvádějí stavový objekt. Klíče začínající podtržítkem (_) jsou specifické pro graf. Standard GQL předepisuje všechny ostatní klíče.

Poznámka:

Diagnostika _graphaneGqlStatus obsahuje kanonický pětiznakový GQLSTATUS hlášený dotazovacím enginem. Každý diagnostický člen s podtržíčkem obsahuje buď null JSON-kódovanou hodnotu GQL. Například používá _graphaneGqlStatusSTRING, zatímco diagnostika klasifikace chyb používá BOOL. Viz Typy hodnot a kódování.

Příčiny

Objekty stavu obsahují volitelné cause pole, pokud je známa základní příčina.

Další objekty stavu

Některé výsledky mohou zobrazit jiné stavové objekty jako seznam v volitelném additionalStatuses poli.

Primární stav je nejkritičtější zaznamenaný stav. Každý další status a vnořená příčina má svůj vlastní veřejný API kód a kanonickou diagnostiku GQLSTATUS.

Typy výsledků

Výsledky používají diskriminovaný sjednocovaný vzor s polem kind :

Výsledky tabulky

Dotazy, které vracejí tabulková data:

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

Dlouhotrvající dotazy

Pokud dotaz během aktuálního HTTP požadavku nedokončí, API vrátí HTTP 200 s veřejným stavovým kódem 02000, prázdnou tabulkou a tokenem nextPage :

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

Doplňovací dotaz se provádí odesláním stejného těla požadavku a přidáním tokenu do URL:

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

Považujte nextPage to za neprůhlednou hodnotu. Procentuálně jej zakódujte přesně jednou podle RFC 3986 před použitím jako hodnoty dotazovacího parametru continuationToken . Nedekódujte, nekontrolujte ani neupravujte token.

Pokračujte, dokud odpověď neobsahuje nextPage. Provádění dotazu může pokračovat až 20 minut od prvního požadavku. Pokud překročí tuto celkovou dobu, API vrátí HTTP 408 s chybovým kódem QueryTimeout.

Zkrácené výsledky

Graph zkracuje odpověď na dotaz, pokud jeho vnitřní binární reprezentace přesahuje 64 MB. API vrací řádky, které odpovídají, a přidává stav do additionalStatuses. Další status používá veřejný kód 01000 a zachovává kanonický GQLSTATUS 01M11 v _graphaneGqlStatus.

Zkrácení nevytváří nextPage token pro vynechané řádky. Dotaz zúžit pomocí filtrů, konkrétních projekcí nebo LIMIT, a pak ho znovu spustit.

Vynechané výsledky

Schéma odpovědí může představovat operaci, jejíž tvrzení nikdy nevytváří řádky, nezávisle na datech nebo výsledku vyhodnocení. Tento výsledek používá stavový kód 00001:

{
  "kind": "NOTHING"
}

Tento vynechaný výsledek se liší od tabulky bez řádků. Prázdná tabulka je výsledkem vyhodnocení dotazu produkujícího řádky, který momentálně nemá žádné řádky, které by bylo možné vrátit.

Graph si tento výsledkový tvar a stavový kód vyhrazuje pro budoucí podporu příkazů pro data definition language (DDL) a data manipulation language (DML). Aktuální dotazové příkazy vždy vracejí výsledky tabulky.

Typy hodnot a kódování

Rozhraní API používá systém bohatého typu k reprezentaci hodnot GQL s přesnou sémantikou. Formát JSON hodnot GQL se řídí diskriminovaným vzorem sjednocení.

Poznámka:

Formát JSON tabulkových výsledků si uvědomuje diskriminovaný sjednocovací vzor oddělením gqlType a value dosažením kompaktnější reprezentace. Viz Optimalizace serializace tabulky.

Struktura hodnot

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

Primitivní typy

Typ GQL	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Nativní logická hodnota JSON
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Řetězec UTF-8

Číselné typy

Celočíselné typy

Typ GQL	Rozmezí	Serializace JSON	Example
`INT64`	-2⁶³ až 2⁶³-1	Číslo nebo řetězec*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 až 2⁶⁴-1	Číslo nebo řetězec*	`{"gqlType": "UINT64", "value": 18467}`

Velká celá čísla mimo bezpečný rozsah JavaScriptu (-9 007 199 254 740 991 až 9 007 199 254 740 991) jsou serializována jako řetězce:

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

Typy s plovoucí desetinou čárkou

Typ GQL	Rozmezí	Serializace JSON	Example
`FLOAT64`	Binární IEEE 7544	Číslo nebo řetězec JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Hodnoty s plovoucí desetinou čárkou podporují speciální hodnoty IEEE 754:

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

Dočasné typy

Podporované dočasné typy používají formáty řetězců ISO 8601:

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

Referenční typy elementů grafu

Typ GQL	Description	Example
`NODE`	Referenční informace k uzlu grafu	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Referenční informace k okraji grafu	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Komplexní typy

Komplexní typy se skládají z jiných hodnot GQL.

Lists

Seznamy obsahují pole hodnot null s konzistentními typy prvků:

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

Speciální typy seznamů:

LIST<ANY> – Smíšené typy (každý prvek obsahuje úplné informace o typu)
LIST<NULL> – Jsou povoleny pouze hodnoty null.
LIST<NOTHING> – Vždy prázdné pole

Paths

Cesty jsou kódovány jako seznamy referenčních hodnot prvků grafu.

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

Viz Optimalizace serializace tabulky.

Optimalizace serializace tabulek

U výsledků tabulky je serializace hodnot optimalizovaná na základě informací o typu sloupce:

Známé typy – Serializuje se pouze nezpracovaná hodnota.
ANY sloupce – objekt úplné hodnoty s typem diskriminátoru

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

Zpracování chyb

Chyby přenosu

HTTP stav a GQL popsávají různé vrstvy odpovědi:

Stav HTTP	Význam
200	API zpracovalo požadavek. Kontrolujte `status.code` proto, že výsledek může představovat úspěch, žádné řádky, stále probíhající dotaz nebo uživatelsky opravovatelnou chybu dotazu.
408	Provedení dotazu překročilo celkový časový limit 20 minut. Chybový kód je .`QueryTimeout`
429	Byl překročen limit přenosové rychlosti služby. Počkejte na délku v hlavičce `Retry-After` , než to zkusíte znovu.
499	Volající žádost zrušil. Chybový kód je .`ClientCancelled`
Ostatní 4xx nebo 5xx	Požadavek nebo služba selhala před vrácením výsledku GQL vykonání. Prohlédněte si HTTP chybovou odpověď.

Chyby aplikace

Chyba na úrovni aplikace může vrátit HTTP 200 s chybovými informacemi ve stavovém objektu. Například dělení nulou používá veřejný API kód 42000 a uchovává kanonický GQLSTATUS 22012 v diagnostickém záznamu:

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

Kontrola stavu

Pro určení celkového výsledku se podívejte na veřejnost status.code. Použijte je _graphaneGqlStatus , když vaše aplikace potřebuje rozlišit konkrétní podmínku dotazovacího enginu, například numerický přetečení (22003) z dělení nulou (22012).

Kompletní příklad pomocí příkazu az rest

Spusťte dotaz pomocí az rest příkazu, abyste nemuseli získat nosné tokeny ručně, například takto:

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

Kompletní příklad s curl

Příklad v této části používá curl nástroj pro provádění požadavků HTTPS z prostředí.

Předpokládáme, že máte platný přístupový token uložený v proměnné prostředí, například takto:

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

Návod

Informace o tom, jak získat platný nosný token, najdete v části o ověřování .

Spusťte dotaz takto:

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

Osvědčené postupy

Při používání rozhraní API pro dotazy GQL postupujte podle těchto osvědčených postupů.

Zpracování chyb

Vždy zkontrolujte stavové kódy – nepředpokládáte úspěch na základě HTTP 200.
Parsování podrobností o chybách – K ladění použijte diagnostiku a řetězy příčin.

Zabezpečení

Používejte PROTOKOL HTTPS – Nikdy neposílejte ověřovací tokeny přes nešifrovaná připojení.
Obměna tokenů – Implementace správné aktualizace tokenu a zpracování vypršení platnosti
Ověřte vstupy – Ověřte a správně uskutečněte všechny uživatelem zadané hodnoty, které vaše aplikace vloží do dotazového textu.

Reprezentace hodnot

Zpracování velkých celočíselových hodnot – Celá čísla jsou kódovaná jako řetězce, pokud je nelze nativně reprezentovat jako čísla JSON.
Zvládněte speciální hodnoty s plovoucí desetinnou čárkou – API serializuje kladné nekonečno, záporné nekonečno, ne-číslo a mínus nulu jako "Inf", "-Inf", "NaN", a "-0".
Zpracování hodnot null – JSON null představuje hodnotu GQL null.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-29

Referenční informace k rozhraní API dotazů GQL

Přehled

Klíčové funkce

Požadavky

Autentizace

Uživatelem delegovaný přístup

Přístup k aplikacím

Koncový bod rozhraní API

Parametry dotazu

Hlavičky žádosti

Formát požadavku

Struktura základního požadavku

Pole žádosti

Formát odpovědi

Struktura odpovědi

Stavový objekt

Stavové kódy

Diagnostické záznamy

Příčiny

Další objekty stavu

Typy výsledků

Výsledky tabulky

Dlouhotrvající dotazy

Zkrácené výsledky

Vynechané výsledky

Typy hodnot a kódování

Struktura hodnot

Primitivní typy

Číselné typy

Celočíselné typy

Typy s plovoucí desetinou čárkou

Dočasné typy

Referenční typy elementů grafu

Komplexní typy

Lists

Paths

Optimalizace serializace tabulek

Zpracování chyb

Chyby přenosu

Chyby aplikace

Kontrola stavu

Kompletní příklad pomocí příkazu az rest

Kompletní příklad s curl

Osvědčené postupy

Zpracování chyb

Zabezpečení

Reprezentace hodnot

Související obsah

Váš názor

Další materiály