Requête HTTP d’interrogation ou de gestion

Demander un verbe et une ressource

Action	Verbe HTTP	Ressource HTTP
Requête	GET	/v1/rest/query
Requête	POST	/v1/rest/query
Requête v2	GET	/v2/rest/query
Requête v2	POST	/v2/rest/query
Gestion	POST	/v1/rest/mgmt

Par exemple, pour envoyer une commande de gestion (« gestion ») à un point de terminaison de service, utilisez la ligne de requête suivante :

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

Consultez ci-dessous pour connaître les en-têtes et le corps de la demande à inclure.

En-têtes de requête

Le tableau suivant contient les en-têtes courants utilisés pour les opérations de requête et de gestion.

En-tête standard	Description	Obligatoire ou facultatif
Accept	Paramètre à définir sur application/json	Obligatoire
Accept-Encoding	Les encodages pris en charge sont gzip et deflate	Facultatif
Authorization	Voir Authentification	Obligatoire
Connection	Nous vous recommandons d’activer Keep-Alive	Facultatif
Content-Length	Nous vous recommandons de spécifier la longueur du corps de la demande lorsqu’elle est connue	Facultatif
Content-Type	Définir sur application/json avec charset=utf-8	Obligatoire
Expect	Peut être défini sur 100-Continue	Facultatif
Host	Définissez sur le nom de domaine qualifié auquel la demande a été envoyée (par exemple, help.kusto.windows.net)	Obligatoire

Le tableau suivant contient les en-têtes personnalisés courants utilisés pour les opérations de requête et de gestion. Sauf indication contraire, ces en-têtes sont utilisés uniquement à des fins de télémétrie et n’ont aucun impact sur les fonctionnalités.

Tous les en-têtes sont facultatifs. Nous vous recommandons de spécifier l’en-tête x-ms-client-request-id personnalisé. Dans certains scénarios, comme l’annulation d’une requête en cours d’exécution, cet en-tête est requis, car il est utilisé pour identifier la requête.

En-tête personnalisé	Description
x-ms-app	Nom (convivial) de l’application qui effectue la demande
x-ms-user	Nom (convivial) de l’utilisateur qui effectue la demande
x-ms-user-id	Identique à x-ms-user
x-ms-client-request-id	Identificateur unique pour la demande
x-ms-client-version	Identificateur de version (convivial) pour le client qui effectue la demande
x-ms-readonly	Si spécifié, force l’exécution de la demande en mode lecture seule, ce qui l’empêche d’apporter des modifications durables

Paramètres de la demande

Les paramètres suivants peuvent être transmis dans la requête. Ils sont encodés dans la requête en tant que paramètres de requête ou dans le corps, selon que GET ou POST est utilisé.

Paramètre	Description	Obligatoire ou facultatif
csl	Texte de la requête ou de la commande de gestion à exécuter	Obligatoire
db	Nom de la base de données dans l’étendue qui est la cible de la requête ou de la commande de gestion	Facultatif pour certaines commandes de gestion. Obligatoire pour les autres commandes et toutes les requêtes.
properties	Fournit des propriétés de requête qui modifient la façon dont la demande est traitée et ses résultats. Pour plus d’informations, consultez Propriétés de la demande	Facultatif

Paramètres de requête GET

Lorsque GET est utilisé, les paramètres de requête de la requête spécifient les paramètres de la requête.

Corps

Lorsque POST est utilisé, le corps de la requête est un seul document JSON encodé en UTF-8, avec les valeurs des paramètres de la requête.

Exemples

Cet exemple montre la requête HTTP POST pour une requête.

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

En-têtes de requête

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

Corps de la demande

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

Cet exemple montre comment créer une requête qui envoie la requête ci-dessus à l’aide de curl.

1. Obtenez un jeton pour l’authentification.

   Remplacez AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDet AAD_APPLICATION_KEY par les valeurs appropriées, après avoir configuré Microsoft Entra’authentification d’application

   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"
   

   Cet extrait de code vous fournira le jeton du porteur.

   {
     "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. Utilisez le jeton du porteur dans votre demande au point de terminaison de requête.

   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. Lisez la réponse en fonction de cette spécification.

Définir les propriétés de la requête cliente et les paramètres de requête

Dans l’exemple de corps suivant, la requête dans le csl champ déclare deux paramètres nommés n et d. Les valeurs de ces paramètres de requête sont spécifiées dans le Parameters champ sous le properties champ dans le corps de la requête. Le Options champ définit les propriétés de la requête cliente.

Notes

Les paramètres non-chaîne et non longs doivent être exprimés en tant que littéraux KQL au format chaîne.

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

Pour plus d’informations, consultez Paramètres de requête.