Query Execution - Execute Query

サービス:: Dataflow

API バージョン:: v1

データフローに対してクエリを実行し、結果を返します。
データフローに対して指定されたクエリを実行し、結果を呼び出し元にストリーミングします。高度なシナリオでのカスタムマッシュアップドキュメントの使用をサポートします。

この API は、実行時間の長い操作 (LRO)をサポートします。

Permissions

呼び出し元には、データフローの実行アクセス許可が必要です。

必要な委任されたスコープ

Dataflow.Execute.All または Item.Execute.All。

制限事項

クエリは最大 90 秒間実行できます。

Microsoft Entra でサポートされている ID

この API では、このセクションに記載されている Microsoft ID がサポートされています。

アイデンティティ	Support
ユーザー	イエス
サービスプリンシパルとマネージド ID	イエス

応答形式

Accept ヘッダーを使用して、応答メディアの種類をネゴシエートします。現在、 Apache Arrow ストリーミング形式は、使用可能な唯一の応答形式です。今後、追加の形式が提供される可能性があります。

Apache Arrow ストリーミング形式

メディアの種類:application/vnd.apache.arrow.stream

このメディアの種類を送信する場合は、 pq-arrow-version メディアの種類のパラメーターが必要であり、方向エンコードバージョンを選択します。

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 パラメーター

名前	/	必須	型	説明
dataflowId	path	True	string (uuid)	データフロー ID。
workspaceId	path	True	string (uuid)	ワークスペース ID。

要求ヘッダー

名前	必須	型	説明
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` が使用されます。

要求本文

名前	必須	型	説明
queryName	True	string	データフローから (またはカスタムマッシュアップドキュメントが指定されている場合は) 実行するクエリの名前。
customMashupDocument		string	データフローの既定のマッシュアップをオーバーライドするオプションのカスタムマッシュアップドキュメント。

応答

名前	型	説明
200 OK	file	クエリ結果が正常にストリーミングされました。応答本文は、要求の `Accept` ヘッダーを介してネゴシエートされたメディアの種類でエンコードされます (サポートされている応答形式の一覧については、操作の説明を参照してください)。応答が Apache Arrow ストリーミング形式 (`application/vnd.apache.arrow.stream`、現在使用可能な唯一の形式) の場合、結果は Apache Arrow IPC としてストリーミングされます。返される方向エンコードバージョンは、要求の `Accept` ヘッダーで送信された`pq-arrow-version` パラメーターと一致します (既定の`1`)。 Python やその他の言語でストリームを読む方法については、 Arrow のドキュメントを参照してください。クエリの実行中またはストリーミング中に発生したエラーは、'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 - クエリの実行に失敗しました。考えられる理由としては、指定したクエリ名が無効か空か、カスタムマッシュアップドキュメントが無効か、指定したクエリ名がデータフロー (または指定されている場合はカスタムマッシュアップドキュメント内) に見つかりませんでした。

定義

名前	説明
ErrorRelatedResource	エラー関連のリソース詳細オブジェクト。
ErrorResponse	エラー応答。
ErrorResponseDetails	エラー応答の詳細。
ExecuteQueryRequest	データフローに対してクエリを実行するための要求ペイロード。

ErrorRelatedResource

Object

エラー関連のリソース詳細オブジェクト。

名前	型	説明
resourceId	string	エラーに関係するリソース ID。
resourceType	string	エラーに関係するリソースの種類。

ErrorResponse

Object

エラー応答。

名前	型	説明
errorCode	string	エラー状態に関する情報を提供し、サービスとそのユーザー間の標準化された通信を可能にする特定の識別子。
isRetriable	boolean	true の場合、要求を再試行できます。 `Retry-After`応答ヘッダーを使用して、遅延 (使用可能な場合) を決定します。
message	string	エラーの人間が判読できる表現。
moreDetails	ErrorResponseDetails[]	その他のエラーの詳細の一覧。
relatedResource	ErrorRelatedResource	エラー関連のリソースの詳細。
requestId	string (uuid)	エラーに関連付けられている要求の ID。

ErrorResponseDetails

Object

エラー応答の詳細。

名前	型	説明
errorCode	string	エラー状態に関する情報を提供し、サービスとそのユーザー間の標準化された通信を可能にする特定の識別子。
message	string	エラーの人間が判読できる表現。
relatedResource	ErrorRelatedResource	エラー関連のリソースの詳細。

ExecuteQueryRequest

Object

データフローに対してクエリを実行するための要求ペイロード。

名前	型	説明
customMashupDocument	string	データフローの既定のマッシュアップをオーバーライドするオプションのカスタムマッシュアップドキュメント。
queryName	string	データフローから (またはカスタムマッシュアップドキュメントが指定されている場合は) 実行するクエリの名前。