GQL-Abfrage-API-Referenz

Führen Sie GQL-Abfragen für Eigenschaftendiagramme in Microsoft Fabric mithilfe einer RESTful-HTTP-API aus. In dieser Referenz wird der HTTP-Vertrag beschrieben: Anforderungs- und Antwortformate, Authentifizierung, JSON-Ergebniscodierung und Fehlerbehandlung.

Überblick

Die GQL Query API stellt einen REST-Endpunkt bereit, der GQL-Abfragen als JSON-Payloads akzeptiert und strukturierte, typisierte Ergebnisse zurückgibt. Es unterstützt Fortsetzungs-Abfragen für Abfragen, die während der ersten Anfrage nicht abgeschlossen werden.

Wichtigste Funktionen

• Einzelner Endpunkt – Alle Vorgänge verwenden HTTP POST zu einer URL.
• JSON-basiert – Anforderungs- und Antwortnutzlasten verwenden JSON mit umfangreicher Codierung von typierten GQL-Werten.
• Fortsetzungs-Abfrage – Langlaufende Abfragen können über mehrere HTTP-Anfragen hinweg fortgesetzt werden.
• Typsicher - Starke, GQL-kompatible Typisierung mit diskriminierten Gewerkschaften für die Wertdarstellung.

Voraussetzungen

• Sie benötigen ein Diagramm, das Daten enthält, einschließlich Knoten und Kanten (Beziehungen). Sehen Sie sich die Schnellstartanleitung zum Erstellen und Laden eines Beispieldiagramms an.
• Sie sollten mit Eigenschaftendiagrammen und einem grundlegenden Verständnis von GQL vertraut sein, einschließlich der Struktur der Ausführungsergebnisse und -ergebnisse.
• Sie müssen das Tool Azure CLIaz installieren und einrichten, um sich bei Ihrer Organisation anzumelden. Befehlszeilenbeispiele in diesem Artikel gehen davon aus, dass eine POSIX-kompatible Befehlszeilenshell wie Bash verwendet wird.

Authentifizierung

Die GQL-Abfrage-API erfordert eine Authentifizierung über Bearertoken.

Fügen Sie Ihr Zugriffstoken in den Autorisierungsheader jeder Anforderung ein:

Authorization: Bearer <your-access-token>

Im Allgemeinen können Sie Bearertoken mit Microsoft Authentication Library (MSAL) (MSAL) oder anderen Authentifizierungsflüssen abrufen, die mit Microsoft Entra kompatibel sind.

Bearertoken werden häufig über zwei Hauptpfade abgerufen:

Benutzerdelegierter Zugriff

Sie können Bearertoken für benutzerdelegierte Dienstaufrufe über die Befehlszeile über das Tool Azure CLIaz abrufen.

Rufen Sie ein Bearertoken für benutzerdelegierte Aufrufe über die Befehlszeile ab:

• Führen Sie az login aus.
• Dann az account get-access-token --resource https://api.fabric.microsoft.com

Dies verwendet das tool Azure CLI tool az.

Wenn Sie zum Ausführen von Anforderungen verwenden az rest , werden Bearertoken automatisch abgerufen.

Anwendungszugriff

Sie können Bearertoken für Anwendungen abrufen, die in Microsoft Entra registriert sind. Weitere Informationen finden Sie in der Fabric-API-Schnellstart .

API-Endpunkt

Die API verwendet einen einzelnen Endpunkt, der alle Abfragevorgänge akzeptiert:

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

Die Query-API befindet sich in der Beta und wird für Produktionszwecke nicht empfohlen. Setze den erforderlichen beta Abfrageparameter auf true. Der ältere preview=true Parameter wird weiterhin für Abwärtskompatibilität unterstützt, aber für neue Integrationen verwendet beta=true .

Zum Abrufen des {workspaceId} Arbeitsbereichs können Sie alle verfügbaren Arbeitsbereiche auflisten:az rest

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

Um das {graphModelId}Zu erhalten, können Sie alle verfügbaren Diagramme in einem Arbeitsbereich auflisten, indem az restSie :

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

Sie können Azure CLI-Ausgabeoptionen verwenden, um die Antworten aus diesen Listenanfragen zu filtern oder zu formatieren. Diese Optionen laufen im Azure CLI-Client; sie sind keine Abfrage-API-Parameter:

• --query "value[?displayName=='My Workspace']" listet nur Elemente mit a displayName von My Workspaceauf.
• --query "value[?starts_with(displayName, 'My')]" listet nur Elemente auf, deren displayName Anfang mit My.
• --query "{query}" listet nur Elemente auf, die dem bereitgestellten JMESPath {query}entsprechen. Siehe Query Azure CLI-Befehlsresultate für die unterstützte Syntax.
• -o table zum Erstellen eines Tabellenergebnisses.

