Dokumentacja interfejsu API zapytań GQL

Uruchamianie zapytań GQL względem grafów właściwości na grafach w usłudze Microsoft Fabric przy użyciu interfejsu API HTTP RESTful. W tej dokumentacji opisano kontrakt HTTP: formaty żądań i odpowiedzi, uwierzytelnianie, kodowanie wyników JSON i obsługa błędów.

Ważne

Artykuł ten wykorzystuje wyłącznie przykładowy zbiór grafów sieci społecznościowych.

Przegląd

API GQL Query udostępnia punkt końcowy REST, który akceptuje zapytania GQL jako ładunki JSON i zwraca strukturalne, typowane wyniki. Obsługuje kontynuację ankiet dla zapytań, które nie kończą się podczas pierwszego żądania.

Kluczowe funkcje

Pojedynczy punkt końcowy — wszystkie operacje używają żądania HTTP POST do jednego adresu URL.
Oparte na formacie JSON — ładunki żądań i odpowiedzi używają kodu JSON z bogatym kodowaniem typowych wartości GQL.
Ankietowanie kontynuacyjne – Długotrwałe zapytania mogą być kontynuowane przez wiele zapytań HTTP.
Bezpieczny typ — silne, zgodne z GQL wpisywanie z dyskryminowanym związkiem dla reprezentacji wartości.

Wymagania wstępne

Potrzebny jest graf zawierający dane, w tym węzły i krawędzie (relacje). Zobacz przewodnik Szybki start dotyczący grafu , aby utworzyć i załadować przykładowy graf.
Należy zapoznać się z grafami właściwości i podstawową wiedzą na temat języka GQL, w tym strukturą wyników i wyników wykonywania.
Musisz zainstalować i skonfigurować narzędzie Azure CLIaz, aby zalogować się do organizacji. Przykłady wiersza polecenia w tym artykule zakładają użycie powłoki wiersza polecenia zgodnej z modelem POSIX, takiej jak powłoka Bash.

Authentication

Interfejs API zapytań GQL wymaga uwierzytelniania za pośrednictwem tokenów elementu nośnego.

Uwzględnij token dostępu w nagłówku autoryzacji każdego żądania:

Authorization: Bearer <your-access-token>

Ogólnie rzecz biorąc, można uzyskać tokeny elementu nośnego przy użyciu Microsoft Authentication Library (MSAL) lub innych przepływów uwierzytelniania zgodnych z Microsoft Entra.

Tokeny elementu nośnego są często uzyskiwane za pomocą dwóch głównych ścieżek:

Dostęp delegowany przez użytkownika

Tokeny elementu nośnego dla wywołań usługi delegowanej przez użytkownika można uzyskać z wiersza polecenia za pośrednictwem Azure CLI narzędzia az.

Pobierz token elementu nośnego dla wywołań delegowanych przez użytkownika z wiersza polecenia za pomocą:

Uruchom az login
Wtedy az account get-access-token --resource https://api.fabric.microsoft.com

Używa to narzędzia Azure CLIaz.

W przypadku używania az rest do wykonywania żądań tokeny elementu nośnego są uzyskiwane automatycznie.

Dostęp do aplikacji

Tokeny elementu nośnego można uzyskać dla aplikacji zarejestrowanych w Microsoft Entra. Aby uzyskać więcej informacji, zapoznaj się z przewodnikiem Szybki start dotyczący interfejsu API sieci szkieletowej .

Punkt końcowy interfejsu API

Interfejs API używa pojedynczego punktu końcowego, który akceptuje wszystkie operacje zapytań:

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

API Query jest w fazie beta i nie jest zalecane do użytku produkcyjnego. Ustaw beta wymagany parametr zapytania na .true Starszy preview=true parametr pozostaje wspierany dla kompatybilności wstecznej, ale jest beta=true używany do nowych integracji.

Aby uzyskać element {workspaceId} dla obszaru roboczego, możesz wyświetlić listę wszystkich dostępnych obszarów roboczych przy użyciu polecenia az rest:

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

Aby uzyskać element {graphModelId}, możesz wyświetlić listę wszystkich dostępnych grafów w obszarze roboczym przy użyciu polecenia az rest:

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

Możesz użyć opcji wyjściowych Azure CLI, aby filtrować lub formatować odpowiedzi z tych list. Te opcje działają w kliencie Azure CLI; nie są to parametry API zapytań:

--query "value[?displayName=='My Workspace']"Zawiera tylko elementy z .displayNameMy Workspace
--query "value[?starts_with(displayName, 'My')]" zawiera tylko elementy, których displayName początki zaczynają się od My.
--query "{query}" zawiera tylko elementy odpowiadające dostarczonemu JMESPath {query}. Zobacz wyniki poleceń Query Azure CLI dla obsługiwanej składni.
-o table w celu utworzenia wyniku tabeli.

