Richiesta HTTP di query/gestione

Richiedere verbo e risorsa

Azione	Verbo HTTP	Risorsa HTTP
Query	GET	/v1/rest/query
Query	POST	/v1/rest/query
Query v2	GET	/v2/rest/query
Query v2	POST	/v2/rest/query
Gestione	POST	/v1/rest/mgmt

Ad esempio, per inviare un comando di gestione ("gestione") a un endpoint di servizio, usare la riga di richiesta seguente:

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

Vedere di seguito per le intestazioni della richiesta e il corpo da includere.

Intestazioni della richiesta

La tabella seguente contiene le intestazioni comuni usate per le operazioni di query e gestione.

Intestazione standard	Descrizione	Obbligatorio/facoltativo
Accept	Impostare su application/json	Necessario
Accept-Encoding	Le codifiche supportate sono gzip e deflate	Facoltativo
Authorization	Vedere l'autenticazione	Necessario
Connection	È consigliabile abilitare Keep-Alive	Facoltativo
Content-Length	È consigliabile specificare la lunghezza del corpo della richiesta quando nota	Facoltativo
Content-Type	Impostare su application/json con charset=utf-8	Necessario
Expect	Può essere impostato su 100-Continue	Facoltativo
Host	Impostare sul nome di dominio qualificato a cui è stata inviata la richiesta (ad esempio, help.kusto.windows.net)	Necessario

La tabella seguente contiene le intestazioni personalizzate comuni usate per le operazioni di query e gestione. A meno che non sia indicato diversamente, queste intestazioni vengono usate solo per scopi di telemetria e non hanno alcun impatto sulla funzionalità.

Tutte le intestazioni sono facoltative. È consigliabile specificare l'intestazione x-ms-client-request-id personalizzata. In alcuni scenari, ad esempio l'annullamento di una query in esecuzione, questa intestazione è necessaria perché viene usata per identificare la richiesta.

Intestazione personalizzata	Descrizione
x-ms-app	Nome (descrittivo) dell'applicazione che effettua la richiesta
x-ms-user	Nome (descrittivo) dell'utente che effettua la richiesta
x-ms-user-id	Uguale a x-ms-user
x-ms-client-request-id	Identificatore univoco per la richiesta
x-ms-client-version	Identificatore di versione (descrittivo) per il client che effettua la richiesta
x-ms-readonly	Se specificato, forza l'esecuzione della richiesta in modalità di sola lettura, impedendogli di apportare modifiche di lunga durata

Parametri della richiesta

I parametri seguenti possono essere passati nella richiesta. Vengono codificati nella richiesta come parametri di query o come parte del corpo, a seconda che venga usato GET o POST.

Parametro	Descrizione	Obbligatorio/facoltativo
csl	Testo del comando query o gestione da eseguire	Necessario
db	Nome del database nell'ambito di destinazione del comando query o gestione	Facoltativo per alcuni comandi di gestione. Obbligatorio per altri comandi e tutte le query.
properties	Fornisce proprietà della richiesta che modificano il modo in cui la richiesta viene elaborata e i relativi risultati. Per altre informazioni, vedere Proprietà della richiesta	Facoltativo

Parametri di query GET

Quando viene usato GET, i parametri di query della richiesta specificano i parametri della richiesta.

Corpo

Quando viene usato POST, il corpo della richiesta è un singolo documento JSON codificato in UTF-8, con i valori dei parametri della richiesta.

Esempio

Questo esempio mostra la richiesta HTTP POST per una query.

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

Intestazioni della richiesta

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

Testo della richiesta

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

In questo esempio viene illustrato come creare una richiesta che invia la query precedente usando curl.

1. Ottenere un token per l'autenticazione.

   Sostituire AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDe AAD_APPLICATION_KEY con i valori pertinenti, dopo aver configurato Microsoft Entra'autenticazione dell'applicazione

   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"
   

   Questo frammento di codice fornisce il token di connessione.

   {
     "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. Usare il token di connessione nella richiesta all'endpoint di query.

   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. Leggere la risposta in base a questa specifica.

Impostare le proprietà della richiesta client e i parametri di query

Nel corpo dell'esempio csl seguente la query nel campo dichiara due parametri denominati n e d. I valori per tali parametri di query vengono specificati all'interno del Parameters campo nel campo properties nel corpo della richiesta. Il Options campo definisce le proprietà della richiesta client.

Nota

I parametri non stringa e non lunghi devono essere espressi come valori letterali KQL in formato stringa.

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

Per altre informazioni, vedere Parametri di query.