Sdílet prostřednictvím

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

Poznámka:

Tato funkce je aktuálně ve verzi Public Preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v tématu Supplementální podmínky použití pro Microsoft Azure Verze Preview.

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

Rozhraní API pro dotazy GQL je jeden koncový bod (RPC přes HTTP), který přijímá dotazy GQL jako datové části JSON a vrací strukturované zadané výsledky. Rozhraní API je bezstavové, zpracovává ověřování a poskytuje komplexní hlášení chyb.

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.
  • Bezstavová – mezi požadavky není vyžadován žádný stav relace.
  • Typ bezpečný - Silné, GQL kompatibilní psaní s diskriminovanými sjednoceními pro reprezentaci hodnot.

Požadavky

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í Microsoft Authentication Library (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?preview=true

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

Další parametry můžete použít k dalšímu zúžení výsledků dotazu:

  • --query 'value[?displayName=='My Workspace']pro výpis pouze položek s položkou displayName .My Workspace
  • --query 'value[starts_with(?displayName='My')] pro výpis pouze položky, jejichž displayName začíná na My.
  • --query '{query}' pro výpis pouze položky, které odpovídají zadané JMESPath {query}. Informace o podporované syntaxi pro najdete v dokumentaci k Azure CLI v JMESPath0>.
  • -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 .

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "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 šestiznakový stavový kód (000000 = úspěch)
description řetězec Stavová zpráva čitelná pro člověka
diagnostics objekt Podrobné diagnostické záznamy
cause objekt Volitelný základní objekt stavu příčiny

Stavové kódy

Stavové kódy se řídí hierarchickým vzorem:

  • 00xxxx - Dokončení úspěchu
  • 01xxxx - Úspěch s upozorněními
  • 02xxxx - Úspěch bez dat
  • 03xxxx - Úspěch s informacemi
  • 04xxxx a vyšší – chyby a podmínky výjimky

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:

Hodnoty v diagnostickém záznamu klíčů specifických pro graf jsou hodnoty GQL kódované ve formátu JSON. 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 můžou hlásit jiné stavové objekty jako seznam v poli (volitelné). additionalStatuses

Pokud ano, primární stavový objekt je vždy určen jako nejdůležitější stavový objekt (například podmínka výjimky), jak je předepsáno standardem GQL.

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

Vynechané výsledky

Pro operace, které nevrací data (například katalog nebo aktualizace dat):

{
  "kind": "NOTHING"
}

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

Zpracování chyb

Chyby přenosu

Chyby přenosu sítě a PROTOKOLU HTTP vedou ke standardním stavovými kódy chyb HTTP (4xx, 5xx).

Chyby aplikace

Chyby na úrovni aplikace vždy vrací http 200 s informacemi o chybě ve stavovém objektu:

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

Kontrola stavu

Pokud chcete zjistit úspěch, zkontrolujte stavový kód:

  • Kódy začínající na 00, 01, 02označují 03 úspěch (s možnými upozorněními)
  • Všechny ostatní kódy označují chyby.

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

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

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 – Sanitize a správně uniknou všem parametrům dotazu zadaným uživatelem vloženým do dotazu.

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.
  • Zpracování speciálních hodnot s plovoucí desetinou čárkou – hodnoty s plovoucí desetinou čárkou vrácené z dotazů můžou být Infinityhodnoty , -Infinitynebo NaN (ne čísla).
  • Zpracování hodnot null – JSON null představuje hodnotu GQL null.

Související obsah

  • Last updated on