Uwaga / Notatka

Zobacz sekcję dotyczącą korzystania z polecenia az-rest lub sekcji dotyczącej używania narzędzia curl , aby dowiedzieć się, jak wykonywać zapytania za pośrednictwem punktu końcowego interfejsu API z poziomu powłoki wiersza polecenia.

Parametry zapytania

Parametr	Typ	Wymagania	Description
`beta`	boolean	Tak	Ustaw na `true` użycie beta Query API.
`continuationToken`	ciąg	Nie.	Token z `result.nextPage` czasów, gdy zapytanie nadal działa. Wyślij ten sam tekst zapytania, gdy używasz tokena.

Nagłówki zapytań

Header	Wartość	Wymagania
`Content-Type`	`application/json`	Tak
`Accept`	`application/json`	Tak
`Authorization`	`Bearer <token>`	Tak

Format żądania

Wszystkie żądania używają żądania HTTP POST z ładunkiem JSON.

Podstawowa struktura żądań

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

Pola żądania

(No changes needed)	Typ	Wymagania	Description
`query`	ciąg	Tak	Zapytanie GQL do wykonania

Format odpowiedzi

Wszystkie odpowiedzi dotyczące pomyślnych żądań używają stanu HTTP 200 z ładunkiem JSON zawierającym stan wykonania i wyniki.

Struktura odpowiedzi

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

Obiekt stanu

Każda odpowiedź zawiera obiekt stanu z informacjami o wykonaniu:

(No changes needed)	Typ	Description
`code`	ciąg	Pięcioznakowy publiczny kod statusu API.
`description`	ciąg	Czytelny dla człowieka opis statusu.
`diagnostics`	obiekt	Szczegółowy zapis diagnostyczny, w tym kanoniczny silnik zapytań GQLSTATUS, gdy jest dostępny.
`cause`	obiekt	Opcjonalny obiekt statusu przyczyny podstawowej.

Kody stanu

Główny status.code korzysta z następujących kategorii publicznych API:

00000 - Pomyślne ukończenie z co najmniej jednym wierszem.
00001 - Pomyślne ukończenie z pominiętym wynikiem. Zarezerwowane na przyszłe wsparcie DDL i DML.
01000 - Stan ostrzegawczy lub informacyjny.
02000 - Obecnie nie ma dostępnych wierszy z zapytania generującego wiersze.
42000 - Błąd składni, reguły dostępu lub innego błędu zapytania możliwy do poprawy przez użytkownika.
50000 - Błąd systemowy lub nieklasyfikowany.

Aby uzyskać więcej informacji, zobacz dokumentację kodów stanu GQL.

Rekordy diagnostyczne

Rekordy diagnostyczne mogą zawierać inne pary klucz-wartość, które szczegółowo opisują obiekt stanu. Klucze rozpoczynające się od podkreślenia (_) są specyficzne dla grafu. Standard GQL określa wszystkie inne klucze.

Uwaga / Notatka

Diagnostyka _graphaneGqlStatus zawiera kanoniczny, pięcioznakowy GQLSTATUS raportowany przez silnik zapytań. Każdy członek diagnostyczny z podkreśleniem zawiera albo null lub wartość GQL zakodowaną przez JSON. Na przykład używa _graphaneGqlStatusSTRING, podczas gdy diagnostyka klasyfikacji błędów używa BOOL. Zobacz Typy wartości i kodowanie.

Przyczyny

Obiekty stanu zawierają pole opcjonalne cause , gdy znana jest podstawowa przyczyna.

Inne obiekty stanu

Niektóre wyniki mogą zgłaszać inne obiekty statusu jako listę w polu opcjonalnym additionalStatuses .

Status pierwotny jest najważniejszym odnotowanym stanem. Każdy dodatkowy status i zagnieżdżona przyczyna ma własny publiczny kod API oraz kanoniczną diagnostykę GQLSTATUS.

Typy wyników

Wyniki używają wzorca związków dyskryminowanych z polem kind :

Wyniki tabeli

W przypadku zapytań, które zwracają dane tabelaryczne:

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

Długotrwałe zapytania

Jeśli zapytanie nie zostanie zakończone podczas bieżącego żądania HTTP, API zwraca HTTP 200 z publicznym kodem 02000statusu, pustą tabelą i tokenem nextPage :

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

Polluj do zakończenia, wysyłając to samo ciało żądania i dodając token do URL:

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

