Query Execution - Execute Query

Služba:: Dataflow

Verze rozhraní API:: v1

Spustí dotaz na tok dat a vrátí výsledek.
Provede zadaný dotaz na tok dat a streamuje výsledek zpět volajícímu. Podporuje použití vlastních mashupových dokumentů pro pokročilé scénáře.

Toto rozhraní API podporuje dlouhotrvajících operací (LRO).

Povolení

Volající musí mít oprávnění ke spuštění toku dat.

Požadované delegovaná rozsahy

Dataflow.Execute.All nebo Item.Execute.All.

Omezení

Dotazy můžou běžet maximálně 90 sekund.

Podporované identity v Microsoft Entra

Toto rozhraní API podporuje identity Microsoft uvedené v této části.

Identita	Support
Uživatel	Ano
Hlavní služba a Spravované identity	Ano

Formáty odpovědí

Pomocí hlavičky Accept vyjednáte typ média odpovědi. Dnes je formát streamování Apache Arrow jediným dostupným formátem odpovědi; další formáty mohou být nabízeny v budoucnu.

Formát streamování Apache Arrow

Typ média:application/vnd.apache.arrow.stream

Při odesílání tohoto typu pq-arrow-version média se vyžaduje parametr media-type a vybere verzi kódování šipky:

pq-arrow-version=1 — Původní kódování Apache Arrow. Kompatibilní se všemi toky dat, včetně těch, které se připojují přes místní bránu dat.
pq-arrow-version=2 – Novější kódování Apache Arrow s vylepšeným výkonem streamování Toky dat, které se připojují přes místní bránu dat, se nepodporuje.

Příklad: Accept: application/vnd.apache.arrow.stream;pq-arrow-version=2

Accept Pokud je záhlaví zcela vynecháno (nebo */* je odesláno), odpověď se ve výchozím nastavení nastaví na application/vnd.apache.arrow.stream;pq-arrow-version=1hodnotu .

Rozhraní

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

Parametry identifikátoru URI

Název	V	Vyžadováno	Typ	Description
dataflowId	path	True	string (uuid)	ID toku dat.
workspaceId	path	True	string (uuid)	Identifikátor pracovního prostoru.

Hlavička požadavku

Název	Vyžadováno	Typ	Description
Accept		string	Požadovaný typ média odpovědi. Seznam podporovaných formátů odpovědí najdete v popisu operace. Dnes je podporován pouze `application/vnd.apache.arrow.stream` tento typ média. `pq-arrow-version` Při odesílání tohoto typu média je parametr povinný a musí být buď `1` nebo `2` (např. `application/vnd.apache.arrow.stream;pq-arrow-version=1`). Pokud je záhlaví zcela vynecháno, použije se výchozí hodnota `application/vnd.apache.arrow.stream;pq-arrow-version=1` .

Text požadavku

Název	Vyžadováno	Typ	Description
queryName	True	string	Název dotazu, který se má provést z toku dat (nebo z vlastního mashupového dokumentu, pokud je k dispozici).
customMashupDocument		string	Volitelný vlastní mashup dokument, který přepíše výchozí mashup toku dat.

Odpovědi

Název	Typ	Description
200 OK	file	Výsledek dotazu byl úspěšně streamován. Tělo odpovědi je kódované v typu média vyjednané prostřednictvím hlavičky `Accept` požadavku (viz popis operace pro seznam podporovaných formátů odpovědí). Když je odpověď ve formátu streamování Apache Arrow (`application/vnd.apache.arrow.stream`jediný dostupný formát dnes), výsledky se streamují jako Apache Arrow IPC. Vrácená verze kódování šipky odpovídá `pq-arrow-version` parametru odeslanému v hlavičce požadavku `Accept` (výchozí `1`). Informace o tom, jak číst stream v Pythonu a dalších jazycích, najdete v dokumentaci se šipkami . Chyby, ke kterým došlo při provádění dotazů nebo streamování, se hlásí v dalším sloupci na konci s názvem Metadata šipky PQ.
202 Accepted		Žádost byla přijata a probíhá provádění dotazu. Hlavičky Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	Byl překročen limit přenosové rychlosti služby. Server vrátí hlavičku označující `Retry-After` , jak dlouho musí klient čekat před odesláním dalších požadavků. Hlavičky Retry-After: integer
Other Status Codes	ErrorResponse	Běžné kódy chyb: DataflowExecuteQueryError – Spuštění dotazu se nezdařilo. Mezi možné důvody patří: zadaný název dotazu je neplatný nebo prázdný, vlastní dokument mashupu je neplatný nebo zadaný název dotazu nebyl nalezen v toku dat (nebo ve vlastním dokumentu mashupu, pokud je k dispozici).

Definice

Název	Description
ErrorParameter	Strukturovaný parametr poskytující další strojově čitelný kontext chyby.
ErrorRelatedResource	Chyba související s objektem podrobností o prostředku.
ErrorResponse	Odpověď na chybu.
ErrorResponseDetails	Podrobnosti o odpovědi na chybu.
ExecuteQueryRequest	Žádost o datovou část pro spuštění dotazu na tok dat

ErrorParameter

Objekt

Strukturovaný parametr poskytující další strojově čitelný kontext chyby.

Název	Typ	Description
message	string	Popis významu parametru čitelný člověkem.
name	string	Identifikátor parametru.
value	string	Hodnota parametru.

ErrorRelatedResource

Objekt

Chyba související s objektem podrobností o prostředku.

Název	Typ	Description
resourceId	string	ID prostředku, které je součástí chyby.
resourceType	string	Typ prostředku, který je součástí chyby.

ErrorResponse

Objekt

Odpověď na chybu.

Název	Typ	Description
errorCode	string	Konkrétní identifikátor, který poskytuje informace o chybovém stavu, což umožňuje standardizovanou komunikaci mezi naší službou a jejími uživateli.
isRetriable	boolean	Pokud je hodnota true, je možné požadavek opakovat. Pomocí hlavičky `Retry-After` odpovědi určete zpoždění, pokud je k dispozici.
message	string	Lidské čitelné vyjádření chyby.
moreDetails	ErrorResponseDetails[]	Seznam dalších podrobností o chybě
parameters	ErrorParameter[]	Strukturované parametry poskytují další strojově čitelný kontext chyby.
relatedResource	ErrorRelatedResource	Podrobnosti o prostředku souvisejícím s chybou
requestId	string (uuid)	ID požadavku přidruženého k chybě.

ErrorResponseDetails

Objekt

Podrobnosti o odpovědi na chybu.

Název	Typ	Description
errorCode	string	Konkrétní identifikátor, který poskytuje informace o chybovém stavu, což umožňuje standardizovanou komunikaci mezi naší službou a jejími uživateli.
message	string	Lidské čitelné vyjádření chyby.
parameters	ErrorParameter[]	Strukturované parametry poskytují další strojově čitelný kontext chyby.
relatedResource	ErrorRelatedResource	Podrobnosti o prostředku souvisejícím s chybou

ExecuteQueryRequest

Objekt

Žádost o datovou část pro spuštění dotazu na tok dat

Název	Typ	Description
customMashupDocument	string	Volitelný vlastní mashup dokument, který přepíše výchozí mashup toku dat.
queryName	string	Název dotazu, který se má provést z toku dat (nebo z vlastního mashupového dokumentu, pokud je k dispozici).