Richiesta HTTP di query/gestioneQuery/management HTTP request

Verbo della richiesta e risorsaRequest verb and resource

AzioneAction Verbo HTTPHTTP verb Risorsa HTTPHTTP resource
QueryQuery GETGET /v1/rest/query
QueryQuery POSTPOST /v1/rest/query
Query V2Query v2 GETGET /v2/rest/query
Query V2Query v2 POSTPOST /v2/rest/query
GestioneManagement POSTPOST /v1/rest/mgmt

Per inviare, ad esempio, un comando di controllo ("gestione") a un endpoint del servizio, usare la seguente riga di richiesta:For example, to send a control command ("management") to a service endpoint, use the following request line:

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

Per includere le intestazioni e il corpo della richiesta, vedere di seguito.See below for the request headers and body to include.

Intestazioni della richiestaRequest headers

Nella tabella seguente sono contenute le intestazioni comuni utilizzate per le operazioni di gestione e query.The following table contains the common headers used for query and management operations.

Intestazione standardStandard header DescriptionDescription Obbligatorio/facoltativoRequired/Optional
Accept Impostare su application/jsonSet to application/json ObbligatoriaRequired
Accept-Encoding Le codifiche supportate sono gzip edeflateSupported encodings are gzip and deflate FacoltativoOptional
Authorization Vedere autenticazioneSee authentication ObbligatoriaRequired
Connection Si consiglia di abilitareKeep-AliveWe recommend that you enable Keep-Alive FacoltativoOptional
Content-Length È consigliabile specificare la lunghezza del corpo della richiesta quando notoWe recommend that you specify the request body length when known FacoltativoOptional
Content-Type Imposta su application/json concharset=utf-8Set to application/json with charset=utf-8 ObbligatoriaRequired
Expect Può essere impostato su100-ContinueCan be set to 100-Continue FacoltativoOptional
Host Impostare sul nome di dominio completo a cui è stata inviata la richiesta (ad esempio, help.kusto.windows.net )Set to the qualified domain name that the request was sent to (for example, help.kusto.windows.net) ObbligatoriaRequired

La tabella seguente contiene le intestazioni personalizzate comuni utilizzate per le operazioni di gestione e query.The following table contains the common custom headers used for query and management operations. Se non diversamente specificato, queste intestazioni vengono usate solo a scopo di telemetria e non hanno alcun effetto sulla funzionalità.Unless otherwise indicated, these headers are used for telemetry purposes only, and have no functionality impact.

Tutte le intestazioni sono facoltative.All headers are optional. Si consiglia di specificare l' x-ms-client-request-id intestazione personalizzata.We recommend that you specify the x-ms-client-request-id custom header. In alcuni scenari, ad esempio l'annullamento di una query in esecuzione, questa intestazione è necessaria perché viene usata per identificare la richiesta.In some scenarios, such as canceling a running query, this header is required because it's used to identify the request.

Intestazione personalizzataCustom header DescriptionDescription
x-ms-app Nome (descrittivo) dell'applicazione che effettua la richiesta.The (friendly) name of the application making the request
x-ms-user Nome (descrittivo) dell'utente che effettua la richiestaThe (friendly) name of the user making the request
x-ms-user-id Uguale a x-ms-userSame as x-ms-user
x-ms-client-request-id Identificatore univoco per la richiesta.A unique identifier for the request
x-ms-client-version Identificatore di versione (descrittivo) per il client che effettua la richiestaThe (friendly) version identifier for the client making the request
x-ms-readonly Se specificato, impone la richiesta di esecuzione in modalità di sola lettura, impedendone la creazione di modifiche di lunga durataIf specified, forces the request to run in read-only mode, preventing it from making long-lasting changes

Parametri della richiestaRequest parameters

È possibile passare i parametri seguenti nella richiesta.The following parameters can be passed in the request. Sono codificati nella richiesta come parametri di query o come parte del corpo, a seconda che venga usato GET o POST.They're encoded in the request as query parameters or as part of the body, depending on whether GET or POST is used.

ParametroParameter DescrizioneDescription Obbligatorio/facoltativoRequired/Optional
csl Testo della query o del comando di controllo da eseguireText of the query or control command to execute ObbligatoriaRequired
db Nome del database nell'ambito che è la destinazione del comando di query o controlloName of the database in scope that is the target of the query or control command Facoltativo per alcuni comandi di controllo.Optional for some control commands.
Obbligatorio per altri comandi e per tutte le query.Required for other commands and all queries.
properties Fornisce le proprietà della richiesta client che modificano il modo in cui la richiesta viene elaborata e i relativi risultati.Provides client request properties that modify how the request is processed and its results. Per ulteriori informazioni, vedere proprietà della richiesta clientFor more information, see client request properties FacoltativoOptional

OTTENERE i parametri della queryGET query parameters

Quando si usa GET, i parametri di query della richiesta specificano i parametri della richiesta.When GET is used, the query parameters of the request specify the request parameters.

CorpoBody

Quando si usa POST, il corpo della richiesta è un singolo documento JSON codificato in UTF-8, con i valori dei parametri della richiesta.When POST is used, the body of the request is a single JSON document encoded in UTF-8, with the values of the request parameters.

EsempiExamples

In questo esempio viene illustrata la richiesta HTTP POST per una query.This example shows the HTTP POST request for a query.

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

Intestazioni della richiestaRequest headers

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

Corpo della richiestaRequest body

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

Questo esempio illustra come creare una richiesta che invia la query precedente usando curl.This example shows how to create a request that sends the query above, using curl.

  1. Ottenere un token per l'autenticazione.Obtain a token for authentication.

    Sostituire AAD_TENANT_NAME_OR_ID , AAD_APPLICATION_ID e AAD_APPLICATION_KEY con i valori rilevanti, dopo aver configurato l'autenticazione dell'applicazione AADReplace AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_ID, and AAD_APPLICATION_KEY with the relevant values, after having set up AAD application authentication

    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 fornirà le bearer token.This code snippet will provide you with the bearer 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. Usare il bearer token nella richiesta all'endpoint di query.Use the bearer token in your request to the query endpoint.

    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.Read the response according to this specification.