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

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 GQL Query expose un point de terminaison REST qui accepte les requêtes GQL comme des charges utiles JSON et retourne des résultats structurés et typés. Il supporte le polling de continuation pour les requêtes qui ne se terminent pas lors de la requête initiale.

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.
Interrogation de continuation - Les requêtes de longue durée peuvent se poursuivre sur plusieurs requêtes HTTP.
Type sécurisé : frappe forte et compatible GQL avec des unions discriminatoires pour la représentation de valeur.

Prerequisites

Vous avez besoin d’un graphique qui contient des données, y compris des nœuds et des arêtes (relations). Consultez le guide de démarrage rapide du graphique pour créer et charger un exemple de graphique.
Vous devez être familiarisé avec les graphiques de propriétés et une compréhension de base de GQL, y compris la structure des résultats et des résultats d’exécution.
Vous devez installer et configurer l’outil Azure CLIaz pour vous connecter à votre organisation. Les exemples de ligne de commande de cet article supposent l’utilisation d’un interpréteur de commandes compatible POSIX, tel que bash.

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?beta=true

L’API Query est en version bêta et n’est pas recommandée pour une utilisation en production. Définissez le paramètre de requête requis beta à true. L’ancien preview=true paramètre reste pris en charge pour la rétrocompatibilité, mais il est utilisé beta=true pour de nouvelles intégrations.

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 {graphModelId}, 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 les options de sortie Azure CLI pour filtrer ou formater les réponses issues de ces requêtes de liste. Ces options s'exécutent dans le client Azure CLI ; ce ne sont pas des paramètres API de requête :

--query "value[?displayName=='My Workspace']"Liste uniquement les éléments ayant un displayName .My Workspace
--query "value[?starts_with(displayName, 'My')]" Liste uniquement les éléments commençant displayName par My.
--query "{query}" ne liste que les éléments correspondant au JMESPath {query}fourni. Consultez les résultats de la commande Azure CLI pour la syntaxe prise en charge.
-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.

Paramètres de la requête

Paramètre	Type	Obligatoire	Descriptif
`beta`	booléen	Oui	Réglez pour `true` utiliser l’API de requête bêta.
`continuationToken`	ficelle	Non	Jeton de `result.nextPage` la requête en cours d’exécution. Soumettez le même texte de requête lorsque vous utilisez le jeton.

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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "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 de l’API publique de cinq caractères.
`description`	ficelle	Description de statut lisible par un humain.
`diagnostics`	objet	Enregistrement diagnostic détaillé, incluant le statut canonique du moteur de requête GQL lorsque disponible.
`cause`	objet	Objet d’état de cause sous-jacente optionnel.

Codes d’état

Les utilisations principales status.code de ces catégories d’API publiques :

00000 - Réussite avec au moins une ligne.
00001 - Réussite avec un résultat omis. Réservé pour un futur support DDL et DML.
01000 - Avertissement ou état d’information.
02000 - Aucune ligne n’est actuellement disponible depuis une requête de production de lignes.
42000 - Erreur de syntaxe, de règle d’accès ou d’autre erreur de requête corrigable par l’utilisateur.
50000 - Erreur système ou non classifiée.

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

Le _graphaneGqlStatus diagnostic contient le GQLSTATUS canonique de cinq caractères rapporté par le moteur de requête. Chaque membre de diagnostic préfixé par sous-trait contient soit null une valeur GQL encodée en JSON. Par exemple, _graphaneGqlStatus utilise STRING, tandis que les diagnostics de classification d’erreurs utilisent BOOL. 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 rapporter d’autres objets d’état sous forme de liste dans le champ optionnel additionalStatuses .

Le statut principal est l’état le plus critique enregistré. Chaque statut supplémentaire et cause imbriquée possède son propre code API public et un diagnostic canonique GQLSTATUS.

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

Requêtes de longue durée

Si une requête ne se termine pas pendant la requête HTTP en cours, l’API retourne HTTP 200 avec un code 02000d’état public, une table vide et un nextPage jeton :

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

Interrogez pour compléter en envoyant le même corps de requête et en ajoutant le jeton à l’URL :

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

Considérez nextPage comme une valeur opaque. Encodez-le en percentual exactement une fois selon la RFC 3986 avant de l’utiliser comme valeur du continuationToken paramètre de requête. Ne décodez pas, n’inspectez pas ou ne modifiez pas le jeton.

