Compartir a través de

Solicitud HTTP de consulta/administración

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

Solicitud de verbo y recurso

Action Verbo HTTP Recurso HTTP
Consulta GET /v1/rest/query
Consulta PUBLICAR /v1/rest/query
Consulta v2 GET /v2/rest/query
Consulta v2 PUBLICAR /v2/rest/query
Administración PUBLICAR /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 Encabezados de solicitud y Cuerpo para obtener información sobre lo que se debe 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 Los tipos multimedia que recibe el cliente. Establécelo en application/json. Obligatorio
Accept-Encoding Codificaciones de contenido admitidas. Las codificaciones admitidas son gzip y deflate. Opcionales
Authorization Credenciales de autenticación. Para obtener más información, consulte autenticación. Obligatorio
Connection Indica si la conexión permanece abierta después de la operación. La recomendación es establecer en Connection Keep-Alive. Opcionales
Content-Length Tamaño del cuerpo de la solicitud. Especifique la longitud del cuerpo de la solicitud cuando se conozca. Opcionales
Content-Type Tipo de medio del cuerpo de la solicitud. Establezca en application/json con charset=utf-8. Obligatorio
Expect Respuesta esperada del servidor. Se puede establecer en 100-Continue. Opcionales
Host Nombre de dominio completo al que se envió la solicitud. Por ejemplo, help.kusto.windows.net. Obligatorio

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

Todos los encabezados son opcionales. Sin embargo, se recomienda especificar el x-ms-client-request-id encabezado personalizado. En algunos escenarios, como cancelar una consulta en ejecución, es necesario, x-ms-client-request-id ya que 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 El mismo nombre descriptivo que x-ms-user.
x-ms-client-request-id Identificador único de la solicitud.
x-ms-client-version Identificador de versión descriptivo para el 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 la solicitud cambie los datos.

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. Obligatorio
db Nombre de la base de datos que es el destino del comando de consulta o administración. Opcional para algunos comandos de administración.
Necesario para todas las consultas y todos los demás comandos.
properties Propiedades de solicitud que modifican cómo se procesa la solicitud y sus resultados. Para más información, consulte Propiedades necesarias. Opcionales

Parámetros de consulta GET

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

Body

Cuando se usa una solicitud POST, el cuerpo de la solicitud contiene un único documento JSON con codificación UTF-8, que incluye los valores de los parámetros de solicitud.

Ejemplos

En el ejemplo siguiente 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 el ejemplo siguiente 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 configurar la autenticación de aplicaciones de 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"

    Este fragmento de código proporciona 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 los códigos de estado de respuesta.

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

En el ejemplo de cuerpo de la solicitud 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 debajo del campo en el properties cuerpo de la solicitud. El Options campo define las propiedades de solicitud de cliente.

Nota:

Los parámetros que no son de cadena y no largos 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 obtener más información, vea Propiedades de solicitud admitidas.

Comando Enviar directiva de almacenamiento en caché de la base de datos

En el ejemplo siguiente se envía una solicitud para mostrar la directiva de almacenamiento en caché de la Samples base de datos.


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