Odkaz na rozhranie API dotazu GQL

Spustite dotazy GQL v grafoch vlastností v službe Microsoft Fabric pomocou rozhrania RESTful HTTP API. Tento odkaz popisuje zmluvu HTTP: formáty požiadavky a odpovede, overovanie, kódovanie výsledkov JSON a spracovanie chýb.

Dôležité

Tento článok výhradne používa príkladovú dátovú sadu grafov sociálnych sietí.

Prehľad

Rozhranie API dotazu GQL je jeden koncový bod (RPC cez HTTP), ktorý prijíma dotazy GQL ako údajové časti JSON a vracia štruktúrované, zadané výsledky. Rozhranie API je bez štátnej príslušnosti, spracováva overovanie a poskytuje komplexné hlásenie chýb.

Kľúčové funkcie

Jeden koncový bod – všetky operácie používajú http post na jednu URL adresu.
Založené na formáte JSON – údajové časti požiadaviek a odpovedí používajú formát JSON s bohatým kódovaním zadaných hodnôt GQL.
Bezštátne – medzi požiadavkami sa nevyžaduje žiadny stav relácie.
Zabezpečený typ – silný, gql kompatibilný s písaním s diskriminovanými zväzmi za znázornenie hodnoty.

Požiadavky

Potrebujete graf, ktorý obsahuje údaje vrátane uzlov a okrajov (vzťahov). Pozrite si stručný úvod k grafu a vytvorte a načítajte vzorový graf.
Mali by ste byť oboznámení s grafmi vlastností a základným pochopením jazyka GQL vrátane štruktúry výsledkov a výsledkov vykonávania.
Na prihlásenie do organizácie je potrebné nainštalovať a nastaviť nástroj Azure CLIaz. Príklady príkazového riadka v tomto článku predpokladajú použitie prostredia príkazového riadka kompatibilného s posix, ako je napríklad bash.

Overovanie

Rozhranie API dotazu GQL vyžaduje overenie prostredníctvom nosných tokenov.

Zahrňte svoj prístupový token do hlavičky Authorization každej požiadavky:

Authorization: Bearer <your-access-token>

Vo všeobecnosti môžete získať nosné tokeny pomocou Microsoft Authentication Library (MSAL) alebo iných postupov overovania kompatibilných s Microsoft Entra.

Nosné tokeny sa bežne získavajú prostredníctvom dvoch hlavných ciest:

Používateľmi delegovaný prístup

Nosné tokeny pre volania služby delegované používateľom môžete získať z príkazového riadka prostredníctvom nástroja Azure CLIaz.

Získanie nosného tokenu pre používateľom delegované volania z príkazového riadka pomocou:

Bežať az login
Potom az account get-access-token --resource https://api.fabric.microsoft.com

Používa nástroj Azure CLIaz.

Pri použití az rest na vykonanie požiadaviek sa automaticky získajú nosné tokeny.

Prístup k aplikácii

Môžete získať nosné tokeny pre aplikácie zaregistrované v službe Microsoft Entra. Ďalšie podrobnosti nájdete v stručnom úvode k rozhraniu API služby Fabric .

Koncový bod rozhrania API

Rozhranie API používa jeden koncový bod, ktorý akceptuje všetky operácie dotazu:

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

Ak chcete získať {workspaceId} povolenie pre svoj pracovný priestor, všetky dostupné pracovné priestory môžete zobraziť v zozname pomocou az rest:

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

Na získanie {graphId}hodnoty môžete vytvoriť zoznam všetkých dostupných grafov v pracovnom priestore pomocou :az rest

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

Na ďalšie zúženie výsledkov dotazu môžete použiť viac parametrov:

--query 'value[?displayName=='My Workspace'] keď uvádzate zoznam iba položiek s a displayName z typu My Workspace.
--query 'value[starts_with(?displayName='My')] keď uvádzate zoznam iba položiek, ktorých displayName zoznam sa začína na My.
--query '{query}' pre uvedenie len položiek, ktoré zodpovedajú zadanej hodnote JMESPath {query}. Pozrite si dokumentáciu Azure CLI v téme JMESPath v súvislosti s podporovanou syntaxou pre {query}.
-o table na vytvorenie výsledku tabuľky.

Poznámka

Pozrite si časť o používaní az-rest alebo časti o používaní kučier , kde nájdete postup na vykonanie dotazov prostredníctvom koncového bodu rozhrania API z prostredia príkazového riadka.

Hlavičky žiadosti

Záhlavie	Hodnota	Required
`Content-Type`	`application/json`	Áno
`Accept`	`application/json`	Áno
`Authorization`	`Bearer <token>`	Áno

