plug-in gql_request

Il gql_request plug-in esegue una query GQL (ISO Graph Query Language) su un grafico in Microsoft Fabric e restituisce i risultati come tabella. Elaborare la tabella restituita con operatori KQL (Kusto Query Language) standard. Richiamare il plug-in con l'operatore evaluate.

Il plug-in usa l'API query GQL Microsoft Fabric. Facoltativamente, è possibile dichiarare lo schema di output previsto. In questo modo si evita una query GQL aggiuntiva durante l'individuazione dello schema.

Note

Questo plug-in usa Graph Query Language (GQL) per eseguire query Fabric grafici, non GraphQL, il linguaggio di query API.

Note

Il gql_request plug-in è in anteprima.

Prerequisites

  • Grafico Microsoft Fabric che contiene dati. Per creare e caricare un grafico di esempio, vedere Avvio rapido su Graph.
  • Autorizzazione per eseguire query sul grafico nell'area di lavoro Fabric.
  • I criteri di callout del cluster devono consentire Fabric callout della richiesta GQL Graph a api.fabric.microsoft.com. Per modificare questo criterio, sono necessarie AllDatabasesAdmin o Ops autorizzazioni.

Syntax

evaluate gql_request ( ConnectionString,GqlQuery) [:OutputSchema]

Altre informazioni sulle convenzioni di sintassi sono disponibili nella documentazione di riferimento sulle convenzioni della sintassi.

Parameters

Name Type Required Description
Stringa di connessione string Yes URL del modello a grafo Fabric seguito da ;Impersonate. Per il formato supportato, vedere Stringa di connessione.
GqlQuery string Yes Query GQL da eseguire sul grafico.
OutputSchema - - Nomi e tipi delle colonne di output previste. Usare la sintassi (ColumnName:ColumnType [, ...]).

Note

È consigliabile specificare OutputSchema in particolare quando la query GQL potrebbe non restituire righe. Consente a Kusto di determinare le colonne di output e i tipi del plug-in senza eseguire la query durante l'individuazione dello schema. Il plug-in restituisce un errore se lo schema restituito non è compatibile con lo schema dichiarato.

Stringa di connessione

Specificare l'URL del modello a grafo Fabric seguito dalla ;Impersonate direttiva di autenticazione:

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

WorkspaceId e GraphModelId devono essere GUID validi.

Autenticazione e autorizzazione

Il plug-in usa Microsoft Entra'autenticazione on-behalf-of. Il motore ottiene un token per l'utente richiedente ed esegue una query sul grafico nel contesto di sicurezza dell'utente. L'utente deve disporre delle autorizzazioni per il grafico.

Usare ;Impersonate come direttiva di autenticazione. L'identità gestita, l'entità servizio e l'autenticazione della chiave dell'applicazione non sono supportate.

Importante

Usare un valore letterale stringa offuscato per qualsiasi stringa contenente informazioni riservate. I valori offuscati non vengono visualizzati nella traccia Kusto.

Configurare i criteri di callout

Il plug-in effettua una chiamata esterna a Microsoft Fabric. Poiché i criteri di callout predefiniti bloccano Fabric callout delle richieste GQL Graph, un amministratore del cluster deve consentire in modo esplicito l'endpoint Fabric.

Il comando seguente unisce una regola di richiesta GQL Graph restrittiva Fabric nel criterio di callout del cluster esistente:

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

Verificare i criteri:

.show cluster policy callout

Returns

Il plug-in restituisce il risultato della query GQL come tabella KQL. Se si specifica OutputSchema, le colonne restituite devono essere compatibili con lo schema dichiarato. Per risultati prevedibili, proiettare le proprietà necessarie nella query GQL anziché restituire interi nodi, archi o percorsi.

Esempi

Restituire righe da un grafico

In questo esempio si presuppone che il grafico contenga Person nodi con firstName proprietà e lastName . Restituisce fino a 100 nomi.

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)

Elaborare i risultati GQL con Kusto

L'esempio seguente conta Person i nodi con una LIVES_IN relazione con ogni City, quindi usa KQL per mostrare le città con più di 10 persone, ordinate per conteggio. Si presuppone che il grafico contenga Person nodi e City connessi da LIVES_IN relazioni.

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

Questo conta persone distinte per nome città; le città che condividono un nome vengono raggruppate.

Tip

Filtrare, proiettare e limitare i dati in GQL quando possibile per ridurre la quantità di dati restituiti a Kusto.

Troubleshooting

Il plug-in distingue gli errori di trasporto dagli errori dell'applicazione GQL. Un errore dell'applicazione GQL può arrivare in una risposta HTTP 200. Il plug-in valuta lo stato della risposta, include codici di stato, descrizioni e cause annidate disponibili e restituisce l'errore come errore di query.

La tabella seguente elenca gli errori comuni restituiti dal plug-in e le possibili cause e risoluzioni.

Error Causa e risoluzione
Connection string non valido Verificare che il stringa di connessione segua il formato supportato, che gli ID modello dell'area di lavoro e del grafo siano GUID validi e che la stringa termini con ;Impersonate. Non includere /executeQuery , parametri di query o un frammento nell'URL. Il plug-in costruisce internamente l'endpoint API.
Mancata corrispondenza dello schema di output Verificare che i nomi di colonna dichiarati e i tipi KQL siano compatibili con le colonne e i tipi di risultato GQL.
Tipo di risultato GQL non supportato Project singole proprietà scalari nella query GQL. Per i valori complessi, è consigliabile usare GQL TO_JSON_STRING per restituire una rappresentazione di stringa.
Il callout non è consentito Configurare i criteri di callout del cluster per consentire Fabric chiamate di richiesta GQL Graph a api.fabric.microsoft.com.
Errore di autenticazione o autorizzazione Verificare che l'identità del chiamante possa accedere all'area di lavoro e al grafico.
Errore di richiesta HTTP Controllare Microsoft Fabric disponibilità del servizio, accessibilità degli endpoint e risposte di limitazione.
Errore di query GQL Esaminare i dettagli dell'errore di query, inclusa la descrizione dello stato GQL, la diagnostica e la causa annidata, se disponibile.

Contenuti correlati

  • Ultimo aggiornamento: