Condividi tramite

Richiesta HTTP di query/gestione

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

Verbo richiesta e risorsa

Azione Verbo HTTP Risorsa HTTP
Query GET /v1/rest/query
Query POST /v1/rest/query
Eseguire query v2 GET /v2/rest/query
Eseguire 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

Per informazioni su cosa includere, vedere Intestazioni della richiesta e Corpo .

Intestazioni delle richieste

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

Intestazione standard Descrizione Obbligatorio/facoltativo
Accept Il supporto digita il client. Impostare su application/json. Richiesto
Accept-Encoding Codifiche di contenuto supportate. Le codifiche supportate sono gzip e deflate. Facoltativo
Authorization Credenziali di autenticazione. Per altre informazioni, vedere Autenticazione. Richiesto
Connection Indica se la connessione rimane aperta dopo l'operazione. È consigliabile impostare su Connection Keep-Alive. Facoltativo
Content-Length Dimensioni del corpo della richiesta. Specificare la lunghezza del corpo della richiesta quando nota. Facoltativo
Content-Type Tipo di supporto del corpo della richiesta. Impostare su application/json con charset=utf-8. Richiesto
Expect Risposta prevista dal server. Può essere impostato su 100-Continue. Facoltativo
Host Nome di dominio completo a cui è stata inviata la richiesta. Ad esempio: help.kusto.windows.net. Richiesto

La tabella seguente contiene le intestazioni personalizzate comuni usate per le operazioni di query e gestione. Se non specificato, queste intestazioni vengono usate solo per scopi di telemetria e non influiscono sulle funzionalità.

Tutte le intestazioni sono facoltative. È tuttavia consigliabile specificare l'intestazione x-ms-client-request-id personalizzata. In alcuni scenari, ad esempio l'annullamento di una query in esecuzione, x-ms-client-request-id è necessario perché viene usato 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 Lo stesso nome descrittivo di x-ms-user.
x-ms-client-request-id Identificatore univoco per la richiesta.
x-ms-client-version Identificatore descrittivo della versione per il client che effettua la richiesta.
x-ms-readonly Se specificato, forza l'esecuzione della richiesta in modalità di sola lettura che impedisce alla richiesta di modificare i dati.

Parametri della richiesta

Nella richiesta è possibile passare i parametri seguenti. 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 di query o gestione da eseguire. Richiesto
db Nome del database di destinazione del comando di query o gestione. Facoltativo per alcuni comandi di gestione.
Obbligatorio per tutte le query e tutti gli altri comandi.
properties Proprietà della richiesta che modificano il modo in cui viene elaborata la richiesta e i relativi risultati. Per altre informazioni, vedere Proprietà della richiesta. Facoltativo

Parametri di query GET

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

Testo

Quando si usa una richiesta POST, il corpo della richiesta contiene un singolo documento JSON con codifica UTF-8, che include i valori dei parametri della richiesta.

Esempi

Nell'esempio seguente viene illustrata la richiesta HTTP POST per una query.

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

Intestazioni delle richieste

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

Nell'esempio seguente 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 l'autenticazione dell'applicazione 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"

    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 ai codici di stato della risposta.

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

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

Nota

I parametri non stringa e non long 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 Proprietà della richiesta supportate.

Comando Invia mostra criteri di memorizzazione nella cache del database

Nell'esempio seguente viene inviata una richiesta per visualizzare i criteri di memorizzazione nella cache del Samples database.


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