Condividi tramite

Informazioni di riferimento sulle API query GQL

Annotazioni

Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene messa a disposizione senza contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Eseguire query GQL sui grafici delle proprietà in Microsoft Fabric usando un'API HTTP RESTful. Questo riferimento descrive il contratto HTTP: formati di richiesta e risposta, autenticazione, codifica dei risultati JSON e gestione degli errori.

Importante

Questo articolo utilizza esclusivamente il dataset di esempio dei grafi dei social network.

Informazioni generali

L'API query GQL è un singolo endpoint (RPC su HTTP) che accetta query GQL come payload JSON e restituisce risultati strutturati e tipizzato. L'API è senza stato, gestisce l'autenticazione e fornisce una segnalazione degli errori completa.

Funzionalità principali

  • Singolo endpoint : tutte le operazioni usano HTTP POST per un URL.
  • Basato su JSON : i payload di richiesta e risposta usano JSON con codifica avanzata di valori GQL tipizzati.
  • Senza stato: nessuno stato della sessione richiesto tra le richieste.
  • Type safe : tipizzazione compatibile con GQL con unioni discriminate per la rappresentazione di valori.

Prerequisiti

Authentication

L'API query GQL richiede l'autenticazione tramite token di connessione.

Includere il token di accesso nell'intestazione autorizzazione di ogni richiesta:

Authorization: Bearer <your-access-token>

In generale, è possibile ottenere token di connessione usando Microsoft Authentication Library (MSAL) o altri flussi di autenticazione compatibili con Microsoft Entra.

I token di connessione vengono comunemente ottenuti tramite due percorsi principali:

Accesso delegato dall'utente

È possibile ottenere token di connessione per le chiamate al servizio delegato dall'utente dalla riga di comando tramite lo strumento dell'interfaccia della riga di comando di az ,

Ottenere un token di connessione per le chiamate delegate dall'utente dalla riga di comando tramite:

  • Eseguire az login
  • Allora az account get-access-token --resource https://api.fabric.microsoft.com

In questo modo viene usato lo strumento dell'interfaccia della riga di az.

Quando si usa per l'esecuzione az rest di richieste, i token di connessione vengono ottenuti automaticamente.

Accesso alle applicazioni

È possibile ottenere token di connessione per le applicazioni registrate in Microsoft Entra. Per altri dettagli, vedere la guida introduttiva all'API infrastruttura .

Punto finale API

L'API usa un singolo endpoint che accetta tutte le operazioni di query:

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

Per ottenere per l'area {workspaceId} di lavoro, è possibile elencare tutte le aree di lavoro disponibili usando az rest:

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

Per ottenere {graphId}, è possibile elencare tutti i grafici disponibili in un'area di lavoro usando az rest:

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

È possibile usare più parametri per restringere ulteriormente i risultati delle query:

  • --query 'value[?displayName=='My Workspace'] per elencare solo gli elementi con un displayName di My Workspace.
  • --query 'value[starts_with(?displayName='My')] per elencare solo gli elementi che displayName iniziano con My.
  • --query '{query}' per elencare solo gli elementi che corrispondono a JMESPath {query}specificati. Vedere la documentazione dell'interfaccia della riga di comando di Azure in JMESPath relativa alla sintassi supportata per {query}.
  • -o table per produrre un risultato di tabella.

Annotazioni

Vedere la sezione sull'uso di az-rest o la sezione sull'uso di curl per l'esecuzione di query tramite l'endpoint API da una shell della riga di comando.

Header di richiesta

Header Value Obbligatorio
Content-Type application/json Yes
Accept application/json Yes
Authorization Bearer <token> Yes

Formato della richiesta

Tutte le richieste usano HTTP POST con un payload JSON.

Struttura di richiesta di base

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

Campi della richiesta

Campo TIPO Obbligatorio Description
query corda Yes Query GQL da eseguire

Formato della risposta

Tutte le risposte per le richieste riuscite usano lo stato HTTP 200 con payload JSON contenente lo stato e i risultati dell'esecuzione.

Struttura della risposta

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

Oggetto Status

Ogni risposta include un oggetto stato con informazioni sull'esecuzione:

Campo TIPO Description
code corda codice di stato di sei caratteri (000000 = esito positivo)
description corda Messaggio di stato leggibile
diagnostics oggetto Record di diagnostica dettagliati
cause oggetto Oggetto stato della causa sottostante facoltativo

Codici di stato

I codici di stato seguono un modello gerarchico:

  • 00xxxx - Completamento dell'operazione
  • 01xxxx - Operazione riuscita con avvisi
  • 02xxxx - Operazione riuscita senza dati
  • 03xxxx - Operazione riuscita con informazioni
  • 04xxxx e versioni successive - Errori e condizioni di eccezione

Per altre informazioni, vedere le informazioni di riferimento sui codici di stato GQL.

Record di diagnostica

I record di diagnostica possono contenere altre coppie chiave-valore che descrivono ulteriormente l'oggetto stato. Le chiavi che iniziano con un carattere di sottolineatura (_) sono specifiche del grafico per Microsoft Fabric. Lo standard GQL prevede tutte le altre chiavi.

Annotazioni

I valori nel record di diagnostica delle chiavi specifiche del grafico in Microsoft Fabric sono valori GQL con codifica JSON. Vedere Tipi di valore e codifica.

Cause

Gli oggetti stato includono un campo facoltativo cause quando è nota una causa sottostante.

Altri oggetti di stato

Alcuni risultati possono segnalare altri oggetti di stato come elenco nel campo (facoltativo). additionalStatuses

