Informazioni di riferimento sulle API query GQL

Eseguire query GQL sui grafici delle proprietà nel grafico 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.

Informazioni generali

L'API GQL Query espone un endpoint REST che accetta query GQL come payload JSON e restituisce risultati strutturati e tipizzati. Supporta il continuation polling per query che non si completano durante la richiesta iniziale.

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.
• Continuation polling - Le query di lunga durata possono continuare su più richieste HTTP.
• Type safe : tipizzazione compatibile con GQL con unioni discriminate per la rappresentazione di valori.

Prerequisiti

• È necessario un grafo che contiene dati, inclusi nodi e archi (relazioni). Vedere la guida introduttiva al grafico per creare e caricare un grafico di esempio.
• È necessario avere familiarità con i grafici delle proprietà e una conoscenza di base di GQL, inclusa la struttura dei risultati e dei risultati dell'esecuzione.
• È necessario installare e configurare lo strumento interfaccia della riga di comando di Azureaz per accedere all'organizzazione. Gli esempi della riga di comando in questo articolo presuppongono l'uso di una shell della riga di comando compatibile con POSIX, ad esempio bash.

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 Libreria di Autenticazione Microsoft (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 delegate dall'utente dalla riga di comando tramite lo strumento interfaccia della riga di comando di Azureaz.

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

Viene usato lo strumento interfaccia della riga di comando di Azureaz.

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

L'API Query è in beta e non è raccomandata per l'uso in produzione. Imposta il parametro di query richiesto beta a true. Il parametro più vecchio preview=true rimane supportato per la retrocompatibilità, ma viene utilizzato beta=true per nuove integrazioni.

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 {graphModelId}, è 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"

Puoi usare le opzioni di output di interfaccia della riga di comando di Azure per filtrare o formattare le risposte di queste richieste di lista. Queste opzioni si eseguono nel client interfaccia della riga di comando di Azure; non sono parametri API di Query:

• --query "value[?displayName=='My Workspace']"elenca solo gli elementi con un displayName .My Workspace
• --query "value[?starts_with(displayName, 'My')]" elenca solo gli elementi che displayName iniziano con My.
• --query "{query}" elenca solo gli elementi che corrispondono al JMESPath {query}fornito. Consulta i risultati dei comandi interfaccia della riga di comando di Azure per la sintassi supportata.
• -o table per produrre un risultato di tabella.

Parametri di query

Header di richiesta

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

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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Oggetto Status

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

Codici di stato

Il principale status.code utilizza queste categorie pubbliche di API:

• 00000 - Completamento con successo con almeno una riga.
• 00001 - Completamento con successo con un risultato omesso. Riservato per il supporto futuro DDL e DML.
• 01000 - Stato di avviso o informativo.
• 02000 - Attualmente non sono disponibili righe da una query che produce righe.
• 42000 - Sintassi, regola di accesso o altro errore di query correttibile dall'utente.
• 50000 - Errore di sistema o non classificato.

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. Lo standard GQL prevede tutte le altre chiavi.

Cause

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

Altri oggetti di stato

Alcuni risultati possono riportare altri oggetti di stato come elenco nel campo opzionale additionalStatuses .

Lo stato primario è la condizione più critica registrata. Ogni ulteriore stato e causa annidata ha il proprio codice API pubblico e la diagnostica canonica GQLSTATUS.

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

Query con esecuzione prolungata

Se una query non si completa durante la richiesta HTTP corrente, l'API restituisce HTTP 200 con codice 02000di stato pubblico, una tabella vuota e un nextPage token:

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

Interroga per il completamento inviando lo stesso corpo della richiesta e aggiungendo il token all'URL:

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

Trattalo nextPage come un valore opaco. Codificalo percentualmente una volta esattamente secondo la RFC 3986 prima di usarlo come continuationToken valore del parametro di query. Non decodificare, ispezionare o modificare il token.

Continua finché la risposta non contiene nextPagepiù . L'esecuzione della query può continuare fino a 20 minuti dalla richiesta iniziale. Se supera quella durata totale, l'API restituisce HTTP 408 con codice QueryTimeoutdi errore .

Risultati troncati

Graph tronca una risposta alla query quando la sua rappresentazione binaria interna supera i 64 MB. L'API restituisce le righe che si adattano e aggiunge uno stato a additionalStatuses. Lo status aggiuntivo utilizza codice 01000 pubblico e preserva lo status 01M11 canonico GQL in _graphaneGqlStatus.

La troncatura non produce un nextPage gettone per le righe omesse. Restringi la query con filtri, proiezioni specifiche o LIMIT, e poi rieseguila.

Risultati omessi

Lo schema di risposta può rappresentare un'operazione la cui istruzione non produce mai righe, indipendentemente dai dati o dall'esito della valutazione. Questo risultato utilizza il codice 00001di stato :

{
  "kind": "NOTHING"
}

Questo risultato omesso differisce da una tabella senza righe. Una tabella vuota è il risultato della valutazione di una query che produce righe e che attualmente non ha righe da restituire.

Graph riserva questo codice di forma e stato dei risultati per il supporto futuro per il linguaggio di definizione dati (DDL) e il linguaggio di manipolazione dati (DML). Le istruzioni di query attuali restituiscono sempre i risultati delle tabelle.

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.

Struttura del valore

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

Tipi primitivi

Tipi numerici

Tipi integer

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

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:

Tipi di riferimento degli elementi graph

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

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

Gestione degli errori

Errori di trasporto

Lo stato HTTP e lo stato GQL descrivono diversi livelli della risposta:

Errori dell'applicazione

Un errore a livello di applicazione può restituire HTTP 200 con le informazioni sull'errore nell'oggetto di stato. Ad esempio, la divisione per zero utilizza il codice 42000 API pubblico e preserva lo stato 22012 canonico GQL nel record diagnostico:

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

Controllo dello stato

Per determinare l'esito generale, controlla il pubblico status.code. Da usare _graphaneGqlStatus quando la tua applicazione deve distinguere una specifica condizione del motore di query, come il sovraplessamento numerico (22003) dalla divisione per zero (22012).

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

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"

Eseguire una query come segue:

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

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.
• Valida gli input - Valida e sfuggi correttamente a qualsiasi valore fornito dall'utente che la tua applicazione inserisce nel testo della 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 in virgola mobile - L'API serializza infinito positivo, infinito negativo, non-numero-numero e -zero come "Inf", "-Inf", "NaN", e "-0".
• Gestire i valori Null : JSON null rappresenta GQL null.

Contenuti correlati

• modelli di dati del grafo
• Guida al linguaggio GQL
• Valori e tipi valore GQL
• Informazioni di riferimento per i codici di stato GQL