Dokumentacja interfejsu API zapytań GQL

Uwaga / Notatka

Ta funkcja jest obecnie w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie jest zalecana w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.

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

Interfejs API zapytań GQL to pojedynczy punkt końcowy (RPC za pośrednictwem protokołu HTTP), który akceptuje zapytania GQL jako ładunki JSON i zwraca ustrukturyzowane wyniki. Interfejs API jest bezstanowy, obsługuje uwierzytelnianie i zapewnia kompleksowe raportowanie błędów.

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.
Bezstanowy — brak wymaganego stanu sesji między żądaniami.
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?preview=true

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

Aby dokładniej zawęzić wyniki zapytania, możesz użyć większej liczby parametrów:

--query 'value[?displayName=='My Workspace'] do wyświetlania listy tylko elementów z wartością displayNameMy Workspace.
--query 'value[starts_with(?displayName='My')] do wyświetlania listy tylko elementów, których displayName początek to My.
--query '{query}' do wyświetlania listy tylko elementów pasujących do podanego elementu JMESPath {query}. Zapoznaj się z dokumentacją Azure CLI dotyczącą JMESPath dotyczącą obsługiwanej składni {query}.
-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.

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "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	sześcioznaczny kod stanu (000000 = powodzenie)
`description`	ciąg	Komunikat o stanie czytelnym dla człowieka
`diagnostics`	obiekt	Szczegółowe rekordy diagnostyczne
`cause`	obiekt	Opcjonalny obiekt stanu przyczyny źródłowej

Kody stanu

Kody stanu są zgodne ze wzorcem hierarchicznym:

00xxxx — Powodzenie
01xxxx — Powodzenie z ostrzeżeniami
02xxxx — Powodzenie bez danych
03xxxx — Powodzenie z informacjami
04xxxx i wyższe — błędy i warunki wyjątków

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

Wartości w rekordzie diagnostycznym kluczy specyficznych dla grafu to wartości GQL zakodowane w formacie JSON. 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 stanu jako listę w polu (opcjonalnie). additionalStatuses

Jeśli tak, obiekt stanu podstawowego jest zawsze określany jako najbardziej krytyczny obiekt stanu (taki jak warunek wyjątku) zgodnie ze standardem GQL.

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

Pominięto wyniki

W przypadku operacji, które nie zwracają danych (na przykład aktualizacje wykazu i/lub danych):

{
  "kind": "NOTHING"
}

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

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

Obsługa błędów

Błędy transportu

Błędy transportu sieci i PROTOKOŁU HTTP powodują standardowe kody stanu błędów HTTP (4xx, 5xx).

Błędy aplikacji

Błędy na poziomie aplikacji zawsze zwracają błąd HTTP 200 z informacjami o błędzie w obiekcie stanu:

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

Sprawdzanie stanu

Aby określić powodzenie, sprawdź kod stanu:

Kody rozpoczynające się od 00, , 010203 , wskazują powodzenie (z możliwymi ostrzeżeniami)
Wszystkie inne kody wskazują błędy

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

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

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.
Zweryfikuj dane wejściowe — zweryfikuj i odpowiednio uniknie wszystkich parametrów zapytania dostarczonych przez użytkownika wprowadzonych do 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 — wartości zmiennoprzecinkowe zwracane z zapytań mogą być Infinitywartościami , -Infinitylub NaN (nie liczbą).
Obsługa wartości null — wartość null JSON reprezentuje wartość null GQL.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-03-12

Udostępnij za pośrednictwem

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

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

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