Teilen über

GQL-Abfrage-API-Referenz

Hinweis

Dieses Feature ist zurzeit als öffentliche Preview verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und ist nicht für Produktionsworkloads vorgesehen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

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.

Von Bedeutung

In diesem Artikel wird ausschließlich das Beispieldiagramm-Dataset für soziale Netzwerke verwendet.

Überblick

Die GQL-Abfrage-API ist ein einzelner Endpunkt (RPC über HTTP), der GQL-Abfragen als JSON-Nutzlasten akzeptiert und strukturierte, typierte Ergebnisse zurückgibt. Die API ist zustandslos, behandelt die Authentifizierung und bietet umfassende Fehlerberichte.

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.
  • Statuslos – Kein Sitzungszustand zwischen Anforderungen erforderlich.
  • Typsicher - Starke, GQL-kompatible Typisierung mit diskriminierten Gewerkschaften für die Wertdarstellung.

Voraussetzungen

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) 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 Azure CLI-Toolazabrufen.

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 Azure CLI-Toolaz.

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?preview=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 {graphId}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 weitere Parameter verwenden, um Abfrageergebnisse weiter einzugrenzen:

  • --query 'value[?displayName=='My Workspace'] für die Auflistung nur Elemente mit einer displayName von My Workspace.
  • --query 'value[starts_with(?displayName='My')] für die Auflistung nur Elemente, deren displayName Start mit My.
  • --query '{query}' für die Auflistung nur Elemente, die mit dem bereitgestellten JMESPath {query}übereinstimmen. Weitere Informationen zur unterstützten Syntax finden Sie in der Azure CLI-Dokumentation zu JMESPath.{query}
  • -o table zum Erstellen eines Tabellenergebnisses.

Hinweis

Informationen zum Ausführen von Abfragen über den API-Endpunkt über eine Befehlszeilenshell finden Sie im Abschnitt zur Verwendung von az-rest oder im Abschnitt zur Verwendung von Curl .

Anforderungsheader

Header Wert Erforderlich
Content-Type application/json Yes
Accept application/json Yes
Authorization Bearer <token> Yes

Anforderungsformat

Alle Anforderungen verwenden HTTP POST mit einer JSON-Nutzlast.

Grundlegende Anforderungsstruktur

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

Anforderungsfelder

Feld Typ Erforderlich Description
query Schnur Yes Die auszuführende GQL-Abfrage

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Status-Objekt

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

Feld Typ Description
code Schnur Sechsstelligen Statuscode (0000000 = Erfolg)
description Schnur Lesbare Statusmeldung
diagnostics Objekt Detaillierte Diagnosedatensätze
cause Objekt Optionales zugrunde liegendes Ursachenstatusobjekt

Statuscodes

Statuscodes folgen einem hierarchischen Muster:

  • 00xxxx - Vollständiger Erfolg
  • 01xxxx - Erfolg mit Warnungen
  • 02xxxx - Erfolg ohne Daten
  • 03xxxx - Erfolg mit Informationen
  • 04xxxx und höher – Fehler und Ausnahmebedingungen

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 für Microsoft Fabric spezifisch. Der GQL-Standard schreibt alle anderen Schlüssel vor.

Hinweis

Werte im Diagnosedatensatz von Schlüsseln, die für Diagramme in Microsoft Fabric spezifisch sind JSON-codierte GQL-Werte. Siehe Werttypen und Codierung.

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 melden.

Wenn ja, wird das primäre Statusobjekt immer als das kritischste Statusobjekt (z. B. eine Ausnahmebedingung) festgelegt, wie es vom GQL-Standard vorgeschrieben ist.

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

Ausgelassene Ergebnisse

Für Vorgänge, die keine Daten zurückgeben (z. B. Katalog- und/oder Datenaktualisierungen):

{
  "kind": "NOTHING"
}

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.

Hinweis

Das JSON-Format von tabellarischen Ergebnissen realisiert das diskriminierte Union-Muster durch Trennen gqlType und value Erzielen einer kompakteren Darstellung. Siehe Optimierung der Tabellen serialisierung.

Wertstruktur

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

Grundtypen

GQL-Typ Example Description
BOOL {"gqlType": "BOOL", "value": true} Natives JSON-Boolean
STRING {"gqlType": "STRING", "value": "Hello"} UTF-8-Zeichenfolge

Numerische Typen

Ganzzahlige Typen

GQL-Typ Bereich JSON-Serialisierung Example
INT64 -2⁶¹ bis 2⁶¹-1 Zahl oder Zeichenfolge* {"gqlType": "INT64", "value": -9237}
UINT64 0 bis 2⁶⁴-1 Zahl oder Zeichenfolge* {"gqlType": "UINT64", "value": 18467}

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

GQL-Typ Bereich JSON-Serialisierung Example
FLOAT64 IEEE 754 binär64 JSON-Nummer oder -Zeichenfolge {"gqlType": "FLOAT64", "value": 3.14}

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:

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

Graph-Elementverweistypen

GQL-Typ Description Example
NODE Graph-Knotenverweis {"gqlType": "NODE", "value": "node-123"}
EDGE Graph-Edgeverweis {"gqlType": "EDGE", "value": "edge_abc#def"}

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

Fehlerbehandlung

Transportfehler

Netzwerk- und HTTP-Transportfehler führen zu standardmäßigen HTTP-Fehlerstatuscodes (4xx, 5xx).

Anwendungsfehler

Fehler auf Anwendungsebene geben immer HTTP 200 mit Fehlerinformationen im Statusobjekt zurück:

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

Statusüberprüfung

Überprüfen Sie den Statuscode, um den Erfolg zu ermitteln:

  • Codes beginnend mit 00, 01, 02, geben 03 Erfolg an (mit möglichen Warnungen)
  • Alle anderen Codes deuten auf Fehler hin

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

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"

Tipp

Informationen zum Abrufen eines gültigen Bearertokens finden Sie im Abschnitt zur Authentifizierung .

Führen Sie eine Abfrage wie folgt aus:

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

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.
  • Überprüfen Von Eingaben – Entfernen und ordnungsgemäßes Escapen aller vom Benutzer bereitgestellten Abfrageparameter, die in die Abfrage eingefügt wurden.

Wertdarstellung

  • Behandeln großer ganzzahliger Werte – Ganze Zahlen werden als Zeichenfolgen codiert, wenn sie nicht nativ als JSON-Zahlen dargestellt werden können.
  • Behandeln sie spezielle Gleitkommawerte : Gleitkommawerte , die von Abfragen zurückgegeben werden, können Werte sein Infinity, -Infinityoder NaN (keine Zahlen).
  • Handhabung von Nullwerten – JSON-Null repräsentiert GQL-Null.

Verwandte Inhalte

  • Last updated on