Query Execution - Execute Query

Serviço:: Dataflow

Versão da API:: v1

Executa uma consulta em um fluxo de dados e retorna o resultado.
Executa uma consulta especificada em um fluxo de dados e transmite o resultado de volta para o chamador. Dá suporte ao uso de documentos de mashup personalizados para cenários avançados.

Essa API dá suporte a LRO (operações de execução longa).

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 ser executadas por um máximo de 90 segundos.

Identidades com suporte do Microsoft Entra

Esta API dá suporte às identidades do Microsoft listadas nesta seção.

Identidade	Support
Utilizador	Yes
Entidade de serviço e identidades gerenciadas	Yes

Formatos de resposta

Use o Accept cabeçalho para negociar o tipo de mídia de resposta. Hoje, o formato de streaming do Apache Arrow é o único formato de resposta disponível; formatos adicionais podem ser oferecidos no futuro.

Formato de streaming do Apache Arrow

Tipo de mídia:application/vnd.apache.arrow.stream

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

pq-arrow-version=1 — Codificação original do Apache Arrow. Compatível com todos os fluxos de dados, incluindo aqueles que se conectam por meio de um gateway de dados local.
pq-arrow-version=2 — Codificação mais recente do Apache Arrow com melhor desempenho de streaming. Não há suporte para fluxos de dados que se conectam por meio de um gateway de dados local.

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

Se o Accept cabeçalho for omitido inteiramente (ou */* for enviado), a resposta usará como padrão application/vnd.apache.arrow.stream;pq-arrow-version=1.

Interfase

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
dataflowId	path	True	string (uuid)	A ID do fluxo de dados.
workspaceId	path	True	string (uuid)	O identificador do espaço de trabalho.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
Accept		string	O tipo de mídia desejado para a resposta. Consulte a descrição da operação para obter a lista de formatos de resposta com suporte. Hoje, só `application/vnd.apache.arrow.stream` há suporte; ao enviar esse tipo de mídia, o `pq-arrow-version` parâmetro é necessário e deve ser `1` ou `2` (por exemplo `application/vnd.apache.arrow.stream;pq-arrow-version=1`). Se o cabeçalho for totalmente omitido, o padrão `application/vnd.apache.arrow.stream;pq-arrow-version=1` será usado.

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
queryName	True	string	O nome da consulta a ser executada do fluxo de dados (ou do documento de mashup personalizado, se fornecido).
customMashupDocument		string	Documento de mashup personalizado opcional para substituir o mashup padrão do fluxo de dados.

Respostas

Nome	Tipo	Description
200 OK	file	O resultado da consulta foi transmitido com êxito. O corpo da resposta é codificado no tipo de mídia negociado por meio do cabeçalho da solicitação (consulte a descrição da `Accept` operação para a lista de formatos de resposta com suporte). Quando a resposta está no formato de streaming do Apache Arrow (`application/vnd.apache.arrow.stream`o único formato disponível hoje), os resultados são transmitidos como IPC de Seta do Apache; a versão de codificação de seta retornada corresponde ao `pq-arrow-version` parâmetro enviado no cabeçalho da `Accept` solicitação (padrão `1`). Consulte a documentação de seta sobre como ler o fluxo em Python e em outros idiomas. Erros encontrados durante a execução da consulta ou streaming são relatados em uma coluna adicional no final chamada 'Metadados de Seta PQ'.
202 Accepted		Solicitação aceita, 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 taxa de serviço foi excedido. O servidor retorna um `Retry-After` cabeçalho indicando, em segundos, quanto tempo o cliente deve aguardar antes de enviar solicitações adicionais. Cabeçalhos Retry-After: integer
Other Status Codes	ErrorResponse	Códigos de erro comuns: DataflowExecuteQueryError – Falha na execução da consulta. Alguns motivos possíveis incluem: o nome da consulta especificado é inválido ou vazio, o documento de mashup personalizado é inválido ou o nome da consulta especificado não foi encontrado no fluxo de dados (ou no documento de mashup personalizado, se fornecido).

Definições

Nome	Description
ErrorRelatedResource	O objeto de detalhes do recurso relacionado ao erro.
ErrorResponse	A resposta de erro.
ErrorResponseDetails	Os detalhes da resposta de erro.
ExecuteQueryRequest	Solicite conteúdo para executar uma consulta em um fluxo de dados.

ErrorRelatedResource

Objeto

O objeto de detalhes do recurso relacionado ao erro.

Nome	Tipo	Description
resourceId	string	A ID do recurso envolvida no erro.
resourceType	string	O tipo do recurso envolvido no erro.

ErrorResponse

Objeto

A resposta de erro.

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

ErrorResponseDetails

Objeto

Os detalhes da resposta de erro.

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

ExecuteQueryRequest

Objeto

Solicite conteúdo para executar uma consulta em um fluxo de dados.

Nome	Tipo	Description
customMashupDocument	string	Documento de mashup personalizado opcional para substituir o mashup padrão do fluxo de dados.
queryName	string	O nome da consulta a ser executada do fluxo de dados (ou do documento de mashup personalizado, se fornecido).