Requête HTTP d’interrogation ou de gestion

Article
12/04/2024

S’applique à : ✅Microsoft Fabric ✅Azure Data Explorer

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 les en-têtes de requête et le corps pour découvrir ce qu’il faut 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`	Les types multimédias reçus par le client. Réglez sur `application/json`.	Requis
`Accept-Encoding`	Encodages de contenu pris en charge. Les encodages pris en charge sont `gzip` et `deflate`.	Facultatif
`Authorization`	Informations d’identification d’authentification. Pour plus d’informations, consultez l’authentification.	Requis
`Connection`	Indique si la connexion reste ouverte après l’opération. La recommandation est de définir `Connection` `Keep-Alive`sur .	Facultatif
`Content-Length`	Taille du corps de la requête. Spécifiez la longueur du corps de la requête lorsqu’elle est connue.	Facultatif
`Content-Type`	Type de média du corps de la requête. Défini sur `application/json` avec `charset=utf-8`.	Requis
`Expect`	Réponse attendue du serveur. Elle peut être définie sur `100-Continue`.	Facultatif
`Host`	Nom de domaine qualifié auquel la demande a été envoyée. Par exemple : `help.kusto.windows.net`.	Requis

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’affectent pas les fonctionnalités.

Tous les en-têtes sont facultatifs. Toutefois, 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, est nécessaire, x-ms-client-request-id 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 requête.
`x-ms-user`	Nom convivial de l’utilisateur effectuant la requête.
`x-ms-user-id`	Le même nom convivial que `x-ms-user`.
`x-ms-client-request-id`	Identificateur unique de la requête.
`x-ms-client-version`	Identificateur de version convivial pour le client effectuant la requête.
`x-ms-readonly`	Si elle est spécifiée, elle force l’exécution de la requête en mode lecture seule, ce qui empêche la demande de modifier les données.

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 commande de requête ou de gestion à exécuter.	Requis
`db`	Nom de la base de données qui est la cible de la commande de requête ou de gestion.	Facultatif pour certaines commandes de gestion. Obligatoire pour toutes les requêtes et toutes les autres commandes.
`properties`	Propriétés de requête qui modifient la façon dont la requête est traitée et ses résultats. Pour plus d’informations, consultez Propriétés de la requête.	Facultatif

Paramètres de requête GET

Lorsqu’une requête GET est utilisée, les paramètres de requête spécifient les paramètres de la requête.

Corps

Lorsqu’une requête POST est utilisée, le corps de la requête contient un document JSON encodé en UTF-8 unique, qui inclut les valeurs des paramètres de la requête.

Exemples

L’exemple suivant 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\"}"
}

L’exemple suivant montre comment créer une requête qui envoie la requête précédente, à l’aide de curl.

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é l’authentification de l’application 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"

Cet extrait de code vous fournit 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"
}

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

Lisez la réponse en fonction des codes d’état de la réponse.

Définir les propriétés et les paramètres de requête du client

Dans l’exemple de corps de requête 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 champ dans le properties corps de la requête. Le Options champ définit les propriétés de requête du client.

Remarque

Les paramètres non-chaînes et non longs doivent être exprimés en tant que littéraux KQL au format de 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 Les propriétés de requête prises en charge.

Commande Envoyer afficher la stratégie de mise en cache de la base de données

L’exemple suivant envoie une requête pour afficher la Samples stratégie de mise en cache de la base de données.


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

Partage via

Requête HTTP d’interrogation ou de gestion

Demander un verbe et une ressource

En-têtes de requête

Paramètres de la demande

Paramètres de requête GET

Corps

Exemples

Définir les propriétés et les paramètres de requête du client

Commande Envoyer afficher la stratégie de mise en cache de la base de données

Commentaires

Ressources supplémentaires