Formát požiadavky

Všetky požiadavky používajú funkciu HTTP POST s údajovou časťou JSON.

Základná štruktúra požiadaviek

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

Polia požiadavky

Pole	Type	Required	Popis
`query`	reťazec	Áno	Dotaz GQL, ktorý sa má spustiť

Formát odpovede

Všetky odpovede na úspešné žiadosti používajú stav HTTP 200 s údajovou časťou JSON obsahujúcou stav spustenia a výsledky.

Štruktúra odpovede

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

Objekt Status

Každá odpoveď obsahuje objekt stavu s informáciami o spustení:

Pole	Type	Popis
`code`	reťazec	kód stavu šesť znakov (000 000 = úspech)
`description`	reťazec	Správa o stave čitateľnom ľuďmi
`diagnostics`	objekt	Podrobné diagnostické záznamy
`cause`	objekt	Voliteľný objekt stavu základnej príčiny

Kódy stavu

Kódy stavu sa riadia hierarchickým vzorom:

00xxxx – Dokončenie úspechu
01xxxx – Úspešné s upozorneniami
02xxxx – Úspech bez údajov
03xxxx - Úspech s informáciami
04xxxx a vyššie – chyby a podmienky výnimiek

Ďalšie informácie nájdete v téme Odkaz na kódy stavu jazyka GQL.

Diagnostické záznamy

Diagnostické záznamy môžu obsahovať ďalšie páry kľúča a hodnoty, ktoré podrobnejšie popisujú objekt stavu. Kľúče začínajúce reťazcom podčiarknutia (_) sú špecifické pre graf. V štandarde GQL sa predpíšu všetky ostatné kľúče.

Poznámka

Hodnoty v diagnostickom zázname kľúčov špecifických pre graf sú hodnoty GQL kódované použitím JSON. Pozrite si tému Typy hodnôt a kódovanie.

Spôsobuje

Objekty stavu zahŕňajú voliteľné cause pole, keď je známa základná príčina.

Iné objekty stavu

Niektoré výsledky môžu nahlásiť iné objekty stavu ako zoznam v poli (voliteľné). additionalStatuses

V takom prípade sa objekt primárneho stavu vždy určí ako najdôležitejší objekt stavu (napríklad podmienka výnimky), ako je predpísaný štandardom GQL.

Typy výsledkov

Výsledky používajú diskriminovaný vzor zjednotenia s poľom kind :

Výsledky tabuľky

Pre dotazy, ktoré vracajú tabuľkové údaje:

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

Pre operácie, ktoré nevracajú údaje (napríklad aktualizácie katalógu alebo údajov):

{
  "kind": "NOTHING"
}

Typy hodnôt a kódovanie

Rozhranie API používa systém bohatého typu na znázornenie hodnôt GQL s presnou sémantikou. Formát JSON hodnôt GQL sleduje diskriminovaný vzor zjednotenia.

Poznámka

Formát JSON tabuľkových výsledkov si uvedomuje diskriminovaný vzor zjednotenia gqlType tým, že rozdeľuje a value dosahuje kompaktnejšie vyjadrenie. Pozrite si tému Optimalizácia serializácie tabuliek.

Štruktúra hodnoty

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

Primitívne typy

Typ GQL	Príklad	Popis
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Natívny booleovský kód JSON
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Reťazec UTF-8

Číselné typy

Typy celých čísel

Typ GQL	Rozsah	JSON serializácia	Príklad
`INT64`	-2³ až 2³-1	Číslo alebo reťazec*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 až 2 – 1	Číslo alebo reťazec*	`{"gqlType": "UINT64", "value": 18467}`

Veľké celé čísla mimo bezpečného rozsahu JavaScriptu (–9 007 199 254 740 991 až 9 007 199 254 740 991) sa sériovo označujú ako reťazce:

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

Typy s pohyblivou desatinnou čiarkou

Typ GQL	Rozsah	JSON serializácia	Príklad
`FLOAT64`	IEEE 754 binary64	Číslo alebo reťazec JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Hodnoty s pohyblivou desatinnou čiarkou podporujú špeciálne hodnoty IEEE 754:

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

Časové typy

Podporované časové typy používajú formáty reťazcov ISO 8601:

Typ GQL	Format	Príklad
`ZONED DATETIME`	RRRR-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Referenčné typy prvkov grafu

Typ GQL	Popis	Príklad
`NODE`	Odkaz na uzol grafu	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Referenčné informácie k okrajom grafu	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Komplexné typy

