Partager via

Informations de référence sur l’API de requête GQL

Note

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service, et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Supplemental Conditions d’utilisation pour les préversions Microsoft Azure.

Exécutez des requêtes GQL sur des graphiques de propriétés dans Microsoft Fabric à l’aide d’une API HTTP RESTful. Cette référence décrit le contrat HTTP : formats de requête et de réponse, authentification, encodage des résultats JSON et gestion des erreurs.

Important

Cet article utilise exclusivement l’exemple de jeu de données de graphe de réseau social.

Aperçu

L’API de requête GQL est un point de terminaison unique (RPC sur HTTP) qui accepte les requêtes GQL en tant que charges utiles JSON et retourne des résultats structurés et typés. L’API est sans état, gère l’authentification et fournit un rapport d’erreurs complet.

Fonctionnalités clés

  • Point de terminaison unique : toutes les opérations utilisent HTTP POST sur une URL.
  • Basé sur JSON : les charges utiles de requête et de réponse utilisent JSON avec un encodage enrichi de valeurs GQL typées.
  • Sans état : aucun état de session requis entre les requêtes.
  • Type sécurisé : frappe forte et compatible GQL avec des unions discriminatoires pour la représentation de valeur.

Prerequisites

Authentication

L’API de requête GQL nécessite l’authentification via des jetons du porteur.

Incluez votre jeton d’accès dans l’en-tête d’autorisation de chaque requête :

Authorization: Bearer <your-access-token>

En général, vous pouvez obtenir des jetons du porteur à l’aide de Microsoft Authentication Library (MSAL) ou d’autres flux d’authentification compatibles avec Microsoft Entra.

Les jetons du porteur sont couramment obtenus via deux chemins principaux :

Accès délégué par l’utilisateur

Vous pouvez obtenir des jetons de porteur pour les appels de service délégués par l’utilisateur à partir de la ligne de commande via l’outil Azure CLIaz.

Obtenez un jeton de porteur pour les appels délégués par l’utilisateur à partir de la ligne de commande par :

  • exécuter az login.
  • Alors az account get-access-token --resource https://api.fabric.microsoft.com

Cela utilise l’outil Azure CLIaz.

Lorsque vous utilisez az rest pour effectuer des requêtes, les jetons du porteur sont obtenus automatiquement.

Accès aux applications

Vous pouvez obtenir des jetons du porteur pour les applications inscrites dans Microsoft Entra. Pour plus d’informations, consultez le guide de démarrage rapide de l’API Fabric .

Point de terminaison d’API

L’API utilise un point de terminaison unique qui accepte toutes les opérations de requête :

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

Pour obtenir l’espace {workspaceId} de travail, vous pouvez répertorier tous les espaces de travail disponibles à l’aide de az rest:

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

Pour obtenir le {graphId}, vous pouvez répertorier tous les graphiques disponibles dans un espace de travail à l’aide de az rest:

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

Vous pouvez utiliser davantage de paramètres pour affiner davantage les résultats de requête :

  • --query 'value[?displayName=='My Workspace']pour répertorier uniquement les éléments avec un displayName .My Workspace
  • --query 'value[starts_with(?displayName='My')] pour répertorier uniquement les éléments dont displayName le début commence par My.
  • --query '{query}' pour répertorier uniquement les éléments qui correspondent au JMESPath {query}fourni. Consultez la documentation Azure CLI sur JMESPath concernant la syntaxe prise en charge pour {query}.
  • -o table pour produire un résultat de table.

Note

Consultez la section sur l’utilisation d’az-rest ou de la section sur l’utilisation de curl pour savoir comment exécuter des requêtes via le point de terminaison de l’API à partir d’un interpréteur de commandes.

En-têtes de requête

Header Valeur Obligatoire
Content-Type application/json Oui
Accept application/json Oui
Authorization Bearer <token> Oui

Format de la demande

Toutes les requêtes utilisent HTTP POST avec une charge utile JSON.

Structure de requête de base

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

Champs de requête

Terrain Type Obligatoire Descriptif
query ficelle Oui Requête GQL à exécuter

Format de la réponse

Toutes les réponses pour les requêtes réussies utilisent l’état HTTP 200 avec la charge utile JSON contenant l’état d’exécution et les résultats.

Structure de réponse

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

Objet Status

Chaque réponse inclut un objet d’état avec des informations d’exécution :

Terrain Type Descriptif
code ficelle code d’état à six caractères (000000 = réussite)
description ficelle Message d’état lisible par l’homme
diagnostics objet Enregistrements de diagnostic détaillés
cause objet Objet d’état de la cause sous-jacente facultative

Codes d’état

Les codes d’état suivent un modèle hiérarchique :

  • 00xxxx - Réussite complète
  • 01xxxx - Réussite avec des avertissements
  • 02xxxx - Réussite sans données
  • 03xxxx - Réussite avec des informations
  • 04xxxx et versions ultérieures : erreurs et conditions d’exception

Pour plus d’informations, consultez la référence des codes d’état GQL.

Enregistrements de diagnostic

Les enregistrements de diagnostic peuvent contenir d’autres paires clé-valeur qui détaillent davantage l’objet d’état. Les clés commençant par un trait de soulignement (_) sont spécifiques au graphique. La norme GQL prescrit toutes les autres clés.

Note

Les valeurs de l’enregistrement de diagnostic des clés spécifiques au graphique sont des valeurs GQL encodées au format JSON. Consultez types valeur et encodage.

Causes

Les objets d’état incluent un champ facultatif cause lorsqu’une cause sous-jacente est connue.

Autres objets d’état

Certains résultats peuvent signaler d’autres objets d’état sous forme de liste dans le champ (facultatif). additionalStatuses

