Query Execution - Execute Query

Serviço:: Dataflow

Versão da API:: v1

Executa uma consulta contra um fluxo de dados e devolve o resultado.
Executa uma consulta especificada contra um fluxo de dados e transmite o resultado de volta ao chamador. Suporta o uso de documentos mashup personalizados para cenários avançados.

Esta API suporta operações de longa duração (LRO).

Permissions

O chamador deve ter permissões de execução para o fluxo de dados.

Escopos delegados necessários

Dataflow.Execute.All ou Item.Execute.All.

Limitações

As consultas podem correr durante um máximo de 90 segundos.

Identidades suportadas pelo Entra da Microsoft

Esta API suporta as identidades do Microsoft listadas nesta secção.

Identidade	Support
User	Yes
Entidade de serviço e identidades geridas	Yes

Formatos de resposta

Use o Accept cabeçalho para negociar o tipo de meio de resposta. Hoje, o formato de streaming Apache Arrow é o único formato de resposta disponível; Formatos adicionais poderão ser oferecidos no futuro.

Formato de streaming Apache Arrow

Tipo de media:application/vnd.apache.arrow.stream

Ao enviar este tipo de meio, é necessário o pq-arrow-version parâmetro de tipo de média e seleciona a versão de codificação Arrow:

pq-arrow-version=1 — Codificação original Apache Arrow. Compatível com todos os fluxos de dados, incluindo aqueles que se ligam através de um gateway de dados local.
pq-arrow-version=2 — Codificação Apache Arrow mais recente com melhor desempenho em streaming. Não é suportado para fluxos de dados que se ligam através de um gateway de dados local.

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

Se o Accept cabeçalho for omitido completamente (ou */* for enviado), a resposta passa por defeito a application/vnd.apache.arrow.stream;pq-arrow-version=1.

Interfaz

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

Parâmetros do URI

Name	Em	Obrigatório	Tipo	Descrição
dataflowId	path	True	string (uuid)	O ID do fluxo de dados.
workspaceId	path	True	string (uuid)	O ID do espaço de trabalho.

Cabeçalho do Pedido

Name	Obrigatório	Tipo	Descrição
Accept		string	O tipo de media desejado para a resposta. Consulte a descrição da operação para a lista de formatos de resposta suportados. Atualmente, apenas `application/vnd.apache.arrow.stream` é suportado; ao enviar este tipo de meio, o `pq-arrow-version` parâmetro é necessário e deve ser ou `1` ou `2` (por exemplo, `application/vnd.apache.arrow.stream;pq-arrow-version=1`). Se o cabeçalho for omitido completamente, o padrão `application/vnd.apache.arrow.stream;pq-arrow-version=1` é usado.

Corpo do Pedido

Name	Obrigatório	Tipo	Descrição
queryName	True	string	O nome da consulta a executar a partir do fluxo de dados (ou do documento personalizado de mashup, se fornecida).
customMashupDocument		string	Documento de mashup personalizado opcional para sobrepor o mashup padrão do dataflow.

Respostas

Name	Tipo	Descrição
200 OK	file	O resultado da consulta foi transmitido com sucesso. O corpo da resposta é codificado no tipo de media negociado através do cabeçalho do `Accept` pedido (ver a descrição da operação para a lista de formatos de resposta suportados). Quando a resposta está no formato de streaming Apache Arrow (`application/vnd.apache.arrow.stream`, o único formato disponível atualmente), os resultados são transmitidos como IPC Apache Arrow; a versão de codificação Arrow devolvida corresponde ao `pq-arrow-version` parâmetro enviado no cabeçalho do `Accept` pedido (por defeito `1`). Consulte a documentação do Arrow sobre como ler o fluxo em Python e outras linguagens. Os erros encontrados durante a execução da consulta ou o streaming são reportados numa coluna adicional no final chamada 'PQ Arrow Metadata'.
202 Accepted		Pedido aceite, execução da consulta em andamento. Cabeçalhos Location: string x-ms-operation-id: string Retry-After: integer
429 Too Many Requests	ErrorResponse	O limite de tarifa de serviço foi ultrapassado. O servidor devolve um `Retry-After` cabeçalho que indica, em segundos, quanto tempo o cliente deve esperar antes de enviar pedidos adicionais. Cabeçalhos Retry-After: integer
Other Status Codes	ErrorResponse	Códigos de erro comuns: DataflowExecuteQueryError - Falha na execução da consulta. Algumas razões possíveis incluem: o nome da consulta especificado é inválido ou vazio, o documento personalizado de mashup é inválido, ou o nome de consulta especificado não foi encontrado no fluxo de dados (ou no documento personalizado de mashup, se fornecido).

Definições

Name	Descrição
ErrorRelatedResource	O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse	A resposta de erro.
ErrorResponseDetails	Os detalhes da resposta de erro.
ExecuteQueryRequest	Solicite carga útil para executar uma consulta num fluxo de dados.

ErrorRelatedResource

Object

O objeto de detalhes do recurso relacionado ao erro.

Name	Tipo	Descrição
resourceId	string	A ID do recurso envolvida no erro.
resourceType	string	O tipo de recurso envolvido no erro.

ErrorResponse

Object

A resposta de erro.

Name	Tipo	Descrição
errorCode	string	Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
isRetriable	boolean	Quando confirmado, o pedido pode ser retentado. Use o `Retry-After` cabeçalho de resposta para determinar o atraso, se disponível.
message	string	Uma representação legível por humanos do erro.
moreDetails	ErrorResponseDetails[]	Lista de detalhes de erro adicionais.
relatedResource	ErrorRelatedResource	Os detalhes do recurso relacionados ao erro.
requestId	string (uuid)	ID da solicitação associada ao erro.

ErrorResponseDetails

Object

Os detalhes da resposta de erro.

Name	Tipo	Descrição
errorCode	string	Um identificador específico que fornece informações sobre uma condição de erro, permitindo uma comunicação padronizada entre nosso serviço e seus usuários.
message	string	Uma representação legível por humanos do erro.
relatedResource	ErrorRelatedResource	Os detalhes do recurso relacionados ao erro.

ExecuteQueryRequest

Object

Solicite carga útil para executar uma consulta num fluxo de dados.

Name	Tipo	Descrição
customMashupDocument	string	Documento de mashup personalizado opcional para sobrepor o mashup padrão do dataflow.
queryName	string	O nome da consulta a executar a partir do fluxo de dados (ou do documento personalizado de mashup, se fornecida).