Zložité typy pozostávajú z iných hodnôt GQL.

Zoznamov

Zoznamy obsahujú polia hodnôt s povolenou hodnotou null s konzistentnými typmi prvkov:

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

Špeciálne typy zoznamu:

LIST<ANY> – Kombinované typy (každý prvok obsahuje úplné informácie o type)
LIST<NULL> – Povolené sú iba hodnoty null
LIST<NOTHING> – Vždy prázdne pole

Cesty

Cesty sú kódované ako zoznamy referenčných hodnôt prvkov grafu.

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

Pozrite si tému Optimalizácia serializácie tabuliek.

Optimalizácia serializácie tabuliek

V prípade výsledkov tabuľky je serializácia hodnoty optimalizovaná na základe informácií o type stĺpca:

Známe typy – serializuje sa iba nespracovaná hodnota
ĽUBOVOĽNÉ stĺpce – objekt s celou hodnotou s diskriminačným typom

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

Spracovanie chýb

Chyby prenosu

Sieťové a HTTP chyby prenosu majú za následok štandardné kódy stavu chyby HTTP (4xx, 5xx).

Chyby aplikácie

Chyby na úrovni aplikácie vždy vracajú protokol HTTP 200 s informáciami o chybe v objekte stavu:

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

Ak chcete zistiť úspešnosť, skontrolujte kód stavu:

Kódy začínajúce na 00, 01, 02, 03 označujú úspech (s možnými upozorneniami)
Všetky ostatné kódy označujú chyby

Úplný príklad s az rest

Spustite dotaz pomocou príkazu , az rest aby ste nemuseli získavať nosné tokeny manuálne, naprí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" 
}'

Úplný príklad so kulmom

V príklade tejto časti sa používa curl nástroj na vykonávanie požiadaviek HTTPS z používateľského prostredia.

Predpokladáme, že máte platný prístupový token uložený v premennej shell, napríklad:

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

Tip

Ako získať platný nosný token nájdete v časti o overení .

Spustite dotaz ako napríklad:

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

Osvedčené postupy

Pri používaní rozhrania API dotazov GQL postupujte podľa týchto osvedčených postupov.

Spracovanie chýb

Vždy skontrolujte kódy stavu – Nepredpokladajte úspech na základe PROTOKOLU HTTP 200.
Analýza podrobností o chybe – používajte diagnostiku a spôsobuje reťazce na ladenie.

Zabezpečenie

Používanie protokolu HTTPS – nikdy neodosielať overovacie tokeny cez nešifrované pripojenia.
Rotovať tokeny – implementujte správne obnovenie tokenu a spracovanie uplynutia platnosti.
Overenie vstupov – dezinfikujte a správne ukončite všetky parametre dotazu poskytnuté používateľom vložené do dotazu.

Vyjadrenie hodnoty

Spracovanie veľkých celočíselných hodnôt – celé čísla sú kódované ako reťazce, ak nemôžu byť reprezentované ako čísla JSON natívne.
Spracovanie špeciálnych hodnôt s pohyblivou rádovou čiarkou – hodnoty s pohyblivou rádovou čiarkou vrátené z dotazov môžu byť Infinityhodnoty , -Infinityalebo NaN (nie číselné).
Spracovanie hodnôt null – JSON null predstavuje hodnotu GQL null.

Pripomienky

Bola táto stránka užitočná?

Last updated on 2026-05-20

Odkaz na rozhranie API dotazu GQL

Prehľad

Kľúčové funkcie

Požiadavky

Overovanie

Používateľmi delegovaný prístup

Prístup k aplikácii

Koncový bod rozhrania API

Hlavičky žiadosti

Formát požiadavky

Základná štruktúra požiadaviek

Polia požiadavky

Formát odpovede

Štruktúra odpovede

Objekt Status

Kódy stavu

Diagnostické záznamy

Spôsobuje

Iné objekty stavu

Typy výsledkov

Výsledky tabuľky

Vynechané výsledky

Typy hodnôt a kódovanie

Štruktúra hodnoty

Primitívne typy

Číselné typy

Typy celých čísel

Typy s pohyblivou desatinnou čiarkou

Časové typy

Referenčné typy prvkov grafu

Komplexné typy

Zoznamov

Cesty

Optimalizácia serializácie tabuliek

Spracovanie chýb

Chyby prenosu

Chyby aplikácie

Kontrola stavu

Úplný príklad s az rest

Úplný príklad so kulmom

Osvedčené postupy

Spracovanie chýb

Zabezpečenie

Vyjadrenie hodnoty

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií