Udostępnij za pośrednictwem

Żądanie HTTP zapytania/zarządzania

  • Artykuł

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Żądanie zlecenia i zasobu

Akcja Czasownik HTTP Zasób HTTP
Query GET /v1/rest/query
Query 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

Zobacz Nagłówki żądań i treść , aby dowiedzieć się, co należy uwzględnić.

Nagłówki żądań

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

Nagłówek standardowy opis Wymagane/opcjonalnie
Accept Nośniki są odbierane przez klienta. Ustaw wartość application/json. Wymagania
Accept-Encoding Obsługiwane kodowanie zawartości. Obsługiwane kodowanie to gzip i deflate. Opcjonalnie
Authorization Poświadczenia uwierzytelniania. Aby uzyskać więcej informacji, zobacz uwierzytelnianie. Wymagania
Connection Czy połączenie pozostaje otwarte po operacji. Zaleceniem jest ustawienie wartości Connection Keep-Alive. Opcjonalnie
Content-Length Rozmiar treści żądania. Określ długość treści żądania, jeśli jest znana. Opcjonalnie
Content-Type Typ nośnika treści żądania. Ustaw wartość na application/json z charset=utf-8. Wymagania
Expect Oczekiwana odpowiedź z serwera. Można go ustawić na 100-Continue. Opcjonalnie
Host Kwalifikowana nazwa domeny, do którego wysłano żądanie. Na przykład help.kusto.windows.net. Wymagania

Poniższa tabela zawiera typowe nagłówki niestandardowe używane na potrzeby operacji zapytań i zarządzania. O ile nie określono, te nagłówki są używane tylko do celów telemetrycznych i nie mają wpływu na funkcjonalność.

Wszystkie nagłówki są opcjonalne. Zalecamy jednak określenie nagłówka niestandardowego x-ms-client-request-id . W niektórych scenariuszach, takich jak anulowanie uruchomionego zapytania, jest wymagane, x-ms-client-request-id ponieważ jest ono używane 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 Taka sama przyjazna nazwa jak x-ms-user.
x-ms-client-request-id Unikatowy identyfikator żądania.
x-ms-client-version Przyjazny identyfikator wersji dla klienta wysyłającego żądanie.
x-ms-readonly Jeśli zostanie określony, wymusza uruchomienie żądania w trybie tylko do odczytu, co uniemożliwia zmianę danych przez żądanie.

Parametry żądania

Następujące parametry można przekazać w żądaniu. Są one kodowane 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/opcjonalnie
csl Tekst polecenia zapytania lub zarządzania do wykonania. Wymagania
db Nazwa bazy danych, która jest elementem docelowym polecenia zapytania lub zarządzania. Opcjonalnie w przypadku niektórych poleceń zarządzania.
Wymagane dla wszystkich zapytań i wszystkich innych poleceń.
properties Zażądaj właściwości, które modyfikują sposób przetwarzania żądania i jego wyników. Aby uzyskać więcej informacji, zobacz Request properties (Właściwości żądania). Opcjonalnie

Parametry zapytania GET

Gdy jest używane żądanie GET, parametry zapytania określają parametry żądania.

Treść

Gdy jest używane żądanie POST, treść żądania zawiera pojedynczy dokument JSON zakodowany w formacie UTF-8, który zawiera wartości parametrów żądania.

Przykłady

Poniższy przykład przedstawia żą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 poniższym przykładzie pokazano, jak utworzyć żądanie, które wysyła poprzednie 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 zawiera 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 kodami stanu odpowiedzi.

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

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

Uwaga

Parametry nieciągalne i nie 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 Obsługiwane właściwości żądania.

Wyślij polecenie zasad buforowania bazy danych

Poniższy przykład wysyła żądanie wyświetlania Samples zasad buforowania bazy danych.


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