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.

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

• 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?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.

En-têtes de requête

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

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 :

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.

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.

Structure des valeurs

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

Types primitifs

Types valeurs numériques

Types entiers

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

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 :

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

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"

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

• Modèles de données de graphe
• Guide de langue GQL
• Valeurs et types de valeurs GQL
• Informations de référence sur les codes d’état GQL