Query Execution - Execute Query

Servizio:: Dataflow

Versione API:: v1

Esegue una query su un flusso di dati e restituisce il risultato.
Esegue una query specificata su un flusso di dati e trasmette il risultato al chiamante. Supporta l'uso di documenti mashup personalizzati per scenari avanzati.

Questa API supporta operazioni con esecuzione prolungata (LRO).

Permissions

Il chiamante deve disporre delle autorizzazioni di esecuzione per il flusso di dati.

Ambiti delegati obbligatori

Dataflow.Execute.All o Item.Execute.All.

Limitazioni

Le query possono essere eseguite per un massimo di 90 secondi.

Identità supportate da Microsoft Entra

Questa API supporta le identità di Microsoft elencate in questa sezione.

Identità	Support
User	Yes
Principale del servizio e Identità gestite	Yes

Formati di risposta

Usare l'intestazione Accept per negoziare il tipo di supporto di risposta. Oggi, il formato di streaming Apache Arrow è l'unico formato di risposta disponibile; altri formati possono essere offerti in futuro.

Formato di streaming Apache Arrow

Tipo di supporto:application/vnd.apache.arrow.stream

Quando si invia questo tipo di supporto, è necessario il pq-arrow-version parametro media-type e seleziona la versione di codifica Arrow:

pq-arrow-version=1 — Codifica Apache Arrow originale. Compatibile con tutti i flussi di dati, inclusi quelli che si connettono tramite un gateway dati locale.
pq-arrow-version=2 - Codifica Apache Arrow più recente con prestazioni di streaming migliorate. Non supportato per i flussi di dati che si connettono tramite un gateway dati locale.

Esempio: Accept: application/vnd.apache.arrow.stream;pq-arrow-version=2

Se l'intestazione Accept viene omessa interamente (o */* viene inviata), per impostazione predefinita la risposta è application/vnd.apache.arrow.stream;pq-arrow-version=1.

Interfaccia

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/dataflows/{dataflowId}/executeQuery

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
dataflowId	path	True	string (uuid)	ID flusso di dati.
workspaceId	path	True	string (uuid)	L’ID dell’area di lavoro.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
Accept		string	Il tipo di media desiderato della risposta. Vedere la descrizione dell'operazione per l'elenco dei formati di risposta supportati. Attualmente è supportato solo `application/vnd.apache.arrow.stream` ; quando si invia questo tipo di supporto, il `pq-arrow-version` parametro è obbligatorio e deve essere `1` o `2` (ad esempio `application/vnd.apache.arrow.stream;pq-arrow-version=1`). Se l'intestazione viene omessa interamente, viene utilizzata l'impostazione predefinita `application/vnd.apache.arrow.stream;pq-arrow-version=1` .

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
queryName	True	string	Nome della query da eseguire dal flusso di dati (o dal documento mashup personalizzato, se specificato).
customMashupDocument		string	Documento mashup personalizzato facoltativo per eseguire l'override del mashup predefinito del flusso di dati.

Risposte

Nome	Tipo	Descrizione
200 OK	file	Il risultato della query è stato trasmesso correttamente. Il corpo della risposta viene codificato nel tipo di supporto negoziato tramite l'intestazione della richiesta (vedere la descrizione dell'operazione `Accept` per l'elenco dei formati di risposta supportati). Quando la risposta è nel formato di streaming Apache Arrow (`application/vnd.apache.arrow.stream`, l'unico formato attualmente disponibile), i risultati vengono trasmessi come Apache Arrow IPC. La versione di codifica Arrow restituita corrisponde al `pq-arrow-version` parametro inviato nell'intestazione della `Accept` richiesta (impostazione predefinita `1`). Vedere la documentazione di Arrow su come leggere il flusso in Python e altri linguaggi. Gli errori riscontrati durante l'esecuzione o lo streaming delle query vengono segnalati in una colonna aggiuntiva alla fine denominata "Metadati freccia PQ".
202 Accepted		Richiesta accettata, esecuzione di query in corso. Intestazioni Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	È stato superato il limite di velocità del servizio. Il server restituisce un'intestazione `Retry-After` che indica, in secondi, per quanto tempo il client deve attendere prima di inviare richieste aggiuntive. Intestazioni Retry-After: integer
Other Status Codes	ErrorResponse	Codici di errore comuni: DataflowExecuteQueryError - Esecuzione della query non riuscita. Alcuni possibili motivi includono: il nome della query specificato non è valido o vuoto, il documento mashup personalizzato non è valido o il nome della query specificato non è stato trovato nel flusso di dati (o nel documento mashup personalizzato, se specificato).

Definizioni

Nome	Descrizione
ErrorRelatedResource	Oggetto dettagli risorsa correlato all'errore.
ErrorResponse	Risposta di errore.
ErrorResponseDetails	Dettagli della risposta di errore.
ExecuteQueryRequest	Richiedere il payload per l'esecuzione di una query su un flusso di dati.

ErrorRelatedResource

Oggetto

Oggetto dettagli risorsa correlato all'errore.

Nome	Tipo	Descrizione
resourceId	string	ID risorsa coinvolto nell'errore.
resourceType	string	Tipo della risorsa coinvolta nell'errore.

ErrorResponse

Oggetto

Risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
isRetriable	boolean	Se true, la richiesta può essere ritentata. Usare l'intestazione della `Retry-After` risposta per determinare il ritardo, se disponibile.
message	string	Rappresentazione leggibile dell'errore.
moreDetails	ErrorResponseDetails[]	Elenco di dettagli aggiuntivi sull'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.
requestId	string (uuid)	ID della richiesta associata all'errore.

ErrorResponseDetails

Oggetto

Dettagli della risposta di errore.

Nome	Tipo	Descrizione
errorCode	string	Identificatore specifico che fornisce informazioni su una condizione di errore, consentendo la comunicazione standardizzata tra il servizio e i relativi utenti.
message	string	Rappresentazione leggibile dell'errore.
relatedResource	ErrorRelatedResource	Dettagli della risorsa correlati all'errore.

ExecuteQueryRequest

Oggetto

Richiedere il payload per l'esecuzione di una query su un flusso di dati.

Nome	Tipo	Descrizione
customMashupDocument	string	Documento mashup personalizzato facoltativo per eseguire l'override del mashup predefinito del flusso di dati.
queryName	string	Nome della query da eseguire dal flusso di dati (o dal documento mashup personalizzato, se specificato).