Sdílet prostřednictvím

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

  • Článek

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

Žá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 požadavku:

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

Informace o zahrnutí najdete v hlavičce požadavku a textu .

Záhlaví žádosti

Následující tabulka obsahuje běžné hlavičky používané pro operace dotazování a správy.

Standardní hlavička Popis Povinné/volitelné
Accept Typy médií, které klient obdrží. Nastavte na application/json. Požaduje se
Accept-Encoding Podporované kódování obsahu. Podporované kódování jsou gzip a deflate. Volitelné
Authorization Přihlašovací údaje pro ověřování. Další informace najdete v tématu ověřování. Požaduje se
Connection Zda připojení zůstane otevřené po operaci. Doporučení je nastavit Connection na Keep-Alivehodnotu . Volitelné
Content-Length Velikost textu požadavku. Zadejte délku textu požadavku, pokud je známa. Volitelné
Content-Type Typ média textu požadavku. Nastavte na application/json hodnotu s parametrem charset=utf-8. Požaduje se
Expect Očekávaná odpověď ze serveru. Může být nastavena na 100-Continuehodnotu . Volitelné
Host Kvalifikovaný název domény, na který byl požadavek odeslán. Například help.kusto.windows.net. Požaduje se

Následující tabulka obsahuje běžné vlastní hlavičky používané pro operace dotazování a správy. Pokud není uvedeno, tyto hlavičky se používají jenom pro účely telemetrie a nemají vliv na funkčnost.

Všechna záhlaví jsou volitelná. Doporučujeme ale 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 vyžaduje, x-ms-client-request-id protože se používá k identifikaci požadavku.

Vlastní hlavička Popis
x-ms-app Popisný název aplikace, která žádost provádí.
x-ms-user Popisný název uživatele, který žádost provádí.
x-ms-user-id Stejný popisný název jako x-ms-user.
x-ms-client-request-id Jedinečný identifikátor požadavku.
x-ms-client-version Popisný identifikátor verze pro klienta, který požadavek provádí.
x-ms-readonly Pokud je zadáno, vynutí, aby se požadavek spustil v režimu jen pro čtení, který brání požadavku ve změně dat.

Parametry požadavku

V požadavku lze předat následující parametry. Kódují se v požadavku jako parametry dotazu nebo jako součást těla v závislosti na tom, jestli se používá GET nebo POST.

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

Parametry dotazu GET

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

Text

Při použití požadavku POST obsahuje text požadavku jeden dokument JSON s kódováním UTF-8, který obsahuje hodnoty parametrů požadavku.

Příklady

Následující příklad ukazuje požadavek HTTP POST pro dotaz.

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

Záhlaví žádosti

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\"}"
}

Následující příklad ukazuje, jak vytvořit požadavek, který odešle předchozí dotaz pomocí curl.

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

    Nahraďte AAD_TENANT_NAME_OR_IDa AAD_APPLICATION_KEY AAD_APPLICATION_IDza odpovídající hodnoty po nastavení ověřování aplikace 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"

    Tento fragment kódu poskytuje 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 stavových kódů odpovědí.

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

V následujícím příkladu textu požadavku dotaz v csl poli deklaruje dva parametry pojmenované n a d. Hodnoty těchto parametrů dotazu jsou zadány v Parameters poli pod properties polem v textu požadavku. Pole Options definuje vlastnosti požadavku klienta.

Poznámka:

Jiné než řetězcové a jiné než dlouhé 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 naleznete v tématu Podporované vlastnosti požadavku.

Příkaz Odeslat zásadu ukládání do mezipaměti databáze

Následující příklad odešle požadavek, který zobrazí Samples zásady ukládání databáze do mezipaměti.


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