Share via

Consulta de la respuesta HTTP V2

  • Artículo

Línea de estado de respuesta HTTP

Si la solicitud se realiza correctamente, el código de estado de respuesta HTTP es 200 OK. El cuerpo de la respuesta HTTP es una matriz JSON, como se explica a continuación.

Si se produce un error en la solicitud, el código de estado de respuesta HTTP es un 4xx error o 5xx . La frase de motivo incluirá información adicional sobre el error. El cuerpo de la respuesta HTTP es un objeto JSON, como se explica a continuación.

Nota

La solicitud puede devolver un código de estado de , pero el cuerpo de 200 OKla respuesta HTTP indicará un error. Esto puede ocurrir cuando se produce el error después de que ya se devuelva la línea de estado HTTP. Se espera que el lector compruebe explícitamente si se trata de una condición de este tipo.

Encabezados de respuesta HTTP

Independientemente del éxito o error de la solicitud, se incluyen dos encabezados HTTP personalizados con la respuesta:

  1. x-ms-client-request-id: el servicio devuelve una cadena opaca que identifica el par de solicitud/respuesta con fines de correlación. Si la solicitud incluía un identificador de solicitud de cliente, su valor aparecerá aquí; de lo contrario, se devuelve alguna cadena aleatoria.

  2. x-ms-activity-id: el servicio devuelve una cadena opaca que identifica de forma única el par de solicitud/respuesta con fines de correlación. A diferencia x-ms-client-request-idde , este identificador no se ve afectado por ninguna información de la solicitud y es único por respuesta.

Cuerpo de respuesta HTTP (en caso de error de solicitud)

En caso de error de solicitud, el cuerpo de la respuesta HTTP será un documento JSON con formato según OneApiErrors las reglas. Para obtener una descripción del OneApiErrors formato, consulte la sección 7.10.2 aquí. A continuación se muestra un ejemplo de este error.

{
    "error": {
        "code": "General_BadRequest",
        "message": "Request is invalid and cannot be executed.",
        "@type": "Kusto.Data.Exceptions.KustoBadRequestException",
        "@message": "Request is invalid and cannot be processed: Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
        "@context": {
            "timestamp": "2023-04-18T12:59:27.4855445Z",
            "serviceAlias": "HELP",
            "machineName": "KEngine000000",
            "processName": "Kusto.WinSvc.Svc",
            "processId": 12580,
            "threadId": 10260,
            "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
            "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
            "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
            "activityType": "DN.FE.ExecuteQuery",
            "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
            "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
        },
        "@permanent": true,
        "@text": "aaa",
        "@database": "Samples",
        "@ClientRequestLogger": "",
        "innererror": {
            "code": "SEM0100",
            "message": "'table' operator: Failed to resolve table expression named 'aaa'",
            "@type": "Kusto.Data.Exceptions.SemanticException",
            "@message": "Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
            "@context": {
                "timestamp": "2023-04-18T12:59:27.4855445Z",
                "serviceAlias": "HELP",
                "machineName": "KEngine000000",
                "processName": "Kusto.WinSvc.Svc",
                "processId": 12580,
                "threadId": 10260,
                "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
                "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
                "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
                "activityType": "DN.FE.ExecuteQuery",
                "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
                "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
            },
            "@permanent": true,
            "@errorCode": "SEM0100",
            "@errorMessage": "'table' operator: Failed to resolve table expression named 'aaa'"
        }
    }
}

Cuerpo de la respuesta HTTP (si la solicitud se ha realizado correctamente)

Si la solicitud se realiza correctamente, el cuerpo de la respuesta HTTP será una matriz JSON que codifica los resultados de la solicitud.

Lógicamente, la respuesta V2 describe un objeto DataSet que contiene cualquier número de tablas. Estas tablas pueden representar los datos reales solicitados por la solicitud o información adicional sobre la ejecución de la solicitud (por ejemplo, una contabilidad de los recursos consumidos por la solicitud). Además, la solicitud real podría producir un error (debido a varias condiciones), aunque se devuelva un 200 OK estado y, en ese caso, la respuesta incluirá datos de respuesta parciales más una indicación de los errores.

Físicamente, la matriz JSON del cuerpo de respuesta es una lista de objetos JSON, cada uno de los cuales se denomina marco. El objeto DataSet se codifica en dos fotogramas: DataSetHeader y DataSetCompletion. El primero es siempre el primer fotograma y el segundo es siempre el último fotograma. En "entre ellos", se pueden encontrar los marcos que describen los objetos Table.

Los objetos Table se pueden codificar de dos maneras:

  1. Como marco único: DataTable. Este es el valor predeterminado.

  2. Como alternativa, como una "combinación" de cuatro tipos de fotogramas: TableHeader (que viene primero y describe la tabla), TableFragment (que describe los datos de una tabla), TableProgress (que es opcional y proporciona una estimación de la distancia en los datos de la tabla que estamos) y TableCompletion (que es el último marco de la tabla).

El segundo caso se denomina "modo progresivo" y solo aparecerá si la propiedad results_progressive_enabled de solicitud de cliente está establecida trueen . En este caso, cada fotograma TableFragment describe una actualización de los datos acumulados por todos los fotogramas anteriores para la tabla, ya sea como una operación de anexión o como una operación de reemplazo. (Este último se usa, por ejemplo, cuando se realiza algún cálculo de agregación de larga duración en el "nivel superior" de la consulta, por lo que un resultado de agregación inicial se reemplaza por resultados más precisos más adelante).

