Pedido de HTTP de consulta/gestão

Pedir verbo e recurso

Ação	Verbo HTTP	Recurso HTTP
Consulta	GET	/v1/rest/query
Consulta	POST	/v1/rest/query
Consulta v2	GET	/v2/rest/query
Consulta v2	POST	/v2/rest/query
Gestão	POST	/v1/rest/mgmt

Por exemplo, para enviar um comando de gestão ("gestão") para um ponto final de serviço, utilize a seguinte linha de pedido:

POST https://help.kusto.windows.net/v1/rest/mgmt HTTP/1.1

Veja abaixo os cabeçalhos e o corpo do pedido a incluir.

Cabeçalhos do pedido

A tabela seguinte contém os cabeçalhos comuns utilizados para operações de consulta e gestão.

Cabeçalho padrão	Description	Obrigatório/Opcional
Accept	Definir como application/json	Necessário
Accept-Encoding	As codificações suportadas são gzip e deflate	Opcional
Authorization	Ver autenticação	Necessário
Connection	Recomendamos que ative Keep-Alive	Opcional
Content-Length	Recomendamos que especifique o comprimento do corpo do pedido quando conhecido	Opcional
Content-Type	Definir como application/json com charset=utf-8	Necessário
Expect	Pode ser definido como 100-Continue	Opcional
Host	Definido como o nome de domínio qualificado para o qual o pedido foi enviado (por exemplo, help.kusto.windows.net)	Necessário

A tabela seguinte contém os cabeçalhos personalizados comuns utilizados para operações de consulta e gestão. Salvo indicação em contrário, estes cabeçalhos são utilizados apenas para fins de telemetria e não têm qualquer impacto na funcionalidade.

Todos os cabeçalhos são opcionais. Recomendamos que especifique o x-ms-client-request-id cabeçalho personalizado. Em alguns cenários, como cancelar uma consulta em execução, este cabeçalho é necessário porque é utilizado para identificar o pedido.

Cabeçalho personalizado	Description
x-ms-app	O nome (amigável) da aplicação que faz o pedido
x-ms-user	O nome (amigável) do utilizador que faz o pedido
x-ms-user-id	O mesmo que x-ms-user
x-ms-client-request-id	Um identificador exclusivo para o pedido
x-ms-client-version	O identificador de versão (amigável) do cliente que faz o pedido
x-ms-readonly	Se especificado, força o pedido a ser executado no modo só de leitura, impedindo-o de fazer alterações duradouras

Parâmetros do pedido

Os parâmetros seguintes podem ser transmitidos no pedido. São codificados no pedido como parâmetros de consulta ou como parte do corpo, dependendo se GET ou POST são utilizados.

Parâmetro	Description	Obrigatório/Opcional
csl	Texto da consulta ou comando de gestão a executar	Necessário
db	Nome da base de dados no âmbito que é o destino do comando de consulta ou gestão	Opcional para alguns comandos de gestão. Necessário para outros comandos e todas as consultas.
properties	Fornece propriedades de pedido que modificam a forma como o pedido é processado e os respetivos resultados. Para obter mais informações, veja Propriedades do pedido	Opcional

Parâmetros de consulta GET

Quando GET é utilizado, os parâmetros de consulta do pedido especificam os parâmetros do pedido.

Corpo

Quando POST é utilizado, o corpo do pedido é um único documento JSON codificado em UTF-8, com os valores dos parâmetros do pedido.

Exemplos

Este exemplo mostra o pedido HTTP POST de uma consulta.

POST https://help.kusto.windows.net/v2/rest/query HTTP/1.1

Cabeçalhos do pedido

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.windows.net
x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1
x-ms-user-id: EARTH\davidbg
x-ms-app: MyApp

Corpo do pedido

{
  "db":"Samples",
  "csl":"print Test=\"Hello, World!\"",
  "properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"
}

Este exemplo mostra como criar um pedido que envia a consulta acima com curl.

1. Obtenha um token para autenticação.

   Substitua AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDe AAD_APPLICATION_KEY pelos valores relevantes, depois de ter configurado Microsoft Entra autenticação de aplicações

   curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
     -F "grant_type=client_credentials" \
     -F "resource=https://help.kusto.windows.net" \
     -F "client_id=AAD_APPLICATION_ID" \
     -F "client_secret=AAD_APPLICATION_KEY"
   

   Este fragmento de código irá fornecer-lhe o token de portador.

   {
     "token_type": "Bearer",
     "expires_in": "3599",
     "ext_expires_in":"3599", 
     "expires_on":"1578439805",
     "not_before":"1578435905",
     "resource":"https://help.kusto.windows.net",
     "access_token":"eyJ0...uXOQ"
   }
   

2. Utilize o token de portador no seu pedido para o ponto final da consulta.

   curl -d '{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"}}"}"' \
   -H "Accept: application/json" \
   -H "Authorization: Bearer eyJ0...uXOQ" \
   -H "Content-Type: application/json; charset=utf-8" \
   -H "Host: help.kusto.windows.net" \
   -H "x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
   -H "x-ms-user-id: EARTH\davidbg" \
   -H "x-ms-app: MyApp" \
   -X POST https://help.kusto.windows.net/v2/rest/query
   

3. Leia a resposta de acordo com esta especificação.

Definir propriedades do pedido de cliente e parâmetros de consulta

No corpo de exemplo seguinte, a consulta no csl campo declara dois parâmetros com o nome n e d. Os valores desses parâmetros de consulta são especificados no Parameters campo no properties campo no corpo do pedido. O Options campo define as propriedades do pedido de cliente.

Nota

Os parâmetros não de cadeia e não longos têm de ser expressos como literais KQL no formato de cadeia.

{
    "db": "Samples",
    "csl": "declare query_parameters (n:long, d:dynamic); StormEvents | where State in (d) | top n by StartTime asc",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        },
        "Parameters": {
            "n": 10, "d": "dynamic([\"ATLANTIC SOUTH\"])"
        }
    }
}

Para obter mais informações, veja Parâmetros de consulta.