Traktuj nextPage to jako wartość nieprzezroczystą. Koduj go procentowo dokładnie raz zgodnie z RFC 3986 przed użyciem jako wartości parametru continuationToken zapytania. Nie dekoduj, nie kontroluj ani nie modyfikuj tokena.

Kontynuuj, aż odpowiedź przestanie zawierać nextPage. Wykonywanie zapytań może trwać do 20 minut od pierwszego żądania. Jeśli przekroczy ten całkowity czas, API zwraca HTTP 408 z kodem QueryTimeoutbłędu .

Wyniki skrócone

Graph skraca odpowiedź zapytania, gdy jego wewnętrzna reprezentacja binarna przekracza 64 MB. API zwraca wiersze, które pasują, i dodaje status do additionalStatuses. Dodatkowy status korzysta z kodu 01000 publicznego i zachowuje kanoniczny GQLSTATUS 01M11 w _graphaneGqlStatus.

Obcięcie nie generuje nextPage tokena dla pominiętych wierszy. Zawęż zapytanie za pomocą filtrów, konkretnych projekcji lub LIMIT, a następnie uruchom je ponownie.

Pominięto wyniki

Schemat odpowiedzi może reprezentować operację, której zdanie nigdy nie generuje wierszy, niezależnie od danych lub wyniku oceny. Ten wynik wykorzystuje kod 00001statusu:

{
  "kind": "NOTHING"
}

Ten pominięty wynik różni się od tabeli bez wierszy. Pusta tabela jest wynikiem oceny zapytania generującego wiersze, które obecnie nie ma wierszy do zwrócenia.

Graph zachowuje ten kształt i kod statusu dla przyszłego wsparcia dla przyszłych instrukcji data definition language (DDL) oraz data manipulation language (DML). Aktualne instrukcje zapytań zawsze zwracają wyniki tabeli.

Typy wartości i kodowanie

Interfejs API używa systemu bogatego typu do reprezentowania wartości GQL z precyzyjnymi semantykami. Format JSON wartości GQL jest zgodny ze wzorcem związków dyskryminowanych.

Uwaga / Notatka

Format JSON wyników tabelarycznych zdaje sobie sprawę ze wzorca dyskryminowanego związku poprzez oddzielenie gqlType i value osiągnięcie bardziej kompaktowej reprezentacji. Zobacz Optymalizacja serializacji tabel.

Struktura wartości

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

Typy pierwotne

Typ GQL	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Natywna wartość logiczna JSON
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Ciąg UTF-8

Typy liczbowe

Typy liczb całkowitych

Typ GQL	Zakres	Serializacja JSON	Example
`INT64`	-2⁶³ do 2⁶³-1	Liczba lub ciąg*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	Od 0 do 2⁶⁴-1	Liczba lub ciąg*	`{"gqlType": "UINT64", "value": 18467}`

Duże liczby całkowite poza zakresem bezpiecznym języka JavaScript (-9 007 199 254 740 991 do 9007 199 254 740 991) są serializowane jako ciągi:

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

Typy zmiennoprzecinkowe

Typ GQL	Zakres	Serializacja JSON	Example
`FLOAT64`	IEEE 754 binary64	Liczba lub ciąg JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Wartości zmiennoprzecinkowe obsługują specjalne wartości IEEE 754:

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

Typy czasowe

Obsługiwane typy czasowe używają formatów ciągów ISO 8601:

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

Typy referencyjne elementów programu Graph

Typ GQL	Description	Example
`NODE`	Dokumentacja węzła programu Graph	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Dokumentacja krawędzi grafu	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Typy złożone

Typy złożone składają się z innych wartości GQL.

Lists

Listy zawierają tablice wartości dopuszczanych do wartości null z spójnymi typami elementów:

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

Specjalne typy list:

LIST<ANY> - Typy mieszane (każdy element zawiera pełne informacje o typie)
LIST<NULL> - Dozwolone są tylko wartości null
LIST<NOTHING> — Zawsze pusta tablica

Paths

Ścieżki są kodowane jako listy wartości odwołań elementów grafu.

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

Zobacz Optymalizacja serializacji tabel.

Optymalizacja serializacji tabel

W przypadku wyników tabeli serializacji wartości jest zoptymalizowana na podstawie informacji o typie kolumny:

Znane typy — tylko nieprzetworzona wartość jest serializowana
KOLUMNY ANY — obiekt pełnej wartości z dyskryminującym typem

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

Obsługa błędów

Błędy transportu

Status HTTP i status GQL opisują różne warstwy odpowiedzi:

Kod statusu HTTP	Meaning
200	API przetwarzało żądanie. Inspekcja `status.code` , ponieważ wynik może oznaczać sukces, brak wierszy, wciąż trwające zapytanie lub błąd podatny na poprawę przez użytkownika.
408	Wykonanie zapytań przekroczyło łączny 20-minutowy limit. Kod błędu to `QueryTimeout`.
429	Przekroczono limit szybkości usługi. Poczekaj na czas trwania w nagłówku `Retry-After` , zanim spróbujesz ponownie.
499	Dzwoniący anulował prośbę. Kod błędu to `ClientCancelled`.
Inne 4xx lub 5xx	Żądanie lub usługa nie powiodła się, zanim zwrócono wynik wykonania GQL. Sprawdź odpowiedź na błędy HTTP.

Błędy aplikacji

Błąd na poziomie aplikacji może zwrócić HTTP 200 z informacjami o błędzie w obiekcie statusu. Na przykład dzielenie przez zero korzysta z publicznego kodu 42000 API i zachowuje kanoniczny status GQLSTATUS 22012 w rekordzie diagnostycznym:

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

Sprawdzanie stanu

Aby określić ogólny wynik, sprawdź publiczność status.code. Używaj, _graphaneGqlStatus gdy Twoja aplikacja musi rozróżnić konkretny warunek silnika zapytań, na przykład przelew numeryczny (22003) od dzielenia przez zero (22012).

Kompletny przykład za pomocą polecenia az rest

Uruchom zapytanie przy użyciu polecenia , az rest aby uniknąć konieczności ręcznego uzyskiwania tokenów elementu nośnego, w następujący sposób:

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

Kompletny przykład za pomocą narzędzia curl

W przykładzie w tej sekcji użyto curl narzędzia do wykonywania żądań HTTPS z powłoki.

Zakładamy, że masz prawidłowy token dostępu przechowywany w zmiennej powłoki, w następujący sposób:

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

Wskazówka

Zobacz sekcję dotyczącą uwierzytelniania, aby uzyskać prawidłowy token elementu nośnego.

Uruchom zapytanie w następujący sposób:

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

Najlepsze rozwiązania

Postępuj zgodnie z tymi najlepszymi rozwiązaniami podczas korzystania z interfejsu API zapytań GQL.

Obsługa błędów

Zawsze sprawdzaj kody stanu — nie zakładaj powodzenia na podstawie protokołu HTTP 200.
Analizowanie szczegółów błędu — użyj diagnostyki i łańcuchów przyczyn debugowania.

Zabezpieczenia

Użyj protokołu HTTPS — nigdy nie wysyłaj tokenów uwierzytelniania za pośrednictwem nieszyfrowanych połączeń.
Obracanie tokenów — implementowanie prawidłowego odświeżania i wygasania tokenów.
Walidacja danych wejściowych – Waliduj i poprawnie uciekaj z wszelkich wartości podanych przez użytkownika, które aplikacja wstawia do tekstu zapytania.

Reprezentacja wartości

Obsługa dużych wartości całkowitych — liczby całkowite są kodowane jako ciągi, jeśli nie mogą być reprezentowane jako liczby JSON natywnie.
Obsługa specjalnych wartości zmiennoprzecinkowych – API serializuje dodatnią nieskończoność, ujemną nieskończoność, nie-liczbę i zero jako "Inf", "-Inf", "NaN", oraz "-0".
Obsługa wartości null — wartość null JSON reprezentuje wartość null GQL.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-29

Dokumentacja interfejsu API zapytań GQL

Przegląd

Kluczowe funkcje

Wymagania wstępne

Authentication

Dostęp delegowany przez użytkownika

Dostęp do aplikacji

Punkt końcowy interfejsu API

Parametry zapytania

Nagłówki zapytań

Format żądania

Podstawowa struktura żądań

Pola żądania

Format odpowiedzi

Struktura odpowiedzi

Obiekt stanu

Kody stanu

Rekordy diagnostyczne

Przyczyny

Inne obiekty stanu

Typy wyników

Wyniki tabeli

Długotrwałe zapytania

Wyniki skrócone

Pominięto wyniki

Typy wartości i kodowanie

Struktura wartości

Typy pierwotne

Typy liczbowe

Typy liczb całkowitych

Typy zmiennoprzecinkowe

Typy czasowe

Typy referencyjne elementów programu Graph

Typy złożone

Lists

Paths

Optymalizacja serializacji tabel

Obsługa błędów

Błędy transportu

Błędy aplikacji

Sprawdzanie stanu

Kompletny przykład za pomocą polecenia az rest

Kompletny przykład za pomocą narzędzia curl

Najlepsze rozwiązania

Obsługa błędów

Zabezpieczenia

Reprezentacja wartości

Treści powiązane

Opinia

Dodatkowe zasoby