HTTP-Anforderung (Abfrage/Verwaltung)

Anfordern von Verb und Ressource

Aktion	HTTP-Verb	HTTP-Ressource
Abfrage	GET	/v1/rest/query
Abfrage	POST	/v1/rest/query
Abfrage v2	GET	/v2/rest/query
Abfrage v2	POST	/v2/rest/query
Verwaltung	POST	/v1/rest/mgmt

Um beispielsweise einen Verwaltungsbefehl ("verwaltung") an einen Dienstendpunkt zu senden, verwenden Sie die folgende Anforderungszeile:

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

Im Folgenden finden Sie die einzufügenden Anforderungsheader und den Text.

Anforderungsheader

Die folgende Tabelle enthält die allgemeinen Header, die für Abfrage- und Verwaltungsvorgänge verwendet werden.

Standardheader	BESCHREIBUNG	Erforderlich/Optional
Accept	Legen Sie den Wert application/json	Erforderlich
Accept-Encoding	Unterstützte Codierungen sind gzip und deflate	Optional
Authorization	Weitere Informationen finden Sie unter Authentifizierung.	Erforderlich
Connection	Es wird empfohlen, dass Sie Keep-Alive	Optional
Content-Length	Es wird empfohlen, die Länge des Anforderungstexts anzugeben, wenn sie bekannt ist.	Optional
Content-Type	Festlegen auf application/json mit charset=utf-8	Erforderlich
Expect	Kann auf festgelegt werden 100-Continue	Optional
Host	Legen Sie auf den qualifizierten Domänennamen fest, help.kusto.windows.netan den die Anforderung gesendet wurde (z. B. ).	Erforderlich

Die folgende Tabelle enthält die allgemeinen benutzerdefinierten Header, die für Abfrage- und Verwaltungsvorgänge verwendet werden. Sofern nicht anders angegeben, werden diese Header nur zu Telemetriezwecken verwendet und haben keine Auswirkungen auf die Funktionalität.

Alle Header sind optional. Es wird empfohlen, den x-ms-client-request-id benutzerdefinierten Header anzugeben. In einigen Szenarien, z. B. beim Abbrechen einer ausgeführten Abfrage, ist dieser Header erforderlich, da er verwendet wird, um die Anforderung zu identifizieren.

Benutzerdefinierter Header	BESCHREIBUNG
x-ms-app	Der (Anzeige-)Name der Anwendung, die die Anforderung stellt.
x-ms-user	Der (Anzeige-)Name des Benutzers, der die Anforderung stellt
x-ms-user-id	Identisch mit x-ms-user
x-ms-client-request-id	Ein eindeutiger Bezeichner für die Anforderung
x-ms-client-version	Der (benutzerfreundliche) Versionsbezeichner für den Client, der die Anforderung stellt.
x-ms-readonly	Wenn angegeben, erzwingt die Anforderung die Ausführung im schreibgeschützten Modus, sodass keine lang andauernden Änderungen vorgenommen werden.

Anforderungsparameter

Die folgenden Parameter können in der Anforderung übergeben werden. Sie werden in der Anforderung als Abfrageparameter oder als Teil des Texts codiert, je nachdem, ob GET oder POST verwendet wird.

Parameter	BESCHREIBUNG	Erforderlich/Optional
csl	Text der auszuführenden Abfrage oder des Verwaltungsbefehls	Erforderlich
db	Name der Datenbank im Bereich, der das Ziel der Abfrage oder des Verwaltungsbefehls ist	Optional für einige Verwaltungsbefehle. Erforderlich für andere Befehle und alle Abfragen.
properties	Stellt Anforderungseigenschaften bereit, die die Verarbeitung der Anforderung und deren Ergebnisse ändern. Weitere Informationen finden Sie unter Anforderungseigenschaften.	Optional

GET-Abfrageparameter

Wenn GET verwendet wird, geben die Abfrageparameter der Anforderung die Anforderungsparameter an.

Text

Wenn POST verwendet wird, ist der Text der Anforderung ein einzelnes JSON-Dokument, das in UTF-8 codiert ist, mit den Werten der Anforderungsparameter.

Beispiele

Dieses Beispiel zeigt die HTTP POST-Anforderung für eine Abfrage.

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

Anforderungsheader

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

Anforderungstext

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

In diesem Beispiel wird gezeigt, wie Sie mithilfe von curl eine Anforderung erstellen, die die obige Abfrage sendet.

1. Rufen Sie ein Token für die Authentifizierung ab.

   Ersetzen Sie AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDund AAD_APPLICATION_KEY durch die relevanten Werte, nachdem Sie Microsoft Entra Anwendungsauthentifizierung eingerichtet haben.

   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"
   

   In diesem Codeausschnitt erhalten Sie das Bearertoken.

   {
     "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. Verwenden Sie das Bearertoken in Ihrer Anforderung an den Abfrageendpunkt.

   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. Lesen Sie die Antwort gemäß dieser Spezifikation.

Festlegen von Clientanforderungseigenschaften und Abfrageparametern

Im folgenden Beispieltext deklariert die Abfrage im csl Feld zwei Parameter mit dem Namen n und d. Die Werte für diese Abfrageparameter werden im Parameters Feld unter dem properties Feld im Anforderungstext angegeben. Das Options Feld definiert Clientanforderungseigenschaften.

Hinweis

Nicht-Zeichenfolgen- und nicht lange Parameter müssen als KQL-Literale im Zeichenfolgenformat ausgedrückt werden.

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

Weitere Informationen finden Sie unter Abfrageparameter.