Abfrageparameter

Anforderungsheader

Anforderungsformat

Alle Anforderungen verwenden HTTP POST mit einer JSON-Nutzlast.

Grundlegende Anforderungsstruktur

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

Anforderungsfelder

Antwortformat

Alle Antworten für erfolgreiche Anforderungen verwenden den HTTP 200-Status mit JSON-Nutzlast mit Ausführungsstatus und Ergebnissen.

Antwortstruktur

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

Status-Objekt

Jede Antwort enthält ein Statusobjekt mit Ausführungsinformationen:

Statuscodes

Die Primary status.code verwendet diese öffentlichen API-Kategorien:

• 00000 - Erfolgreicher Abschluss mit mindestens einer Reihe.
• 00001 - Erfolgreicher Abschluss mit ausgelassenem Ergebnis. Reserviert für zukünftige DDL- und DML-Unterstützung.
• 01000 - Warnung oder Informationsbedingung.
• 02000 - Derzeit sind keine Zeilen von einer zeilenerzeugenden Abfrage verfügbar.
• 42000 - Syntax-, Zugriffsregel- oder andere benutzerkorrigierbare Abfragefehler.
• 50000 - System- oder unklassifizierter Fehler.

Weitere Informationen finden Sie in der GQL-Statuscodesreferenz.

Diagnosedatensätze

Diagnosedatensätze können andere Schlüsselwertpaare enthalten, die das Statusobjekt weiter detailliert angeben. Tasten, die mit einem Unterstrich (_) beginnen, sind spezifisch für Diagramme. Der GQL-Standard schreibt alle anderen Schlüssel vor.

Ursachen

Statusobjekte enthalten ein optionales cause Feld, wenn eine zugrunde liegende Ursache bekannt ist.

Andere Statusobjekte

Einige Ergebnisse können andere Statusobjekte als Liste im optionalen additionalStatuses Feld anzeigen.

Der primäre Status ist der kritischste dokumentierte Zustand. Jeder zusätzliche Status und jede verschachtelte Ursache hat ihren eigenen öffentlichen API-Code und die kanonische GQLSTATUS-Diagnose.

Ergebnistypen

Ergebnisse verwenden ein diskriminiertes Vereinigungsmuster mit dem kind Feld:

Tabellenergebnisse

Für Abfragen, die tabellarische Daten zurückgeben:

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

Lang laufende Abfragen

Wenn eine Abfrage während der aktuellen HTTP-Anfrage nicht abgeschlossen wird, gibt die API HTTP 200 mit öffentlichem Statuscode 02000, einer leeren Tabelle und einem nextPage Token zurück:

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

Abfrage auf Vollständigkeit erfolgen, indem man denselben Anfrage-Body sendet und das Token zur URL hinzufügt:

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

Behandle nextPage sie als undurchsichtigen Wert. Prozentkodieren Sie es genau einmal gemäß RFC 3986, bevor Sie es als continuationToken Abfrageparameter verwenden. Dekodieren, inspizieren oder das Token nicht verändern.

Fahren Sie fort, bis die Antwort nicht mehr enthält nextPage. Die Abfrageausführung kann bis zu 20 Minuten ab der ersten Anfrage fortgesetzt werden. Überschreitet sie diese Gesamtdauer, gibt die API HTTP 408 mit Fehlercode QueryTimeoutzurück.

Abgeschnittene Ergebnisse

Der Graph trunkiert eine Anfrageantwort, wenn seine interne Binärdarstellung 64 MB überschreitet. Die API gibt die passenden Zeilen zurück und fügt einen Status zu additionalStatuses. Der zusätzliche Status verwendet öffentlichen Code 01000 und bewahrt den kanonischen GQLSTATUS 01M11 in _graphaneGqlStatus.

Die Abschneidung erzeugt nextPage kein Token für die ausgelassenen Zeilen. Begrenzt die Abfrage mit Filtern, spezifischen Projektionen oder LIMIT, und führe sie dann erneut aus.

Ausgelassene Ergebnisse

Das Antwortschema kann eine Operation darstellen, deren Aussage keine Zeilen erzeugt, unabhängig von den Daten oder dem Bewertungsergebnis. Dieses Ergebnis verwendet den Statuscode:00001

{
  "kind": "NOTHING"
}

Dieses ausgelassene Ergebnis unterscheidet sich von einer Tabelle ohne Zeilen. Eine leere Tabelle ist das Ergebnis der Auswertung einer zeilenerzeugenden Abfrage, die derzeit keine Zeilen zu retournern hat.

Graph reserviert diesen Ergebnis-Form- und Statuscode für die Unterstützung zukünftiger Datendefinitionssprache (DDL) und Datenmanipulationssprache (DML). Aktuelle Abfrageanweisungen liefern immer Tabellenergebnisse.

