Query Execution - Execute Query

Dienst:: Dataflow

API-Version:: v1

Führt eine Abfrage für einen Datenfluss aus und gibt das Ergebnis zurück.
Führt eine angegebene Abfrage für einen Datenfluss aus und überträgt das Ergebnis zurück an den Aufrufer. Unterstützt die Verwendung von benutzerdefinierten Mashupdokumenten für erweiterte Szenarien.

Diese API unterstützt LRO-.

Erlaubnisse

Der Aufrufer muss über Ausführungsberechtigungen für den Datenfluss verfügen.

Erforderliche delegierte Bereiche

Dataflow.Execute.All oder Item.Execute.All.

Einschränkungen

Abfragen können maximal 90 Sekunden lang ausgeführt werden.

Von Microsoft Entra unterstützte Identitäten

Diese API unterstützt die in diesem Abschnitt aufgeführten Microsoft Identitäten.

Identität	Support
Benutzer	Yes
Service Principal und Verwaltete Identitäten	Yes

Antwortformate

Verwenden Sie den Accept Header, um den Antwortmedientyp auszuhandeln. Heute ist das Apache Arrow Streaming-Format das einzige verfügbare Antwortformat; In Zukunft können weitere Formate angeboten werden.

Apache Arrow Streaming-Format

Medientyp:application/vnd.apache.arrow.stream

Beim Senden dieses Medientyps ist der pq-arrow-version Medientypparameter erforderlich und wählt die Pfeilcodierungsversion aus:

pq-arrow-version=1 — Ursprüngliche Apache-Pfeilcodierung. Kompatibel mit allen Datenflüssen, einschließlich derJenigen, die eine Verbindung über ein lokales Datengateway herstellen.
pq-arrow-version=2 – Neuere Apache Arrow-Codierung mit verbesserter Streamingleistung. Wird für Datenflüsse, die eine Verbindung über ein lokales Datengateway herstellen, nicht unterstützt.

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

Wenn der Accept Header vollständig ausgelassen wird (oder */* gesendet wird), wird die Antwort standardmäßig auf application/vnd.apache.arrow.stream;pq-arrow-version=1.

Schnittstelle

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
dataflowId	path	True	string (uuid)	Die Datenfluss-ID.
workspaceId	path	True	string (uuid)	Die Arbeitsbereichs-ID.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
Accept		string	Die gewünschte Medienart der Antwort. Die Vorgangsbeschreibung finden Sie in der Liste der unterstützten Antwortformate. Heute wird nur `application/vnd.apache.arrow.stream` unterstützt; beim Senden dieses Medientyps ist der `pq-arrow-version` Parameter erforderlich und muss entweder `1` oder `2` (z. B. `application/vnd.apache.arrow.stream;pq-arrow-version=1`) sein. Wenn die Kopfzeile vollständig weggelassen wird, wird der Standardwert `application/vnd.apache.arrow.stream;pq-arrow-version=1` verwendet.

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
queryName	True	string	Der Name der Abfrage, die aus dem Datenfluss ausgeführt werden soll (oder aus dem benutzerdefinierten Mashupdokument, sofern angegeben).
customMashupDocument		string	Optionales benutzerdefiniertes Mashupdokument zum Überschreiben des Standardmäßigen Mashups des Datenflusses.

Antworten

Name	Typ	Beschreibung
200 OK	file	Das Abfrageergebnis wurde erfolgreich gestreamt. Der Antworttext wird im Medientyp codiert, der über den Header der Anforderung ausgehandelt wird (siehe Vorgangsbeschreibung `Accept` für die Liste der unterstützten Antwortformate). Wenn die Antwort im Apache Arrow Streaming-Format (`application/vnd.apache.arrow.stream`das einzige format heute verfügbar) ist, werden die Ergebnisse als Apache Arrow IPC gestreamt. Die zurückgegebene Pfeilcodierungsversion entspricht dem Parameter, der `pq-arrow-version` auf der Kopfzeile der Anforderung `Accept` gesendet wird (Standard `1`). In der Arrow-Dokumentation erfahren Sie, wie Sie den Stream in Python und anderen Sprachen lesen. Fehler, die während der Abfrageausführung oder beim Streaming aufgetreten sind, werden in einer zusätzlichen Spalte am Ende mit dem Namen "PQ Arrow Metadata" gemeldet.
202 Accepted		Anforderung akzeptiert, Abfrageausführung wird ausgeführt. Header Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	Der Dienstratengrenzwert wurde überschritten. Der Server gibt einen `Retry-After` Header zurück, der in Sekunden angibt, wie lange der Client warten muss, bevor zusätzliche Anforderungen gesendet werden. Header Retry-After: integer
Other Status Codes	ErrorResponse	Häufige Fehlercodes: DataflowExecuteQueryError – Fehler bei der Abfrageausführung. Einige mögliche Gründe sind: Der angegebene Abfragename ist ungültig oder leer, das benutzerdefinierte Mashupdokument ist ungültig, oder der angegebene Abfragename wurde im Datenfluss nicht gefunden (oder im benutzerdefinierten Mashupdokument, falls angegeben).

Definitionen

Name	Beschreibung
ErrorRelatedResource	Das Fehlerbezogene Ressourcendetails-Objekt.
ErrorResponse	Die Fehlerantwort.
ErrorResponseDetails	Die Fehlerantwortdetails.
ExecuteQueryRequest	Anforderungsnutzlast zum Ausführen einer Abfrage für einen Datenfluss.

ErrorRelatedResource

Objekt

Das Fehlerbezogene Ressourcendetails-Objekt.

Name	Typ	Beschreibung
resourceId	string	Die Ressourcen-ID, die an dem Fehler beteiligt ist.
resourceType	string	Der Typ der Ressource, die an dem Fehler beteiligt ist.

ErrorResponse

Objekt

Die Fehlerantwort.

Name	Typ	Beschreibung
errorCode	string	Ein bestimmter Bezeichner, der Informationen über eine Fehlerbedingung bereitstellt und eine standardisierte Kommunikation zwischen unserem Dienst und seinen Benutzern ermöglicht.
isRetriable	boolean	Wenn true, kann die Anforderung wiederholt werden. Verwenden Sie den `Retry-After` Antwortheader, um die Verzögerung zu ermitteln, falls verfügbar.
message	string	Eine lesbare Darstellung des Fehlers.
moreDetails	ErrorResponseDetails[]	Liste der zusätzlichen Fehlerdetails.
relatedResource	ErrorRelatedResource	Die fehlerbezogenen Ressourcendetails.
requestId	string (uuid)	ID der Anforderung, die dem Fehler zugeordnet ist.

ErrorResponseDetails

Objekt

Die Fehlerantwortdetails.

Name	Typ	Beschreibung
errorCode	string	Ein bestimmter Bezeichner, der Informationen über eine Fehlerbedingung bereitstellt und eine standardisierte Kommunikation zwischen unserem Dienst und seinen Benutzern ermöglicht.
message	string	Eine lesbare Darstellung des Fehlers.
relatedResource	ErrorRelatedResource	Die fehlerbezogenen Ressourcendetails.

ExecuteQueryRequest

Objekt

Anforderungsnutzlast zum Ausführen einer Abfrage für einen Datenfluss.

Name	Typ	Beschreibung
customMashupDocument	string	Optionales benutzerdefiniertes Mashupdokument zum Überschreiben des Standardmäßigen Mashups des Datenflusses.
queryName	string	Der Name der Abfrage, die aus dem Datenfluss ausgeführt werden soll (oder aus dem benutzerdefinierten Mashupdokument, sofern angegeben).