Żądanie HTTP zapytania/zarządzania

Żądanie zlecenia i zasobu

Akcja	Czasownik HTTP	Zasób HTTP
Zapytanie	GET	/v1/rest/query
Zapytanie	POST	/v1/rest/query
Zapytanie w wersji 2	GET	/v2/rest/query
Zapytanie w wersji 2	POST	/v2/rest/query
Zarządzanie	POST	/v1/rest/mgmt

Aby na przykład wysłać polecenie zarządzania ("management") do punktu końcowego usługi, użyj następującego wiersza żądania:

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

Poniżej przedstawiono nagłówki żądań i treść do uwzględnienia.

Nagłówki żądań

Poniższa tabela zawiera typowe nagłówki używane do wykonywania zapytań i operacji zarządzania.

Nagłówek standardowy	Opis	Wymagane/Opcjonalne
Accept	Ustaw wartość application/json	Wymagane
Accept-Encoding	Obsługiwane kodowanie to gzip i deflate	Opcjonalne
Authorization	Zobacz uwierzytelnianie	Wymagane
Connection	Zalecamy włączenie Keep-Alive	Opcjonalne
Content-Length	Zalecamy określenie długości treści żądania, gdy jest znana	Opcjonalne
Content-Type	Ustaw wartość na application/json z charset=utf-8	Wymagane
Expect	Można ustawić na 100-Continue	Opcjonalne
Host	Ustaw kwalifikowaną nazwę domeny, do którego wysłano żądanie (na przykład help.kusto.windows.net)	Wymagane

Poniższa tabela zawiera typowe nagłówki niestandardowe używane do wykonywania zapytań i operacji zarządzania. Jeśli nie wskazano inaczej, nagłówki te są używane tylko do celów telemetrycznych i nie mają wpływu na funkcjonalność.

Wszystkie nagłówki są opcjonalne. Zalecamy określenie nagłówka niestandardowego x-ms-client-request-id . W niektórych scenariuszach, takich jak anulowanie uruchomionego zapytania, ten nagłówek jest wymagany, ponieważ jest używany do identyfikowania żądania.

Nagłówek niestandardowy	Opis
x-ms-app	(przyjazna) nazwa aplikacji wysyłającej żądanie
x-ms-user	(przyjazna) nazwa użytkownika wysyłającego żądanie
x-ms-user-id	Tak samo jak x-ms-user
x-ms-client-request-id	Unikatowy identyfikator żądania
x-ms-client-version	Identyfikator wersji (przyjazny) dla klienta wysyłającego żądanie
x-ms-readonly	W przypadku określenia wymusza uruchomienie żądania w trybie tylko do odczytu, co uniemożliwia wprowadzanie długotrwałych zmian

Parametry żądania

Następujące parametry można przekazać w żądaniu. Są one zakodowane w żądaniu jako parametry zapytania lub w ramach treści, w zależności od tego, czy jest używane polecenie GET, czy POST.

Parametr	Opis	Wymagane/Opcjonalne
csl	Tekst zapytania lub polecenia zarządzania do wykonania	Wymagane
db	Nazwa bazy danych w zakresie, który jest obiektem docelowym zapytania lub polecenia zarządzania	Opcjonalnie dla niektórych poleceń zarządzania. Wymagane dla innych poleceń i wszystkich zapytań.
properties	Udostępnia właściwości żądania, które modyfikują sposób przetwarzania żądania i jego wyników. Aby uzyskać więcej informacji, zobacz Request properties (Właściwości żądania)	Opcjonalne

Parametry zapytania GET

W przypadku użycia polecenia GET parametry zapytania żądania określają parametry żądania.

Treść

Gdy jest używana funkcja POST, treść żądania jest pojedynczym dokumentem JSON zakodowanym w formacie UTF-8 z wartościami parametrów żądania.

Przykłady

W tym przykładzie przedstawiono żądanie HTTP POST dla zapytania.

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

Nagłówki żądań

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

Treść żądania

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

W tym przykładzie pokazano, jak utworzyć żądanie, które wysyła powyższe zapytanie przy użyciu narzędzia curl.

1. Uzyskiwanie tokenu na potrzeby uwierzytelniania.

   Zastąp AAD_TENANT_NAME_OR_IDwartości , AAD_APPLICATION_IDi AAD_APPLICATION_KEY odpowiednimi wartościami po skonfigurowaniu uwierzytelniania aplikacji 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"
   

   Ten fragment kodu udostępnia token elementu nośnego.

   {
     "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. Użyj tokenu elementu nośnego w żądaniu do punktu końcowego zapytania.

   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. Przeczytaj odpowiedź zgodnie z tą specyfikacją.

Ustawianie właściwości żądania klienta i parametrów zapytania

W poniższej przykładowej csl treści zapytanie w polu deklaruje dwa parametry o nazwie n i d. Wartości tych parametrów zapytania są określone w Parameters polu w properties polu w polu w treści żądania. Pole Options definiuje właściwości żądania klienta.

Uwaga

Parametry inne niż ciągi i parametry inne niż długie muszą być wyrażone jako literały KQL w formacie ciągu.

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

Aby uzyskać więcej informacji, zobacz Parametry zapytania.