In tal caso, l'oggetto stato primario viene sempre determinato come l'oggetto di stato più critico ,ad esempio una condizione di eccezione, come previsto dallo standard GQL.

Tipi di risultati

I risultati usano un modello di unione discriminante con il kind campo :

Risultati tabella

Per le query che restituiscono dati tabulari:

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

Risultati omessi

Per le operazioni che non restituiscono dati (ad esempio, catalog e/o aggiornamenti dei dati):

{
  "kind": "NOTHING"
}

Tipi di valore e codifica

L'API usa un sistema di tipi avanzato per rappresentare i valori GQL con semantica precisa. Il formato JSON dei valori GQL segue un modello di unione discriminante.

Annotazioni

Il formato JSON dei risultati tabulari realizza il modello di unione discriminante separando gqlType e value per ottenere una rappresentazione più compatta. Vedere Ottimizzazione della serializzazione delle tabelle.

Struttura del valore

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

Tipi primitivi

Tipo GQL Example Description
BOOL {"gqlType": "BOOL", "value": true} Boolean JSON nativo
STRING {"gqlType": "STRING", "value": "Hello"} Stringa UTF-8

Tipi numerici

Tipi integer

Tipo GQL Intervallo Serializzazione JSON Example
INT64 -2⁶⁶⁶⁶-1 Numero o stringa* {"gqlType": "INT64", "value": -9237}
UINT64 Da 0 a 2⁶⁴-1 Numero o stringa* {"gqlType": "UINT64", "value": 18467}

I numeri interi di grandi dimensioni non compresi nell'intervallo sicuro di JavaScript (da 9.007.199.254.740.991 a 9.007.199.254.740.991) vengono serializzati come stringhe:

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

Tipi a virgola mobile

Tipo GQL Intervallo Serializzazione JSON Example
FLOAT64 IEEE 754 binary64 Numero o stringa JSON {"gqlType": "FLOAT64", "value": 3.14}

I valori a virgola mobile supportano valori speciali IEEE 754:

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

Tipi temporali

I tipi temporali supportati usano formati stringa ISO 8601:

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

Tipi di riferimento degli elementi graph

Tipo GQL Description Example
NODE Informazioni di riferimento sul nodo graph {"gqlType": "NODE", "value": "node-123"}
EDGE Riferimento ai bordi del grafo {"gqlType": "EDGE", "value": "edge_abc#def"}

Tipi complessi

I tipi complessi sono costituiti da altri valori GQL.

Lists

Gli elenchi contengono matrici di valori nullable con tipi di elemento coerenti:

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

Tipi di elenco speciali:

  • LIST<ANY> - Tipi misti (ogni elemento include informazioni complete sul tipo)
  • LIST<NULL> - Sono consentiti solo valori Null
  • LIST<NOTHING> - Matrice sempre vuota

Paths

I percorsi vengono codificati come elenchi di valori di riferimento degli elementi del grafo.

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

Vedere Ottimizzazione della serializzazione delle tabelle.

Ottimizzazione della serializzazione delle tabelle

Per i risultati della tabella, la serializzazione dei valori è ottimizzata in base alle informazioni sul tipo di colonna:

  • Tipi noti : viene serializzato solo il valore non elaborato
  • Colonne ANY - Oggetto a valore pieno con discriminatore di tipo
{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Gestione degli errori

Errori di trasporto

Gli errori di trasporto HTTP e di rete generano codici di stato di errore HTTP standard (4xx, 5xx).

Errori dell'applicazione

Gli errori a livello di applicazione restituiscono sempre HTTP 200 con informazioni sull'errore nell'oggetto stato:

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

Controllo dello stato

Per determinare l'esito positivo, controllare il codice di stato:

  • Codici che iniziano con 00, 0102, , 03 indicano l'esito positivo (con possibili avvisi)
  • Tutti gli altri codici indicano errori

Esempio completo con az rest

Eseguire una query usando il az rest comando per evitare di dover ottenere manualmente i token di connessione, come illustrato di seguito:

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

Esempio completo con curl

L'esempio in questa sezione usa lo strumento per l'esecuzione curl di richieste HTTPS dalla shell.

Si supponga di avere un token di accesso valido archiviato in una variabile della shell, come illustrato di seguito:

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

Suggerimento

Vedere la sezione sull'autenticazione per informazioni su come ottenere un token di connessione valido.

Eseguire una query come segue:

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

Procedure consigliate

Seguire queste procedure consigliate quando si usa l'API query GQL.

Gestione degli errori

  • Controllare sempre i codici di stato : non presupporre l'esito positivo in base a HTTP 200.
  • Analizzare i dettagli degli errori : usare la diagnostica e causare catene per il debug.

Security

  • Usare HTTPS : non inviare mai token di autenticazione su connessioni non crittografate.
  • Ruotare i token : implementare la gestione corretta dell'aggiornamento e della scadenza dei token.
  • Convalidare gli input : purificare ed eseguire correttamente l'escape di tutti i parametri di query forniti dall'utente inseriti nella query.

Rappresentazione del valore

  • Gestire valori integer di grandi dimensioni : i numeri interi vengono codificati come stringhe se non possono essere rappresentati come numeri JSON in modo nativo.
  • Gestire valori speciali a virgola mobile: i valori a virgola mobile restituiti dalle query possono essere Infinityvalori , -Infinityo NaN (non un numero).
  • Gestire i valori Null : JSON null rappresenta GQL null.

Contenuti correlati

  • Last updated on