Požadavky HTTP pro dotazování nebo správu

Žádost o příkaz a prostředek

Akce	Příkaz HTTP	Prostředek HTTP
Dotaz	GET	/v1/rest/query
Dotaz	POST	/v1/rest/query
Dotaz v2	GET	/v2/rest/query
Dotaz v2	POST	/v2/rest/query
Správa	POST	/v1/rest/mgmt

Pokud například chcete odeslat příkaz pro správu ("správa") do koncového bodu služby, použijte následující řádek žádosti:

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

Hlavičky a text požadavku, které se mají zahrnout, najdete níže.

Hlavičky požadavku

Následující tabulka obsahuje společné hlavičky používané pro operace dotazů a správy.

Standardní záhlaví	Description	Požadováno/volitelné
Accept	Nastavit na application/json	Vyžadováno
Accept-Encoding	Podporovaná kódování jsou gzip a deflate	Volitelné
Authorization	Viz ověřování.	Vyžadováno
Connection	Doporučujeme povolit Keep-Alive	Volitelné
Content-Length	Doporučujeme zadat délku textu požadavku, pokud je známa.	Volitelné
Content-Type	Nastavit na pomocí application/jsoncharset=utf-8	Vyžadováno
Expect	Lze nastavit na 100-Continue	Volitelné
Host	Nastavte na kvalifikovaný název domény, na který byl požadavek odeslán (například help.kusto.windows.net).	Vyžadováno

Následující tabulka obsahuje společné vlastní hlavičky používané pro operace dotazů a správy. Pokud není uvedeno jinak, používají se tyto hlavičky pouze pro účely telemetrie a nemají žádný vliv na funkčnost.

Všechna záhlaví jsou volitelná. Doporučujeme zadat vlastní hlavičku x-ms-client-request-id . V některých scénářích, jako je zrušení spuštěného dotazu, se tato hlavička vyžaduje, protože se používá k identifikaci požadavku.

Vlastní hlavička	Description
x-ms-app	(popisný) název aplikace, která žádost vytváří
x-ms-user	(popisné) jméno uživatele, který žádost vytváří
x-ms-user-id	Stejné jako x-ms-user
x-ms-client-request-id	Jedinečný identifikátor požadavku
x-ms-client-version	Identifikátor (popisné) verze klienta, který žádost vytváří
x-ms-readonly	Pokud je tato možnost zadána, vynutí spuštění požadavku v režimu jen pro čtení, aby se zabránilo provádění dlouhotrvajících změn.

Parametry požadavku

V požadavku je možné předat následující parametry. Kódují se v požadavku jako parametry dotazu nebo jako součást textu v závislosti na tom, jestli se používá get nebo POST.

Parametr	Popis	Požadováno/volitelné
csl	Text dotazu nebo příkazu pro správu, který se má spustit	Vyžadováno
db	Název databáze v oboru, který je cílem dotazu nebo příkazu pro správu	Volitelné pro některé příkazy pro správu. Vyžaduje se pro ostatní příkazy a všechny dotazy.
properties	Poskytuje vlastnosti požadavku, které upravují způsob zpracování požadavku a jeho výsledky. Další informace najdete v tématu Vlastnosti požadavku.	Volitelné

Parametry dotazu GET

Při použití příkazu GET parametry dotazu požadavku určují parametry požadavku.

Text

Při použití post je tělem požadavku jeden dokument JSON zakódovaný v UTF-8 s hodnotami parametrů požadavku.

Příklady

Tento příklad ukazuje požadavek HTTP POST pro dotaz.

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

Hlavičky požadavku

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

Text požadavku

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

Tento příklad ukazuje, jak pomocí příkazu curl vytvořit požadavek, který odešle výše uvedený dotaz.

1. Získejte token pro ověřování.

   AAD_APPLICATION_IDPo nastavení ověřování Microsoft Entra aplikace nahraďte AAD_TENANT_NAME_OR_ID, a AAD_APPLICATION_KEY příslušnými hodnotami.

   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"
   

   Tento fragment kódu vám poskytne nosný token.

   {
     "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. Použijte nosný token v požadavku na koncový bod dotazu.

   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. Přečtěte si odpověď podle této specifikace.

Nastavení vlastností požadavku klienta a parametrů dotazu

V následujícím příkladu textu dotaz v csl poli deklaruje dva parametry s názvem n a d. Hodnoty pro tyto parametry dotazu se zadají v Parameters poli pod polem properties v textu požadavku. Pole Options definuje vlastnosti požadavku klienta.

Poznámka

Neřetězcové a netlouhlé parametry musí být vyjádřeny jako literály KQL ve formátu řetězce.

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

Další informace najdete v tématu Parametry dotazu.