DataSetHeader

El DataSetHeader marco siempre es el primero del conjunto de datos y aparece exactamente una vez.

{
    "Version": string,
    "IsProgressive": Boolean
}

Donde:

  • Version es la versión del protocolo. La versión actual es v2.0.

  • IsProgressive es una marca booleana que indica si este conjunto de datos contiene fotogramas progresivos. Un fotograma progresivo es uno de los siguientes:

    Fotograma Descripción
    TableHeader Contiene información general sobre la tabla.
    TableFragment Contiene una partición de datos rectangular de la tabla.
    TableProgress Contiene el progreso en porcentaje (0-100)
    TableCompletion Indica que este fotograma es el último

    Los marcos anteriores describen una tabla. Si la IsProgressive marca no está establecida en true, todas las tablas del conjunto se serializarán mediante un solo marco:

  • DataTable: contiene toda la información que el cliente necesita sobre una sola tabla del conjunto de datos.

TableHeader

Las consultas realizadas con la results_progressive_enabled opción establecida en true pueden incluir este marco. Después de esta tabla, los clientes pueden esperar una secuencia de intercalación de TableFragment fotogramas y TableProgress . El marco final de la tabla es TableCompletion.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
}

Donde:

  • TableId es el identificador único de la tabla.

  • TableKind es uno de los siguientes valores:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • TableOfContents
    • QueryProperties
    • QueryPlan
    • Desconocido

  • TableName es el nombre de la tabla.

  • Columns es una matriz que describe el esquema de la tabla.

{
    "ColumnName": string,
    "ColumnType": string,
}

Los tipos de columna admitidos se describen aquí.

TableFragment

El TableFragment marco contiene un fragmento de datos rectangular de la tabla. Además de los datos reales, este fotograma también contiene una TableFragmentType propiedad que indica al cliente qué hacer con el fragmento. Fragmento anexado a fragmentos existentes o reemplácelos.

{
    "TableId": Number,
    "FieldCount": Number,
    "TableFragmentType": string,
    "Rows": Array
}

Donde:

  • TableId es el identificador único de la tabla.

  • FieldCount es el número de columnas de la tabla.

  • TableFragmentType describe lo que el cliente debe hacer con este fragmento. TableFragmentType es uno de los siguientes valores:

    • DataAppend
    • DataReplace

  • Rows es una matriz bidimensional que contiene los datos de fragmento.

TableProgress

El TableProgress marco puede intercalar con el TableFragment marco descrito anteriormente. Su único propósito es notificar al cliente el progreso de la consulta.

{
    "TableId": Number,
    "TableProgress": Number,
}

Donde:

  • TableId es el identificador único de la tabla.
  • TableProgress es el progreso en porcentaje (0--100).

TableCompletion

El TableCompletion marco marca el final de la transmisión de la tabla. No se enviarán más fotogramas relacionados con esa tabla.

{
    "TableId": Number,
    "RowCount": Number,
}

Donde:

  • TableId es el identificador único de la tabla.
  • RowCount es el número total de filas de la tabla.

DataTable

Las consultas emitidas con la EnableProgressiveQuery marca establecida en false no incluirán ninguno de los fotogramas (TableHeader, TableFragment, TableProgressy TableCompletion). En su lugar, cada tabla del conjunto de datos se transmitirá mediante el DataTable marco que contiene toda la información que necesita el cliente para leer la tabla.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
    "Rows": Array,
}

Donde:

  • TableId es el identificador único de la tabla.

  • TableKind es uno de los siguientes valores:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • QueryProperties
    • QueryPlan
    • Desconocido

  • TableName es el nombre de la tabla.

  • Columns es una matriz que describe el esquema de la tabla e incluye:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows es una matriz bidimensional que contiene los datos de la tabla.

Significado de las tablas en la respuesta

  • PrimaryResult : el resultado tabular principal de la consulta. 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 . Puede haber varias tablas de este tipo debido a lotes y operadores de bifurcación.
  • QueryCompletionInformation - Proporciona información adicional sobre la ejecución de la propia consulta, como si se completó correctamente o no, y cuáles fueron los recursos consumidos por la consulta (similar a la tabla QueryStatus en la respuesta v1).
  • QueryProperties : proporciona valores adicionales, como instrucciones de visualización de cliente (emitidas, por ejemplo, para reflejar la información en el operador render) y la información del cursor de base de datos .
  • QueryTraceLog - La información del registro de seguimiento de rendimiento (devuelta cuando perftrace en las propiedades de la solicitud de cliente se establece en true).

DataSetCompletion

El DataSetCompletion marco es el último del conjunto de datos.

{
    "HasErrors": Boolean,
    "Cancelled": Boolean,
    "OneApiErrors": Array,
}

Donde:

  • HasErrors es true si se produjeron errores al generar el conjunto de datos.
  • Cancelled es true si la solicitud que llevó a la generación del conjunto de datos se canceló antes de la finalización.
  • OneApiErrors solo se devuelve si HasErrors es true. Para obtener una descripción del OneApiErrors formato, consulte la sección 7.10.2 aquí.