Werttypen und Codierung

Die API verwendet ein umfangreiches Typsystem, um GQL-Werte mit präziser Semantik darzustellen. Das JSON-Format von GQL-Werten folgt einem diskriminierten Union-Muster.

Wertstruktur

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

Grundtypen

Numerische Typen

Ganzzahlige Typen

Große ganze Zahlen außerhalb des sicheren Bereichs von JavaScript (-9.007.199.254.740.991 bis 9.007.199.254.740.991) werden als Zeichenfolgen serialisiert:

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

Gleitkommatypen

Gleitkommawerte unterstützen IEEE 754-Sonderwerte:

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

Zeitliche Typen

Unterstützte zeitliche Typen verwenden ISO 8601-Zeichenfolgenformate:

Graph-Elementverweistypen

Komplexe Typen

Die komplexen Typen bestehen aus anderen GQL-Werten.

Lists

Listen enthalten Arrays mit nullablen Werten mit konsistenten Elementtypen:

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

Spezielle Listentypen:

• LIST<ANY> - Gemischte Typen (jedes Element enthält vollständige Typinformationen)
• LIST<NULL> - Nur Nullwerte zulässig
• LIST<NOTHING> - Immer leeres Array

Pfade

Pfade werden als Listen von Diagrammelementverweiswerten codiert.

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

Siehe Optimierung der Tabellen serialisierung.

Optimierung der Tabellen serialisierung

Für Tabellenergebnisse wird die Wert serialisierung basierend auf Spaltentypinformationen optimiert:

• Bekannte Typen – Nur der Rohwert wird serialisiert.
• ANY-Spalten - Vollwertobjekt mit Typdiskriminator

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

Fehlerbehandlung

Transportfehler

HTTP-Status und GQL-Status beschreiben verschiedene Ebenen der Antwort:

Anwendungsfehler

Ein Anwendungsfehler kann HTTP 200 mit Fehlerinformationen im Statusobjekt zurückgeben. Zum Beispiel verwendet die Division durch Null den öffentlichen API-Code 42000 und bewahrt den kanonischen GQL-Status 22012 im Diagnosedatensatz:

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

Statusüberprüfung

Um das allgemeine Ergebnis zu bestimmen, prüfen Sie die Öffentlichkeit status.code. Verwenden _graphaneGqlStatus Sie, wenn Ihre Anwendung eine bestimmte Abfrage-Engine-Bedingung, wie numerischen Überlauf (22003) von Division durch Null (22012) unterscheiden muss.

Vollständiges Beispiel mit az rest

Führen Sie eine Abfrage mit dem az rest Befehl aus, um zu vermeiden, dass Sie Bearertoken manuell abrufen müssen, z. 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" 
}'

Vollständiges Beispiel mit Curl

Im Beispiel in diesem Abschnitt wird das curl Tool zum Ausführen von HTTPS-Anforderungen aus der Shell verwendet.

Es wird davon ausgegangen, dass Sie über ein gültiges Zugriffstoken verfügen, das in einer Shellvariable gespeichert ist, z. B.:

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

Führen Sie eine Abfrage wie folgt aus:

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

Bewährte Methoden

Befolgen Sie diese bewährten Methoden, wenn Sie die GQL-Abfrage-API verwenden.

Fehlerbehandlung

• Statuscodes immer überprüfen – Gehen Sie nicht von Erfolg auf der Grundlage von HTTP 200 aus.
• Analysieren Sie Fehlerdetails : Verwenden Sie Diagnose- und Ursacheketten für das Debuggen.

Sicherheit

• Verwenden Sie HTTPS – Senden Sie Authentifizierungstoken niemals über unverschlüsselte Verbindungen.
• Drehen von Token – Implementieren der richtigen Tokenaktualisierung und Ablaufbehandlung.
• Eingaben validieren – Validieren und entfallen Sie alle vom Nutzer bereitgestellten Werte, die Ihre Anwendung in den Abfragetext einfügt.

Wertdarstellung

• Behandeln großer ganzzahliger Werte – Ganze Zahlen werden als Zeichenfolgen codiert, wenn sie nicht nativ als JSON-Zahlen dargestellt werden können.
• Handhabung spezieller Gleitkommawerte – Die API serialisiert positiv unendlich, minus unendlich, nicht eine Zahl und minus null als "Inf", "-Inf", "NaN", und "-0".
• Handhabung von Nullwerten – JSON-Null repräsentiert GQL-Null.

Verwandte Inhalte

• Diagrammdatenmodelle
• GQL-Sprachhandbuch
• GQL-Werte und Werttypen
• Referenz zu GQL-Statuscodes