Solicitud HTTP de consulta/administración

Verbo de solicitud y recurso

Acción	Verbo HTTP	Recurso HTTP
Consultar	GET	/v1/rest/query
Consultar	POST	/v1/rest/query
Consulta v2	GET	/v2/rest/query
Consulta v2	POST	/v2/rest/query
Administración	POST	/v1/rest/mgmt

Por ejemplo, para enviar un comando de administración ("management") a un punto de conexión de servicio, use la siguiente línea de solicitud:

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

Consulte a continuación los encabezados y el cuerpo de la solicitud que se van a incluir.

Encabezados de solicitud

La tabla siguiente contiene los encabezados comunes que se usan para las operaciones de consulta y administración.

Encabezado estándar	Descripción	Obligatorio/opcional
Accept	Establézcala en application/json	Requerido
Accept-Encoding	Las codificaciones admitidas son gzip y deflate	Opcionales
Authorization	Consulte autenticación.	Requerido
Connection	Se recomienda habilitar Keep-Alive	Opcionales
Content-Length	Se recomienda especificar la longitud del cuerpo de la solicitud cuando se conoce.	Opcionales
Content-Type	Establézcalo en application/json con charset=utf-8	Requerido
Expect	Se puede establecer en 100-Continue	Opcionales
Host	Establezca en el nombre de dominio completo al que se envió la solicitud (por ejemplo, help.kusto.windows.net).	Requerido

La tabla siguiente contiene los encabezados personalizados comunes que se usan para las operaciones de consulta y administración. A menos que se indique lo contrario, estos encabezados solo se usan con fines de telemetría y no tienen ningún impacto en la funcionalidad.

Todos los encabezados son opcionales. Se recomienda especificar el x-ms-client-request-id encabezado personalizado. En algunos escenarios, como cancelar una consulta en ejecución, este encabezado es necesario porque se usa para identificar la solicitud.

Encabezado personalizado	Descripción
x-ms-app	Nombre (descriptivo) de la aplicación que realiza la solicitud.
x-ms-user	Nombre (descriptivo) del usuario que realiza la solicitud
x-ms-user-id	Igual que x-ms-user.
x-ms-client-request-id	Un identificador único para la solicitud.
x-ms-client-version	Identificador de versión (descriptivo) del cliente que realiza la solicitud.
x-ms-readonly	Si se especifica, obliga a que la solicitud se ejecute en modo de solo lectura, lo que impide que realice cambios duraderos.

Parámetros de solicitud

Los parámetros siguientes se pueden pasar en la solicitud. Se codifican en la solicitud como parámetros de consulta o como parte del cuerpo, en función de si se usa GET o POST.

Parámetro	Descripción	Obligatorio/opcional
csl	Texto del comando de consulta o administración que se va a ejecutar	Requerido
db	Nombre de la base de datos en el ámbito que es el destino del comando de consulta o administración.	Opcional para algunos comandos de administración. Obligatorio para otros comandos y todas las consultas.
properties	Proporciona propiedades de solicitud que modifican cómo se procesa la solicitud y sus resultados. Para obtener más información, consulte Propiedades de solicitud.	Opcionales

Parámetros de consulta GET

Cuando se usa GET, los parámetros de consulta de la solicitud especifican los parámetros de solicitud.

Cuerpo

Cuando se usa POST, el cuerpo de la solicitud es un único documento JSON codificado en UTF-8, con los valores de los parámetros de solicitud.

Ejemplos

En este ejemplo se muestra la solicitud HTTP POST para una consulta.

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

Encabezados de solicitud

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

Cuerpo de la solicitud

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

En este ejemplo se muestra cómo crear una solicitud que envíe la consulta anterior mediante curl.

1. Obtenga un token para la autenticación.

   Reemplace AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_IDy AAD_APPLICATION_KEY por los valores pertinentes, después de haber configurado Microsoft Entra autenticación de aplicaciones.

   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"
   

   Este fragmento de código le proporcionará el token de portador.

   {
     "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. Use el token de portador en la solicitud al punto de conexión de consulta.

   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. Lea la respuesta según esta especificación.

Establecimiento de propiedades de solicitud de cliente y parámetros de consulta

En el cuerpo del ejemplo siguiente, la consulta del csl campo declara dos parámetros denominados n y d. Los valores de esos parámetros de consulta se especifican dentro del Parameters campo bajo el campo en el properties cuerpo de la solicitud. El Options campo define las propiedades de la solicitud de cliente.

Nota:

Los parámetros que no son de cadena y no long deben expresarse como literales KQL en formato de cadena.

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

Para más información, consulte Parámetros de consulta.