Risposta HTTP di query/gestione

Stato della risposta

La riga di stato della risposta HTTP segue i codici di risposta standard HTTP. Ad esempio, il codice 200 indica l'esito positivo.

I codici di stato seguenti sono attualmente in uso, anche se è possibile restituire qualsiasi codice HTTP valido.

Codice	Sottocodice	Descrizione
100	Continua	Il client può continuare a inviare la richiesta.
200	OK	Richiesta avviata correttamente l'elaborazione.
400	BadRequest	La richiesta non è stata creata correttamente e non è riuscita (in modo permanente).
401	Non autorizzata	Il client deve prima eseguire l'autenticazione.
403	Accesso negato	Richiesta client negata.
404	NotFound	La richiesta fa riferimento a un'entità non esistente.
413	PayloadTooLarge	Il payload della richiesta ha superato i limiti.
429	TooManyRequests	La richiesta è stata negata a causa della limitazione.
504	Timeout	La richiesta è scaduta.
520	ServiceError	Il servizio ha rilevato un errore durante l'elaborazione della richiesta.

Nota

Il codice di stato 200 mostra che l'elaborazione della richiesta è stata avviata correttamente e non che sia stata completata correttamente. Gli errori riscontrati durante l'elaborazione delle richieste dopo che il codice di stato 200 viene restituito vengono chiamati "errori di query parziali" e quando vengono rilevati, gli indicatori speciali vengono inseriti nel flusso di risposta per avvisare il client che si sono verificati.

Intestazioni di risposta

Verranno restituite le intestazioni personalizzate seguenti.

Intestazione personalizzata	Descrizione
x-ms-client-request-id	Identificatore di richiesta univoco inviato nell'intestazione della richiesta dello stesso nome o di un identificatore univoco.
x-ms-activity-id	Identificatore di correlazione univoco globale per la richiesta. Viene creato dal servizio.

Corpo della risposta

Se il codice di stato è 200, il corpo della risposta è un documento JSON che codifica i risultati del comando di query o gestione come sequenza di tabelle rettangolari. Vedere di seguito per altri dettagli.

Nota

La sequenza di tabelle viene riflessa dall'SDK. Ad esempio, quando si usa la libreria Kusto.Data di .NET Framework, la sequenza di tabelle diventa quindi i risultati nell'oggetto System.Data.IDataReader restituito dall'SDK.

Se il codice di stato indica un errore 4xx o 5xx, diverso da 401, il corpo della risposta è un documento JSON che codifica i dettagli dell'errore. Per altre informazioni, vedere Linee guida per le API REST Microsoft.

Nota

Se l'intestazione Accept non è inclusa nella richiesta, il corpo della risposta di un errore non è necessariamente un documento JSON.

Codifica JSON di una sequenza di tabelle

La codifica JSON di una sequenza di tabelle è un singolo contenitore di proprietà JSON con le coppie nome/valore seguenti.

Nome	Valore
Tabelle	Matrice del contenitore delle proprietà Table.

La proprietà Table include le coppie nome/valore seguenti.

Nome	Valore
TableName	Stringa che identifica la tabella.
Colonne	Matrice del contenitore delle proprietà Column.
Righe	Matrice della matrice Row.

Il contenitore delle proprietà Column include le coppie nome/valore seguenti.

Nome	Valore
ColumnName	Stringa che identifica la colonna.
DataType	Stringa che fornisce il tipo .NET approssimativo della colonna.
ColumnType	Stringa che fornisce il tipo di dati scalare della colonna.

La matrice Row ha lo stesso ordine della rispettiva matrice Columns. La matrice Row include anche un elemento che coincide con il valore della riga per la colonna pertinente. I tipi di dati scalari che non possono essere rappresentati in JSON, ad esempio datetime e timespan, sono rappresentati come stringhe JSON.

Nell'esempio seguente viene illustrato un possibile oggetto, quando contiene una singola tabella denominata Table_0 con una singola colonna Text di tipo stringe una singola riga.

{
    "Tables": [{
        "TableName": "Table_0",
        "Columns": [{
            "ColumnName": "Text",
            "DataType": "String",
            "ColumnType": "string"
        }],
        "Rows": [["Hello, World!"]]
}

Un altro esempio:

Significato delle tabelle nella risposta

Nella maggior parte dei casi, i comandi di gestione restituiscono un risultato con una singola tabella, contenente le informazioni generate dal comando di gestione. Ad esempio, il .show databases comando restituisce una singola tabella con i dettagli di tutti i database accessibili nel cluster.

Le query restituiscono in genere più tabelle. Per ogni istruzione espressione tabulare, vengono generate una o più tabelle in ordine, che rappresentano i risultati generati dall'istruzione.

Nota

È possibile che siano presenti più tabelle a causa di batch e operatori fork.

Tre tabelle vengono spesso prodotte:

• Tabella @ExtendedProperties che fornisce valori aggiuntivi, ad esempio istruzioni di visualizzazione client (informazioni fornite dall'operatore di rendering), informazioni sul cursore di database effettivo della query o informazioni sull'uso effettivo della query della cache dei risultati della query.

  Per le query inviate usando il protocollo v1, la tabella ha una singola colonna di tipo string, il cui valore è una stringa con codifica JSON, ad esempio:

  Valore
  {"Visualizzazione":"piechart",...}
  {"Cursor":"637239957206013576"}

  Per le query inviate usando il protocollo v2, la tabella include tre colonne: (1) Colonna integer denominata TableId che indica la tabella nei risultati a cui si applica il record; (2) Colonna string denominata Key che indica il tipo di informazioni fornite dal record (valori possibili: Visualization, ServerCachee Cursor); (3) Colonna dynamic denominata Value che fornisce le informazioni determinate dalla chiave.

  TableId	Chiave	Valore
  1	ServerCache	{"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
  1	Visualizzazione	{"Visualizzazione":"piechart",...}

• Tabella QueryStatus che fornisce informazioni aggiuntive sull'esecuzione della query stessa, ad esempio se è stata completata correttamente o meno e sulle risorse utilizzate dalla query.

  Questa tabella presenta la struttura seguente:

  Timestamp	Gravità	SeverityName	StatusCode	StatusDescription	Conteggio	RequestId	ActivityId	SubActivityId	ClientActivityId
  2020-05-02 06:09:12.7052077	4	Info	0	Query completata correttamente	1	...	...	...	...

  I valori di gravità 2 o inferiori indicano un errore.

• Tabella TableOfContents, che viene creata per ultima e elenca le altre tabelle nei risultati.

  Un esempio per questa tabella è:

  Ordinale	Tipo	Nome	ID	PrettyName
  0	QueryResult	PrimaryResult	db9520f9-0455-4cb5-b257-53068497605a
  1	QueryProperties	@ExtendedProperties	908901f6-5319-4809-ae9e-009068c267c7
  2	QueryStatus	QueryStatus	00000000-0000-0000-0000-000000000000