Dans ce cas, l’objet d’état principal est toujours déterminé comme étant l’objet d’état le plus critique (tel qu’une condition d’exception) tel qu’il est prescrit par la norme GQL.

Types de résultats

Les résultats utilisent un modèle d’union discriminatoire avec le kind champ :

Résultats du tableau

Pour les requêtes qui retournent des données tabulaires :

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

Résultats omis

Pour les opérations qui ne retournent pas de données (par exemple, les mises à jour de catalogue et/ou de données) :

{
  "kind": "NOTHING"
}

Types de valeurs et encodage

L’API utilise un système de type enrichi pour représenter des valeurs GQL avec une sémantique précise. Le format JSON des valeurs GQL suit un modèle d’union discriminatoire.

Note

Le format JSON des résultats tabulaires réalise le modèle d’union discriminé en séparant gqlType et value en obtenant une représentation plus compacte. Consultez l’optimisation de la sérialisation des tables.

Structure des valeurs

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

Types primitifs

GQL Type Example Descriptif
BOOL {"gqlType": "BOOL", "value": true} Boolean JSON natif
STRING {"gqlType": "STRING", "value": "Hello"} Chaîne UTF-8

Types valeurs numériques

Types entiers

GQL Type Gamme Sérialisation JSON Example
INT64 -2⁶³ à 2⁶³-1 Nombre ou chaîne* {"gqlType": "INT64", "value": -9237}
UINT64 0 à 2⁶⁴-1 Nombre ou chaîne* {"gqlType": "UINT64", "value": 18467}

Les entiers volumineux en dehors de la plage sécurisée de JavaScript (-9 007 199 254 740 991 à 9 007 199 254 740 991) sont sérialisés sous forme de chaînes :

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

Types à virgule flottante

GQL Type Gamme Sérialisation JSON Example
FLOAT64 IEEE 754 binary64 Numéro ou chaîne JSON {"gqlType": "FLOAT64", "value": 3.14}

Les valeurs à virgule flottante prennent en charge les valeurs spéciales IEEE 754 :

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

Types temporels

Les types temporels pris en charge utilisent des formats de chaîne ISO 8601 :

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

Types de référence d’élément Graph

GQL Type Descriptif Example
NODE Informations de référence sur les nœuds graph {"gqlType": "NODE", "value": "node-123"}
EDGE Informations de référence sur l’arête du graphique {"gqlType": "EDGE", "value": "edge_abc#def"}

Types complexes

Les types complexes sont composés d’autres valeurs GQL.

Lists

Les listes contiennent des tableaux de valeurs nullables avec des types d’éléments cohérents :

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

Types de listes spéciales :

  • LIST<ANY> - Types mixtes (chaque élément inclut des informations de type complètes)
  • LIST<NULL> - Seules les valeurs Null autorisées
  • LIST<NOTHING> - Tableau toujours vide

Chemins

Les chemins d’accès sont encodés sous forme de listes de valeurs de référence d’élément de graphique.

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

Consultez l’optimisation de la sérialisation des tables.

Optimisation de la sérialisation des tables

Pour les résultats de la table, la sérialisation des valeurs est optimisée en fonction des informations de type de colonne :

  • Types connus : seule la valeur brute est sérialisée
  • Colonnes ANY - Objet de valeur complète avec un discriminateur de type
{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Gestion des erreurs

Erreurs de transport

Les erreurs de transport réseau et HTTP entraînent des codes d’état d’erreur HTTP standard (4xx, 5xx).

Erreurs d’application

Les erreurs au niveau de l’application retournent toujours HTTP 200 avec des informations d’erreur dans l’objet d’état :

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

Vérification de l’état

Pour déterminer la réussite, vérifiez le code d’état :

  • Codes commençant par 00, 01, 02, 03 indiquer la réussite (avec des avertissements possibles)
  • Tous les autres codes indiquent des erreurs

Exemple complet avec az rest

Exécutez une requête à l’aide de la az rest commande pour éviter d’avoir à obtenir manuellement des jetons du porteur, comme suit :

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

Exemple complet avec curl

L’exemple de cette section utilise l’outil curl pour effectuer des requêtes HTTPS à partir de l’interpréteur de commandes.

Nous partons du principe que vous disposez d’un jeton d’accès valide stocké dans une variable shell, comme suit :

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

Conseil / Astuce

Consultez la section sur l’authentification pour savoir comment obtenir un jeton de porteur valide.

Exécutez une requête comme suit :

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

Meilleures pratiques

Suivez ces bonnes pratiques lors de l’utilisation de l’API de requête GQL.

Gestion des erreurs

  • Vérifiez toujours les codes d’état : ne supposez pas la réussite en fonction de HTTP 200.
  • Détails de l’erreur d’analyse : utilisez des diagnostics et provoquez des chaînes pour le débogage.

Security

  • Utilisez HTTPS : n’envoyez jamais de jetons d’authentification sur des connexions non chiffrées.
  • Faire pivoter des jetons - Implémenter une gestion appropriée de l’actualisation et de l’expiration des jetons.
  • Valider les entrées - Nettoyer et échapper correctement les paramètres de requête fournis par l’utilisateur injectés dans la requête.

Représentation de valeur

  • Gérer les valeurs entières volumineuses : les entiers sont encodés en tant que chaînes s’ils ne peuvent pas être représentés en tant que nombres JSON en mode natif.
  • Gérer des valeurs à virgule flottante spéciale : les valeurs à virgule flottante retournées par les requêtes peuvent être Infinity, -Infinityou NaN (pas un nombre).
  • Gérer les valeurs Null : JSON Null représente GQL Null.

Contenu connexe

  • Last updated on