Resposta HTTP da consulta/gerenciamento

Status de resposta

A linha de status de resposta HTTP segue os códigos de resposta padrão HTTP. Por exemplo, o código 200 indica êxito.

Os seguintes códigos de status estão em uso no momento, embora qualquer código HTTP válido possa ser retornado.

Código	Subcódigo	Descrição
100	Continuar	O cliente pode continuar a enviar a solicitação.
200	OK	A solicitação iniciou o processamento com êxito.
400	BadRequest	A solicitação está mal formada e falhou (permanentemente).
401	Não Autorizado	O cliente precisa se autenticar primeiro.
403	Proibido	A solicitação do cliente foi negada.
404	NotFound	A solicitação faz referência a uma entidade não existente.
413	PayloadTooLarge	O conteúdo da solicitação excedeu os limites.
429	TooManyRequests	A solicitação foi negada devido à limitação.
504	Tempo limite	A solicitação atingiu o tempo limite.
520	ServiceError	O serviço encontrou um erro ao processar a solicitação.

Observação

O código 200 status mostra que o processamento da solicitação foi iniciado com êxito e não que foi concluído com êxito. As falhas encontradas durante o processamento da solicitação após o retorno do código de status 200 são chamadas de "falhas de consulta parciais" e, quando são encontradas, indicadores especiais são injetados no fluxo de resposta para alertar o cliente de que eles ocorreram.

Cabeçalhos de resposta

Os cabeçalhos personalizados a seguir serão retornados.

Cabeçalho personalizado	Descrição
x-ms-client-request-id	O identificador de solicitação exclusivo enviado no cabeçalho da solicitação com o mesmo nome ou algum identificador exclusivo.
x-ms-activity-id	Um identificador de correlação global exclusivo para a solicitação. Ele é criado pelo serviço.

Corpo da resposta

Se o código status for 200, o corpo da resposta será um documento JSON que codifica os resultados do comando de consulta ou gerenciamento como uma sequência de tabelas retangulares. Confira os detalhes abaixo.

Observação

A sequência de tabelas é refletida pelo SDK. Por exemplo, ao usar o .NET Framework biblioteca Kusto.Data, a sequência de tabelas se torna os resultados no System.Data.IDataReader objeto retornado pelo SDK.

Se o código status indicar um erro 4xx ou 5xx, diferente de 401, o corpo da resposta será um documento JSON que codifica os detalhes da falha. Para obter mais informações, consulte Diretrizes da API REST da Microsoft.

Observação

Se o Accept cabeçalho não estiver incluído na solicitação, o corpo da resposta de uma falha não será necessariamente um documento JSON.

Codificação JSON de uma sequência de tabelas

A codificação JSON de uma sequência de tabelas é um único recipiente de propriedades JSON com os seguintes pares nome/valor.

Nome	Valor
Tabelas	Uma matriz do recipiente de propriedades Table.

O recipiente de propriedades Table tem os seguintes pares nome/valor.

Nome	Valor
TableName	Uma cadeia de caracteres que identifica a tabela.
Colunas	Uma matriz do recipiente de propriedades Column.
Linhas	Uma matriz da matriz Row.

O recipiente de propriedades Column tem os seguintes pares nome/valor.

Nome	Valor
ColumnName	Cadeia de caracteres que identifica a coluna.
Tipo de dados	Uma cadeia de caracteres que fornece o tipo .NET aproximado da coluna.
ColumnType	Uma cadeia de caracteres que fornece o tipo de dados escalar da coluna.

A matriz Row tem a mesma ordem que a respectiva matriz Columns. A matriz Row também tem um elemento que coincide com o valor da linha para a coluna relevante. Tipos de dados escalares que não podem ser representados em JSON, como datetime e timespan, são representados como cadeias de caracteres JSON.

O exemplo a seguir mostra um possível objeto desse tipo, quando ele contém uma única tabela chamada Table_0 que tem uma única coluna Text do tipo stringe uma única linha.

{
    "Tables": [{
        "TableName": "Table_0",
        "Columns": [{
            "ColumnName": "Text",
            "DataType": "String",
            "ColumnType": "string"
        }],
        "Rows": [["Hello, World!"]]
}

Outro exemplo:

O significado das tabelas na resposta

Na maioria dos casos, os comandos de gerenciamento retornam um resultado com uma única tabela, contendo as informações geradas pelo comando de gerenciamento. Por exemplo, o .show databases comando retorna uma única tabela com os detalhes de todos os bancos de dados acessíveis no cluster.

As consultas geralmente retornam várias tabelas. Para cada instrução de expressão tabular, uma ou mais tabelas são geradas em ordem, representando os resultados produzidos pela instrução .

Observação

Pode haver várias dessas tabelas devido a lotes e operadores de bifurcação).

Três tabelas geralmente são produzidas:

• Uma @ExtendedProperties tabela que fornece valores adicionais, como instruções de visualização do cliente (informações fornecidas pelo operador de renderização), informações sobre o cursor de banco de dados efetivo da consulta ou informações sobre o uso efetivo da consulta do cache de resultados da consulta.

  Para consultas enviadas usando o protocolo v1, a tabela tem uma única coluna do tipo string, cujo valor é uma cadeia de caracteres codificada em JSON, como:

  Valor
  {"Visualization":"piechart",...}
  {"Cursor":"637239957206013576"}

  Para consultas enviadas usando o protocolo v2, a tabela tem três colunas: (1) Uma integer coluna chamada TableId indicando a qual tabela no conjunto de resultados o registro se aplica; (2) Uma string coluna chamada Key indicando o tipo de informação fornecida pelo registro (valores possíveis: Visualization, ServerCachee Cursor); (3) Uma dynamic coluna chamada Value fornecendo as informações determinadas por chave.

  Tableid	Chave	Valor
  1	ServerCache	{"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
  1	Visualização	{"Visualization":"piechart",...}

• Uma tabela QueryStatus que fornece informações adicionais sobre a execução da consulta em si, como, se ela foi concluída com êxito ou não, e quais foram os recursos consumidos pela consulta.

  Esta tabela tem a seguinte estrutura:

  Timestamp	Severidade	SeverityName	StatusCode	Statusdescription	Contagem	RequestId	ActivityId	SubActivityId	ClientActivityId
  2020-05-02 06:09:12.7052077	4	Info	0	Consulta concluída com êxito	1	...	...	...	...

  Valores de severidade de 2 ou menor indicam falha.

• Uma tabela TableOfContents, que é criada por último, e lista as outras tabelas nos resultados.

  Um exemplo para esta tabela é:

  Ordinal	Tipo	Nome	Id	PrettyName
  0	QueryResult	PrimaryResult	db9520f9-0455-4cb5-b257-53068497605a
  1	QueryProperties	@ExtendedProperties	908901f6-5319-4809-ae9e-009068c267c7
  2	QueryStatus	QueryStatus	00000000-0000-0000-0000-000000000000