Partilhar via

Solicitação HTTP da consulta/gerenciamento

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

Verbo de solicitação e recurso

Ação Verbo HTTP Recurso HTTP
Consulta GET /v1/rest/query
Consulta POSTAR /v1/rest/query
Consulta v2 GET /v2/rest/query
Consulta v2 POSTAR /v2/rest/query
Gerenciamento POSTAR /v1/rest/mgmt

Por exemplo, para enviar um comando de gerenciamento ("gerenciamento") para um ponto de extremidade de serviço, use a seguinte linha de solicitação:

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

Consulte Cabeçalhos de solicitação e Corpo para saber o que incluir.

Cabeçalhos da solicitação

A tabela a seguir contém os cabeçalhos comuns usados para operações de consulta e gerenciamento.

Cabeçalho padrão Descrição Obrigatório/Opcional
Accept Os tipos de mídia que o cliente recebe. Defina como application/json. Obrigatório
Accept-Encoding As codificações de conteúdo com suporte. As codificações suportadas são gzip e deflate. Opcional
Authorization As credenciais de autenticação. Para obter mais informações, consulte autenticação. Obrigatório
Connection Se a conexão permanece aberta após a operação. A recomendação é definir Connection como Keep-Alive. Opcional
Content-Length O tamanho do corpo da solicitação. Especifique o comprimento do corpo da solicitação quando conhecido. Opcional
Content-Type O tipo de mídia do corpo da solicitação. Defina como application/json charset=utf-8. Obrigatório
Expect A resposta esperada do servidor. Ele pode ser definido como 100-Continue. Opcional
Host O nome de domínio qualificado para o qual a solicitação foi enviada. Por exemplo, help.kusto.windows.net. Obrigatório

A tabela a seguir contém os cabeçalhos personalizados comuns usados para operações de consulta e gerenciamento. A menos que indicado, esses cabeçalhos são usados apenas para fins de telemetria e não afetam a funcionalidade.

Todos os cabeçalhos são opcionais. No entanto, recomendamos especificar o x-ms-client-request-id cabeçalho personalizado. Em alguns cenários, como cancelar uma consulta em execução, é necessário, x-ms-client-request-id pois é usado para identificar a solicitação.

Cabeçalho personalizado Descrição
x-ms-app O nome amigável do aplicativo que está fazendo a solicitação.
x-ms-user O nome amigável do usuário que está fazendo a solicitação.
x-ms-user-id O mesmo nome amigável que x-ms-user.
x-ms-client-request-id Um identificador exclusivo para a solicitação.
x-ms-client-version O identificador de versão amigável para o cliente que está fazendo a solicitação.
x-ms-readonly Se especificado, ele força a solicitação a ser executada no modo somente leitura, o que impede que a solicitação altere os dados.

Parâmetros da solicitação

Os parâmetros a seguir podem ser passados na solicitação. Eles são codificados na solicitação como parâmetros de consulta ou como parte do corpo, dependendo se GET ou POST é usado.

Parâmetro Descrição Obrigatório/Opcional
csl O texto da consulta ou do comando de gerenciamento a ser executado. Obrigatório
db O nome do banco de dados que é o destino do comando de consulta ou gerenciamento. Opcional para alguns comandos de gerenciamento.
Necessário para todas as consultas e todos os outros comandos.
properties Propriedades de solicitação que modificam como a solicitação é processada e seus resultados. Para obter mais informações, consulte Propriedades da solicitação. Opcional

Parâmetros de consulta GET

Quando uma solicitação GET é usada, os parâmetros de consulta especificam os parâmetros de solicitação.

Corpo

Quando uma solicitação POST é usada, o corpo da solicitação contém um único documento JSON codificado em UTF-8, que inclui os valores dos parâmetros de solicitação.

Exemplos

O exemplo a seguir mostra a solicitação HTTP POST para uma consulta.

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

Cabeçalhos da solicitação

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 da solicitação

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

O exemplo a seguir mostra como criar uma solicitação que envia a consulta anterior, usando curl.

  1. Obtenha um token para autenticação.

    Substitua AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDe pelos AAD_APPLICATION_KEY valores relevantes, depois de configurar a autenticação do aplicativo Microsoft Entra.

    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 snippet de código fornece 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. Use o token de portador em sua solicitação para o ponto de extremidade de 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 os códigos de status da resposta.

Definir propriedades de solicitação do cliente e parâmetros de consulta

No exemplo de corpo da solicitação a seguir, a csl consulta no campo declara dois parâmetros chamados n e d. Os valores para esses parâmetros de consulta são especificados no Parameters campo abaixo do properties campo no corpo da solicitação. O Options campo define as propriedades da solicitação do cliente.

Observação

Os parâmetros não string e não long devem ser expressos como literais KQL no formato string.

{
    "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, consulte Propriedades de solicitação com suporte.

Enviar comando show database caching policy

O exemplo a seguir envia uma solicitação para mostrar a política de cache do Samples banco de dados.


{
    "db": "Samples",
    "csl": ".show database Samples policy caching",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        }
    }
}