Continuez jusqu’à ce que la réponse ne contienne nextPageplus . L’exécution des requêtes peut se poursuivre jusqu’à 20 minutes à partir de la requête initiale. Si elle dépasse cette durée totale, l’API renvoie HTTP 408 avec un code QueryTimeoutd’erreur .

Résultats tronqués

Le graphe tronque une réponse à la requête lorsque sa représentation binaire interne dépasse 64 Mo. L’API retourne les lignes qui correspondent et ajoute un statut à additionalStatuses. Le statut additionnel utilise du code 01000 public et préserve le GQLSTATUS 01M11 canonique dans _graphaneGqlStatus.

La troncature ne produit pas de nextPage jeton pour les lignes omises. Affinez la requête avec des filtres, des projections spécifiques, ou LIMIT, puis relancez-la.

Résultats omis

Le schéma de réponse peut représenter une opération dont l’instruction ne produit jamais de lignes, indépendamment des données ou du résultat de l’évaluation. Ce résultat utilise le code 00001de statut :

{
  "kind": "NOTHING"
}

Ce résultat omis diffère d’un tableau sans lignes. Une table vide est le résultat de l’évaluation d’une requête générant des lignes qui n’a actuellement aucune ligne à retourner.

Graph réserve cette forme de résultat et ce code de statut pour le support futur des instructions du langage de définition de données (DDL) et du langage de manipulation de données (DML). Les instructions de requête actuelles renvoient toujours les résultats des tableaux.

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

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

Gestion des erreurs

Erreurs de transport

L’état HTTP et le statut GQL décrivent différentes couches de la réponse :

État HTTP	Meaning
200	L’API a traité la demande. Inspectez `status.code` car le résultat peut représenter un succès, pas de lignes, une requête encore en cours ou une erreur de requête corrigable par l’utilisateur.
408	L’exécution de la requête dépassait le délai total de 20 minutes. Le code d’erreur est `QueryTimeout`.
429	La limite de débit de service a été dépassée. Attendez la durée dans l’en-tête `Retry-After` avant de réessayer.
499	L’appelant a annulé la demande. Le code d’erreur est `ClientCancelled`.
Autres 4xx ou 5xx	La requête ou le service a échoué avant de renvoyer un résultat d’exécution GQL. Inspectez la réponse à l’erreur HTTP.

Erreurs d’application

Une erreur au niveau de l’application peut retourner HTTP 200 avec l’information d’erreur dans l’objet d’état. Par exemple, la division par zéro utilise le code 42000 API public et préserve le statut 22012 canonique GQL dans l’enregistrement de diagnostic :

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

Vérification de l’état

Pour déterminer le résultat global, vérifiez le public status.code. Utilisez _graphaneGqlStatus lorsque votre application doit distinguer une condition spécifique du moteur de requête, comme le débordement numérique (22003) à partir de la division par zéro (22012).

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

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

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 – Valider et éliminer correctement toutes les valeurs fournies par l’utilisateur que votre application insère dans le texte de 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 spéciales en virgule flottante - L’API sérialise l’infini positif, l’infini négatif, le non-nombre et le nœud négatif comme "Inf", "-Inf", "NaN", et "-0".
Gérer les valeurs Null : JSON Null représente GQL Null.

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-09-29

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

Aperçu

Fonctionnalités clés

Prerequisites

Authentication

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

Accès aux applications

Point de terminaison d’API

Paramètres de la requête

En-têtes de requête

Format de la demande

Structure de requête de base

Champs de requête

Format de la réponse

Structure de réponse

Objet Status

Codes d’état

Enregistrements de diagnostic

Causes

Autres objets d’état

Types de résultats

Résultats du tableau

Requêtes de longue durée

Résultats tronqués

Résultats omis

Types de valeurs et encodage

Structure des valeurs

Types primitifs

Types valeurs numériques

Types entiers

Types à virgule flottante

Types temporels

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

Types complexes

Lists

Chemins

Optimisation de la sérialisation des tables

Gestion des erreurs

Erreurs de transport

Erreurs d’application

Vérification de l’état

Exemple complet avec az rest

Exemple complet avec curl

Meilleures pratiques

Gestion des erreurs

Security

Représentation de valeur

Contenu connexe

Commentaires

Ressources supplémentaires