Resposta de HTTP de consulta/gestão

Estado da resposta

A linha de estado 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 estado estão atualmente a ser utilizados, embora possa ser devolvido qualquer código HTTP válido.

Código	Subcodificador	Description
100	Continuar	O cliente pode continuar a enviar o pedido.
200	OK	O pedido começou a ser processado com êxito.
400	BadRequest	O pedido está mal formado e falhou (permanentemente).
401	Não autorizado	O cliente tem de se autenticar primeiro.
403	Proibido	O pedido de cliente é negado.
404	NotFound	O pedido referencia uma entidade não existente.
413	PayloadTooLarge	O payload do pedido excedeu os limites.
429	TooManyRequests	O pedido foi negado devido à limitação.
504	Tempo Limite	O pedido excedeu o limite de tempo.
520	ServiceError	O serviço encontrou um erro ao processar o pedido.

Nota

O código de estado 200 mostra que o processamento do pedido foi iniciado com êxito e não que foi concluído com êxito. As falhas encontradas durante o processamento do pedido após a devolução do código de estado 200 são denominadas "falhas parciais de consulta" e, quando são encontradas, os indicadores especiais são injetados no fluxo de resposta para alertar o cliente de que ocorreram.

Cabeçalhos de resposta

Serão devolvidos os seguintes cabeçalhos personalizados.

Cabeçalho personalizado	Description
x-ms-client-request-id	O identificador de pedido exclusivo enviado no cabeçalho do pedido com o mesmo nome ou algum identificador exclusivo.
x-ms-activity-id	Um identificador de correlação globalmente exclusivo para o pedido. É criado pelo serviço.

Corpo da resposta

Se o código de estado for 200, o corpo da resposta é um documento JSON que codifica os resultados do comando de consulta ou gestão como uma sequência de tabelas retangulares. Veja abaixo para obter detalhes.

Nota

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

Se o código de estado indicar um erro 4xx ou 5xx, que não seja 401, o corpo da resposta é um documento JSON que codifica os detalhes da falha. Para obter mais informações, veja Diretrizes da API REST da Microsoft.

Nota

Se o Accept cabeçalho não estiver incluído no pedido, o corpo de resposta de uma falha não é 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 saco de propriedades JSON com os seguintes pares nome/valor.

Name	Valor
Tables	Uma matriz do saco de propriedades Tabela.

O saco de propriedades Tabela tem os seguintes pares nome/valor.

Name	Valor
TableName	Uma cadeia que identifica a tabela.
Colunas	Uma matriz do saco de propriedades Coluna.
Rows (Linhas)	Uma matriz da matriz Linha.

O conjunto de propriedades Coluna tem os seguintes pares nome/valor.

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

A matriz Linha tem a mesma ordem que a respetiva matriz Colunas. A matriz Linha também tem um elemento que coincide com o valor da linha para a coluna relevante. Os tipos de dados escalares que não podem ser representados em JSON, como datetime e timespan, são representados como cadeias JSON.

O exemplo seguinte mostra um desses objetos possíveis, quando 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 gestão devolvem um resultado com uma única tabela, contendo as informações geradas pelo comando de gestão. Por exemplo, o .show databases comando devolve uma única tabela com os detalhes de todas as bases de dados acessíveis no cluster.

Geralmente, as consultas devolvem várias tabelas. Para cada instrução de expressão tabular, uma ou mais tabelas são geradas por ordem, representando os resultados produzidos pela instrução .

Nota

Podem existir várias tabelas deste tipo devido a lotes e operadores de fork).

São muitas vezes produzidas três tabelas:

• Uma @ExtendedProperties tabela que fornece valores adicionais, como instruções de visualização de cliente (informações fornecidas pelo operador de composição), informações sobre o cursor de base de dados eficaz da consulta ou informações sobre a utilização efetiva da consulta da cache de resultados da consulta.

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

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

  Para consultas enviadas com o protocolo v2, a tabela tem três colunas: (1) Uma integer coluna chamada TableId a indicar a que tabela nos resultados o registo se aplica; (2) Uma string coluna denominada Key que indica o tipo de informações fornecidas pelo registo (valores possíveis: Visualization, ServerCachee Cursor); (3) Uma dynamic coluna denominada Value fornecer as informações determinadas pela 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 própria consulta, como, por exemplo, se foi concluída com êxito ou não, e quais foram os recursos consumidos pela consulta.

  Esta tabela tem a seguinte estrutura:

  CarimboDeDataEHora	Gravidade	SeverityName	StatusCode	StatusDescription	de palavras	RequestId	ActivityId	SubActivityId	ClientActivityId
  2020-05-02 06:09:12.7052077	4	Informações	0	Consulta concluída com êxito	1	...	...	...	...

  Os valores de gravidade de 2 ou menor indicam uma falha.

• Uma tabela TableOfContents, que é criada pela última vez, e lista as outras tabelas nos resultados.

  Um exemplo para esta tabela é:

  Ordinal	Tipo	Name	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