Query Execution - Execute Query

服務:: Dataflow

API 版本:: v1

對資料流執行查詢並回傳結果。
對資料流執行指定的查詢，並將結果串流回呼叫者。支援使用自訂混搭文件以應付進階情境。

此 API 支援長時間執行的作業（LRO）。

權限

呼叫者必須擁有資料流的執行權限。

必要的委派範圍

Dataflow.Execute.All 或 Item.Execute.All.

局限性

查詢最長可持續 90 秒。

Microsoft Entra 支援的身份識別

此 API 支援本節中列出的Microsoft 身分識別。

身份	Support
User	Yes
服務主體和受控識別	Yes

回應格式

利用 Accept 標頭來協商回應媒體類型。如今，Apache Arrow 串流格式是唯一可用的回應格式;未來可能會提供更多格式。

Apache Arrow 串流格式

媒體類型：application/vnd.apache.arrow.stream

傳送此媒體類型時，pq-arrow-version使用媒體類型參數，並選擇 Arrow 編碼版本：

pq-arrow-version=1 — 原始 Apache Arrow 編碼。相容於所有資料流，包括透過本地資料閘道連接的流量。
pq-arrow-version=2 — 更新的 Apache Arrow 編碼，串流效能提升。不支援透過本地資料閘道連接的資料流。

範例：Accept: application/vnd.apache.arrow.stream;pq-arrow-version=2

若 Accept 標頭完全省略（或 */* 已發送），回應預設為 application/vnd.apache.arrow.stream;pq-arrow-version=1。

介面

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

URI 參數

名稱	位於	必要	類型	Description
dataflowId	path	True	string (uuid)	數據流標識碼。
workspaceId	path	True	string (uuid)	工作區識別碼。

要求標頭

名稱	必要	類型	Description
Accept		string	回應的媒介類型。請參閱操作說明以了解支援的回應格式清單。目前，僅 `application/vnd.apache.arrow.stream` 支援;傳送此媒介類型時， `pq-arrow-version` 參數必須為 `1` 或 `2` （例如 `application/vnd.apache.arrow.stream;pq-arrow-version=1`）。若完全省略標頭，則使用預設 `application/vnd.apache.arrow.stream;pq-arrow-version=1` 標頭。

要求本文

名稱	必要	類型	Description
queryName	True	string	從資料流程（或若提供自訂混搭文件）執行的查詢名稱。
customMashupDocument		string	可選的自訂混搭文件，用來覆寫資料流的預設混搭。

回覆

名稱	類型	Description
200 OK	file	查詢結果已成功串流。回應實體以媒介類型編碼，透過請求 `Accept` 標頭協商（請參見操作說明中支援的回應格式列表）。當回應以 Apache Arrow 串流格式（`application/vnd.apache.arrow.stream`目前唯一可用的格式）時，結果會以 Apache Arrow IPC 格式串流;回傳的 Arrow 編碼版本與請求`pq-arrow-version`標頭上的參數相符`Accept`（預設`1`）。請參考 Arrow 文件，了解如何用 Python 及其他語言閱讀串流。查詢執行或串流過程中遇到的錯誤會以末尾的額外欄位「PQ Arrow Metadata」報告。
202 Accepted		請求已接受，查詢正在執行中。標題 Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	服務費率上限被超標。伺服器會回傳一個 `Retry-After` 標頭，以秒數表示客戶端在發送額外請求前必須等待多久。標題 Retry-After: integer
Other Status Codes	ErrorResponse	常見的錯誤碼： DataflowExecuteQueryError - 查詢執行失敗。可能原因包括：指定的查詢名稱無效或空、自訂混搭文件無效，或資料流中找不到指定的查詢名稱（若有則找不到）。

定義

名稱	Description
ErrorParameter	一個結構化參數，提供關於錯誤的額外機器可讀上下文。
ErrorRelatedResource	錯誤相關的資源詳細資料物件。
ErrorResponse	錯誤回應。
ErrorResponseDetails	錯誤回應詳細數據。
ExecuteQueryRequest	請求有效載荷以執行對資料流的查詢。

ErrorParameter

Object

一個結構化參數，提供關於錯誤的額外機器可讀上下文。

名稱	類型	Description
message	string	一個人類可讀的參數意義描述。
name	string	參數識別碼。
value	string	這是參數值。

ErrorRelatedResource

Object

錯誤相關的資源詳細資料物件。

名稱	類型	Description
resourceId	string	發生錯誤的資源識別碼。
resourceType	string	發生錯誤的資源類型。

ErrorResponse

Object

錯誤回應。

名稱	類型	Description
errorCode	string	提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
isRetriable	boolean	若屬實，請求可重新嘗試。如果有延遲，請使用 `Retry-After` 回應標頭來判斷延遲。
message	string	錯誤的人類可讀取表示法。
moreDetails	ErrorResponseDetails[]	其他錯誤詳細數據的清單。
parameters	ErrorParameter[]	結構化參數提供更多機器可讀的錯誤上下文。
relatedResource	ErrorRelatedResource	錯誤相關的資源詳細數據。
requestId	string (uuid)	與錯誤相關聯的要求標識碼。

ErrorResponseDetails

Object

錯誤回應詳細數據。

名稱	類型	Description
errorCode	string	提供錯誤狀況相關信息的特定標識碼，允許服務與其使用者之間的標準化通訊。
message	string	錯誤的人類可讀取表示法。
parameters	ErrorParameter[]	結構化參數提供更多機器可讀的錯誤上下文。
relatedResource	ErrorRelatedResource	錯誤相關的資源詳細數據。

ExecuteQueryRequest

Object

請求有效載荷以執行對資料流的查詢。

名稱	類型	Description
customMashupDocument	string	可選的自訂混搭文件，用來覆寫資料流的預設混搭。
queryName	string	從資料流程（或若提供自訂混搭文件）執行的查詢名稱。