Réponse HTTP d’interrogation ou de gestion

Status de réponse

La ligne de status réponse HTTP suit les codes de réponse STANDARD HTTP. Par exemple, le code 200 indique la réussite.

Les codes status suivants sont actuellement utilisés, même si tout code HTTP valide peut être retourné.

Code	Sous-code	Description
100	Continue	Le client peut continuer à envoyer la demande.
200	OK	Le traitement de la demande a été effectué avec succès.
400	BadRequest	La demande est mal formée et a échoué (définitivement).
401	Non autorisé	Le client doit d’abord s’authentifier.
403	Interdit	La demande du client est refusée.
404	NotFound	La requête fait référence à une entité non existante.
413	PayloadTooLarge	La charge utile de la demande a dépassé les limites.
429	TooManyRequests	La demande a été refusée en raison de la limitation.
504	Délai d'expiration	Le délai de la demande a expiré.
520	ServiceError	Le service a trouvé une erreur lors du traitement de la demande.

Notes

Le code 200 status indique que le traitement de la demande a démarré correctement et non qu’il s’est terminé avec succès. Les échecs rencontrés lors du traitement de la demande après le retour de 200 status code sont appelés « échecs de requête partiels », et lorsqu’ils sont rencontrés, des indicateurs spéciaux sont injectés dans le flux de réponse pour avertir le client qu’ils se sont produits.

En-têtes de réponse

Les en-têtes personnalisés suivants seront retournés.

En-tête personnalisé	Description
x-ms-client-request-id	Identificateur de requête unique envoyé dans l’en-tête de la demande du même nom, ou un identificateur unique.
x-ms-activity-id	Identificateur de corrélation global unique pour la demande. Il est créé par le service.

Response body

Si le code status est 200, le corps de la réponse est un document JSON qui encode les résultats de la requête ou de la commande de gestion sous la forme d’une séquence de tables rectangulaires. Voir les détails ci-dessous.

Notes

La séquence de tables est reflétée par le Kit de développement logiciel (SDK). Par exemple, lors de l’utilisation de la bibliothèque Kusto.Data .NET Framework, la séquence de tables devient alors les résultats dans l’objet System.Data.IDataReader retourné par le SDK.

Si le code status indique une erreur 4xx ou 5xx, autre que 401, le corps de la réponse est un document JSON qui encode les détails de l’échec. Pour plus d’informations, consultez Instructions relatives à l’API REST Microsoft.

Notes

Si l’en-tête Accept n’est pas inclus dans la demande, le corps de réponse d’un échec n’est pas nécessairement un document JSON.

Encodage JSON d’une séquence de tables

L’encodage JSON d’une séquence de tables est un seul conteneur de propriétés JSON avec les paires nom/valeur suivantes.

Nom	Valeur
Tables	Tableau du sac de propriétés Table.

Le conteneur de propriétés Table comporte les paires nom/valeur suivantes.

Nom	Valeur
TableName	Chaîne qui identifie la table.
Colonnes	Tableau du conteneur de propriétés Column.
Lignes	Tableau du tableau Row.

Le conteneur de propriétés Column a les paires nom/valeur suivantes.

Nom	Valeur
ColumnName	Chaîne qui identifie la colonne.
DataType	Chaîne qui fournit le type .NET approximatif de la colonne.
ColumnType	Chaîne qui fournit le type de données scalaire de la colonne.

Le tableau Row a le même ordre que le tableau Colonnes respectif. Le tableau Row a également un élément qui coïncide avec la valeur de la ligne pour la colonne appropriée. Les types de données scalaires qui ne peuvent pas être représentés dans JSON, tels que datetime et timespan, sont représentés sous forme de chaînes JSON.

L’exemple suivant montre un objet de ce type possible, lorsqu’il contient une table unique appelée Table_0 qui a une colonne Text unique de type stringet une seule ligne.

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

Autre exemple :

Signification des tables dans la réponse

Dans la plupart des cas, les commandes de gestion retournent un résultat avec une table unique, contenant les informations générées par la commande de gestion. Par exemple, la .show databases commande retourne une table unique avec les détails de toutes les bases de données accessibles dans le cluster.

Les requêtes retournent généralement plusieurs tables. Pour chaque instruction d’expression tabulaire, une ou plusieurs tables sont générées dans l’ordre, représentant les résultats produits par l’instruction.

Notes

Il peut y avoir plusieurs tables de ce type en raison des lots et des opérateurs de duplication).

Trois tables sont souvent produites :

• Table @ExtendedProperties qui fournit des valeurs supplémentaires, telles que des instructions de visualisation du client (informations fournies par l’opérateur de rendu), des informations sur le curseur de base de données efficace de la requête ou des informations sur l’utilisation efficace du cache des résultats de la requête.

  Pour les requêtes envoyées à l’aide du protocole v1, la table a une colonne unique de type string, dont la valeur est une chaîne encodée JSON, telle que :

  Valeur
  {"Visualisation » :"graphique en secteurs »,...}
  {"Cursor » :"637239957206013576"}

  Pour les requêtes envoyées à l’aide du protocole v2, la table comporte trois colonnes : (1) Une integer colonne appelée TableId indiquant à quelle table dans le jeu de résultats l’enregistrement s’applique ; (2) Colonne string appelée Key indiquant le type d’informations fournies par l’enregistrement (valeurs possibles : Visualization, ServerCacheet Cursor) ; (3) Colonne dynamic appelée fournissant Value les informations déterminées par la clé.

  TableId	Clé	Valeur
  1	ServerCache	{"OriginalStartedOn » :"2021-06-11T07 :48 :34.6201025Z »,...}
  1	Visualisation	{"Visualisation » :"graphique en secteurs »,...}

• Table QueryStatus qui fournit des informations supplémentaires sur l’exécution de la requête elle-même, par exemple, si elle s’est terminée correctement ou non, et quelles ont été les ressources consommées par la requête.

  Cette table a la structure suivante :

  Timestamp	Gravité	SeverityName	StatusCode	StatusDescription	Nombre	RequestId	ActivityId	SubActivityId	ClientActivityId
  2020-05-02 06:09:12.7052077	4	Informations	0	Requête terminée avec succès	1	...	...	...	...

  Les valeurs de gravité de 2 ou inférieures indiquent un échec.

• TableOfContents, qui est créée en dernier et répertorie les autres tables dans les résultats.

  Voici un exemple pour cette table :

  Ordinal	Genre	Name	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