Share via

HTTP-запрос для запроса или управления

  • Статья

Команда запроса и ресурс

Действие HTTP-команда Ресурс HTTP
Запрос GET /v1/rest/query
Запрос POST /v1/rest/query
Запрос версии 2 GET /v2/rest/query
Запрос версии 2 POST /v2/rest/query
Управление POST /v1/rest/mgmt

Например, чтобы отправить команду управления ("управление") в конечную точку службы, используйте следующую строку запроса:

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

Заголовки и текст запроса для включения см. ниже.

Заголовки запросов

В следующей таблице приведены общие заголовки, используемые для операций запроса и управления.

Стандартный заголовок Описание Обязательный/необязательный
Accept Установите значение application/json Обязательно
Accept-Encoding Поддерживаемые кодировки: gzip и deflate Необязательно
Authorization См . проверку подлинности. Обязательно
Connection Рекомендуется включить Keep-Alive Необязательно
Content-Length Рекомендуется указывать длину текста запроса, если известно. Необязательно
Content-Type Задайте значение с помощью application/jsoncharset=utf-8 Обязательно
Expect Может быть задано значение 100-Continue Необязательно
Host Задайте полное доменное имя, в которое был отправлен запрос (например, help.kusto.windows.net). Обязательно

В следующей таблице приведены общие настраиваемые заголовки, используемые для операций запроса и управления. Если не указано иное, эти заголовки используются только для телеметрии и не влияют на функциональные возможности.

Все заголовки являются необязательными. Рекомендуется указать x-ms-client-request-id пользовательский заголовок. В некоторых сценариях, таких как отмена выполняющегося запроса, этот заголовок является обязательным, так как он используется для идентификации запроса.

Настраиваемый заголовок Описание
x-ms-app (понятное) имя приложения, выполняющего запрос
x-ms-user (понятное) имя пользователя, выполняющего запрос
x-ms-user-id То же, что x-ms-user
x-ms-client-request-id Уникальный идентификатор запроса
x-ms-client-version (понятный) идентификатор версии для клиента, выполняющего запрос.
x-ms-readonly Если этот параметр указан, запрос выполняется в режиме только для чтения, предотвращая длительные изменения.

Параметры запроса

В запросе можно передать следующие параметры. Они кодируются в запросе как параметры запроса или как часть текста в зависимости от того, используется ли GET или POST.

Параметр Описание Обязательный/необязательный
csl Текст запроса или команды управления для выполнения Обязательно
db Имя базы данных в область, которая является целевым объектом запроса или команды управления Необязательный параметр для некоторых команд управления.
Требуется для других команд и всех запросов.
properties Предоставляет свойства запроса, которые изменяют способ обработки запроса и его результаты. Дополнительные сведения см. в разделе Свойства запроса. Необязательно

Параметры запроса GET

Если используется GET, параметры запроса указываются в параметрах запроса.

Текст

При использовании POST текст запроса представляет собой один документ JSON, закодированный в UTF-8, со значениями параметров запроса.

Примеры

В этом примере показан HTTP-запрос POST для запроса.

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

Заголовки запросов

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

Текст запроса

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

В этом примере показано, как создать запрос, который отправляет приведенный выше запрос с помощью curl.

  1. Получите маркер для проверки подлинности.

    Замените AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDи AAD_APPLICATION_KEY соответствующими значениями после настройки проверки подлинности 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"

    Этот фрагмент кода предоставит маркер носителя.

    {
  "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. Используйте маркер носителя в запросе к конечной точке запроса.

    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. Прочтите ответ в соответствии с этой спецификацией.

Настройка свойств и параметров запроса клиента

В следующем примере текста запрос в csl поле объявляет два параметра с именами n и d. Значения этих параметров запроса указываются в Parameters поле под полем properties в тексте запроса. Поле Options определяет свойства запроса клиента.

Примечание

Нестроковые и нестроковые параметры должны быть выражены в виде KQL-литералы в строковом формате.

{
    "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\"])"
        }
    }
}

Дополнительные сведения см. в разделе Параметры запроса.