Respuesta HTTP de consulta/administración

Estado de respuesta

La línea de estado de respuesta HTTP sigue los códigos de respuesta estándar HTTP. Por ejemplo, el código 200 indica que se ha realizado correctamente.

Los siguientes códigos de estado están actualmente en uso, aunque se puede devolver cualquier código HTTP válido.

Código	SubCode	Descripción
100	Continuar	El cliente puede seguir enviando la solicitud.
200	Aceptar	Solicitud iniciada el procesamiento correctamente.
400	BadRequest	La solicitud tiene un formato incorrecto y se produce un error (permanentemente).
401	No autorizado	El cliente debe autenticarse primero.
403	Prohibido	Se deniega la solicitud de cliente.
404	NotFound	La solicitud hace referencia a una entidad no existente.
413	PayloadTooLarge	La carga de solicitud superó los límites.
429	TooManyRequests	Se ha denegado la solicitud debido a la limitación.
504	Tiempo de espera	Se agota el tiempo de espera de la solicitud.
520	ServiceError	El servicio encontró un error al procesar la solicitud.

Nota

El código de estado 200 muestra que el procesamiento de solicitudes se ha iniciado correctamente y no que se ha completado correctamente. Los errores detectados durante el procesamiento de solicitudes después de que se haya devuelto el código de estado 200 se denominan "errores de consulta parciales" y, cuando se encuentran, se insertan indicadores especiales en el flujo de respuesta para alertar al cliente que se produjeron.

Encabezados de respuesta

Se devolverán los siguientes encabezados personalizados.

Encabezado personalizado	Descripción
x-ms-client-request-id	Identificador de solicitud único enviado en el encabezado de solicitud del mismo nombre o algún identificador único.
x-ms-activity-id	Un identificador de correlación único global para la solicitud. El servicio lo crea.

Response body

Si el código de estado es 200, el cuerpo de la respuesta es un documento JSON que codifica los resultados de la consulta o el comando de administración como una secuencia de tablas rectangulares. Para obtener información más detallada, vea a continuación.

Nota:

El SDK refleja la secuencia de tablas. Por ejemplo, cuando se usa la biblioteca Kusto.Data de .NET Framework, la secuencia de tablas se convierte en los resultados del System.Data.IDataReader objeto devuelto por el SDK.

Si el código de estado indica un error 4xx o 5xx, distinto de 401, el cuerpo de la respuesta es un documento JSON que codifica los detalles del error. Para obtener más información, consulte Directrices de la API REST de Microsoft.

Nota

Si el Accept encabezado no se incluye con la solicitud, el cuerpo de respuesta de un error no es necesariamente un documento JSON.

Codificación JSON de una secuencia de tablas

La codificación JSON de una secuencia de tablas es un contenedor de propiedades JSON único con los siguientes pares nombre-valor.

Nombre	Valor
Tablas	Matriz del contenedor de propiedades Table.

El contenedor de propiedades Table tiene los siguientes pares nombre-valor.

Nombre	Valor
TableName	Cadena que identifica la tabla.
Columnas	Matriz del contenedor de propiedades Column.
Filas	Matriz de la matriz Row.

El contenedor de propiedades Column tiene los siguientes pares nombre-valor.

Nombre	Valor
ColumnName	Cadena que identifica la columna.
DataType	Cadena que proporciona el tipo de .NET aproximado de la columna.
ColumnType	Cadena que proporciona el tipo de datos escalar de la columna.

La matriz Row tiene el mismo orden que la matriz Columns correspondiente. La matriz Row también tiene un elemento que coincide con el valor de la fila de la columna correspondiente. Los tipos de datos escalares que no se pueden representar en JSON, como datetime y timespan, se representan como cadenas JSON.

En el ejemplo siguiente se muestra un posible objeto de este tipo, cuando contiene una sola tabla denominada Table_0 que tiene una sola columna Text de tipo stringy una sola fila.

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

Otro ejemplo:

Significado de las tablas en la respuesta

En la mayoría de los casos, los comandos de administración devuelven un resultado con una sola tabla, que contiene la información generada por el comando de administración. Por ejemplo, el .show databases comando devuelve una sola tabla con los detalles de todas las bases de datos accesibles del clúster.

Las consultas suelen devolver varias tablas. Para cada instrucción de expresión tabular, se generan una o varias tablas en orden, que representan los resultados generados por la instrucción .

Nota

Puede haber varias tablas de este tipo debido a lotes y operadores de bifurcación).

A menudo se generan tres tablas:

• Tabla @ExtendedProperties que proporciona valores adicionales, como instrucciones de visualización de cliente (información proporcionada por el operador render), información sobre el cursor de base de datos eficaz de la consulta o información sobre el uso efectivo de la consulta de la caché de resultados de la consulta.

  En el caso de las consultas enviadas mediante el protocolo v1, la tabla tiene una sola columna de tipo string, cuyo valor es una cadena codificada en JSON, como:

  Valor
  {"Visualization":"piechart",...}
  {"Cursor":"637239957206013576"}

  En el caso de las consultas enviadas mediante el protocolo v2, la tabla tiene tres columnas: (1) Columna integer denominada TableId que indica a qué tabla del conjunto de resultados se aplica el registro; (2) Columna string denominada Key que indica el tipo de información proporcionada por el registro (valores posibles: Visualization, ServerCachey Cursor); (3) Columna dynamic denominada Value proporcionar la información determinada por claves.

  TableId	Clave	Valor
  1	ServerCache	{"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
  1	Visualización	{"Visualization":"piechart",...}

• Tabla QueryStatus que proporciona información adicional sobre la ejecución de la propia consulta, como, si se completó correctamente o no, y cuáles eran los recursos consumidos por la consulta.

  Esta tabla tiene la siguiente estructura:

  Timestamp	severity	SeverityName	StatusCode	StatusDescription	Recuento	RequestId	ActivityId	SubActivityId	ClientActivityId
  2020-05-02 06:09:12.7052077	4	Información	0	Consulta completada correctamente	1	...	...	...	...

  Los valores de gravedad de 2 o más pequeños indican un error.

• Una tabla TableOfContents, que se crea por última vez, y enumera las demás tablas de los resultados.

  Un ejemplo de esta tabla es:

  Ordinal	Clase	Nombre	Identificador	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