plug-in gql_request

Le gql_request plug-in exécute une requête GQL (ISO Graph Query Language) sur un graphique dans Microsoft Fabric et retourne les résultats sous forme de table. Traitez la table retournée avec des opérateurs KQL (Kusto Query Language) standard. Appelez le plug-in avec l’opérateur evaluate.

Le plug-in utilise l’API de requête GQL Microsoft Fabric. Vous pouvez éventuellement déclarer le schéma de sortie attendu. Il évite une requête GQL supplémentaire lors de la découverte de schémas.

Note

Ce plug-in utilise le langage de requête Graph (GQL) pour interroger des graphiques Fabric, et non GraphQL, le langage de requête d’API.

Note

Le gql_request plug-in est en préversion.

Prerequisites

  • Graphique Microsoft Fabric qui contient des données. Pour créer et charger un exemple de graphique, consultez le guide de démarrage rapide Graph.
  • Autorisation d’interroger le graphique dans son espace de travail Fabric.
  • La stratégie de légende de cluster doit autoriser Fabric légendes de requête GQL Graph à api.fabric.microsoft.com. Pour modifier cette stratégie, vous avez besoin AllDatabasesAdmin ou Ops autorisations.

Syntax

evaluate gql_request ( ConnectionString,GqlQuery) [:OutputSchema]

En savoir plus sur les conventions de syntaxe dans les conventions de syntaxe pour la documentation de référence.

Paramètres

Nom Type Required Description
ConnectionString string Yes URL du modèle graphique Fabric suivie de ;Impersonate. Pour le format pris en charge, consultez chaîne de connexion.
GqlQuery string Yes Requête GQL à exécuter sur le graphique.
OutputSchema - - Noms et types des colonnes de sortie attendues. Utilisez la syntaxe (ColumnName:ColumnType [, ...]).

Note

La spécification de OutputSchema est recommandée en particulier lorsque la requête GQL peut retourner aucune ligne. Elle permet à Kusto de déterminer les colonnes et types de sortie du plug-in sans exécuter la requête pendant la découverte du schéma. Le plug-in retourne une erreur si le schéma retourné n’est pas compatible avec le schéma déclaré.

Chaîne de connexion

Spécifiez l’URL du modèle graphique Fabric suivie de la ;Impersonate directive d’authentification :

https://api.fabric.microsoft.com/v1/workspaces/<WorkspaceId>/GraphModels/<GraphModelId>;Impersonate

WorkspaceId et GraphModelId doit être des GUID valides.

Authentification et autorisation

Le plug-in utilise Microsoft Entra l’authentification au nom de l’utilisateur. Le moteur obtient un jeton pour l’utilisateur demandeur et interroge le graphique dans le contexte de sécurité de cet utilisateur. L’utilisateur doit disposer d’autorisations sur le graphique.

Utilisez ;Impersonate comme directive d’authentification. L’identité managée, le principal de service et l’authentification par clé d’application ne sont pas pris en charge.

Important

Utilisez un littéral de chaîne obfusqué pour toute chaîne qui contient des informations confidentielles. Les valeurs obfuscatées n’apparaissent pas dans le suivi Kusto.

Configurer la stratégie de légende

Le plug-in effectue un appel externe à Microsoft Fabric. Étant donné que la stratégie de légende par défaut bloque Fabric légendes de requête GQL Graph, un administrateur de cluster doit autoriser explicitement le point de terminaison Fabric.

La commande suivante fusionne une règle de requête GQL graph restrictive Fabric dans la stratégie de légende de cluster existante :

.alter-merge cluster policy callout @'[{
    "CalloutType": "gql", 
    "CalloutUriRegex": "api\\.fabric\\.microsoft\\.com/.*", 
    "CanCall": true
}]'

Vérifiez la stratégie :

.show cluster policy callout

Returns

Le plug-in retourne le résultat de la requête GQL sous la forme d’une table KQL. Si vous spécifiez OutputSchema, les colonnes retournées doivent être compatibles avec le schéma déclaré. Pour obtenir des résultats prévisibles, projetez les propriétés dont vous avez besoin dans la requête GQL plutôt que de retourner des nœuds entiers, des arêtes ou des chemins d’accès.

Examples

Retourner des lignes à partir d’un graphique

Cet exemple suppose que le graphique contient des Person nœuds avec et lastName des firstName propriétés. Il retourne jusqu’à 100 noms.

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/graphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)
    RETURN p.firstName AS firstName, p.lastName AS lastName
    LIMIT 100')
  : (firstName:string, lastName:string)

Traiter les résultats GQL avec Kusto

L’exemple suivant compte Person les nœuds avec une LIVES_IN relation avec chacun d’eux City, puis utilise KQL pour afficher les villes avec plus de 10 personnes, classées par nombre. Il part du principe que le graphique contient Person et City les nœuds connectés par LIVES_IN des relations.

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/GraphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)-[:LIVES_IN]->(c:City)
    RETURN c.name AS city, count(DISTINCT p) AS PersonCount')
  : (city:string, PersonCount:long)
| where PersonCount > 10
| order by PersonCount desc

Cela compte des personnes distinctes par nom de ville ; les villes partageant un nom sont regroupées.

Tip

Filtrez, projetez et limitez les données dans GQL lorsque cela est possible pour réduire la quantité de données retournées à Kusto.

Troubleshooting

Le plug-in distingue les échecs de transport des erreurs d’application GQL. Une erreur d’application GQL peut arriver dans une réponse HTTP 200. Le plug-in évalue l’état de la réponse, inclut les codes d’état disponibles, les descriptions et les causes imbriquées, et retourne l’échec en tant qu’erreur de requête.

Le tableau ci-dessous répertorie les erreurs courantes retournées par le plug-in et leurs causes et résolutions possibles.

Error Cause et résolution
Chaîne de connexion non valide Vérifiez que le chaîne de connexion suit le format pris en charge, les ID de modèle d’espace de travail et de graphique sont des GUID valides, et la chaîne se termine par ;Impersonate. N’incluez /executeQuery pas, les paramètres de requête ou un fragment dans l’URL. Le plug-in construit le point de terminaison d’API en interne.
Incompatibilité du schéma de sortie Vérifiez que les noms de colonnes déclarés et les types KQL sont compatibles avec les colonnes et types de résultats GQL.
Type de résultat GQL non pris en charge Project propriétés scalaires individuelles dans la requête GQL. Pour les valeurs complexes, envisagez d’utiliser GQL TO_JSON_STRING pour retourner une représentation sous forme de chaîne.
La légende n’est pas autorisée Configurez la stratégie de légende de cluster pour autoriser Fabric appels de requête GQL Graph à api.fabric.microsoft.com.
Erreur d’authentification ou d’autorisation Vérifiez que l’identité de l’appelant peut accéder à l’espace de travail et au graphique.
Erreur de requête HTTP Vérifiez Microsoft Fabric disponibilité du service, l’accessibilité des points de terminaison et les réponses de limitation.
Erreur de requête GQL Passez en revue les détails de l’erreur de requête, notamment la description de l’état GQL, les diagnostics et la cause imbriquée lorsqu’elles sont disponibles.

Contenu connexe

  • Dernière mise à jour :