Http-ответ "Запрос версии 2"

Статья
01/10/2024

Строка состояния HTTP-ответа

Если запрос выполнен успешно, код состояния HTTP-ответа имеет значение 200 OK. Текст ответа HTTP является массивом JSON, как описано ниже.

Если запрос завершается сбоем, код состояния HTTP-ответа — ошибка 4xx или 5xx . Фраза причины будет содержать дополнительные сведения о сбое. Текст ответа HTTP является объектом JSON, как описано ниже.

Примечание

Запрос может вернуть код 200 OKсостояния , но текст HTTP-ответа будет указывать на ошибку. Это может произойти, когда ошибка возникает после возврата строки состояния HTTP. Ожидается, что модуль чтения явно проверка для такого условия.

Заголовки HTTP-ответа

Независимо от успешного или неудачного выполнения запроса в ответ включаются два пользовательских заголовка HTTP:

x-ms-client-request-id: служба возвращает непрозрачную строку, которая идентифицирует пару "запрос-ответ" для корреляции. Если запрос включает идентификатор запроса клиента, его значение будет отображаться здесь; в противном случае возвращается случайная строка.
x-ms-activity-id: служба возвращает непрозрачную строку, которая однозначно идентифицирует пару "запрос-ответ" для корреляции. В отличие от x-ms-client-request-id, этот идентификатор не зависит от каких-либо сведений в запросе и уникален для каждого ответа.

Текст ответа HTTP (при сбое запроса)

При сбое запроса текст ответа HTTP будет документом JSON, отформатированным в соответствии с правилами OneApiErrors . Описание формата см. в OneApiErrors разделе 7.10.2 здесь. Ниже приведен пример такого сбоя.

{
    "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'"
        }
    }
}

Текст ответа HTTP (при успешном выполнении запроса)

При успешном выполнении запроса текст http-ответа будет массивом JSON, который кодирует результаты запроса.

Логически ответ версии 2 описывает объект DataSet , содержащий любое количество таблиц. Эти таблицы могут представлять фактические данные, запрашиваемые запросом, или дополнительные сведения о выполнении запроса (например, учет ресурсов, потребляемых запросом). Кроме того, фактический запрос может на самом деле завершиться ошибкой (из-за различных условий), даже если 200 OK возвращается состояние, и в этом случае ответ будет включать частичные данные ответа и указание на ошибки.

Физически массив JSON текста ответа представляет собой список объектов JSON, каждый из которых называется кадром. Объект DataSet кодируется в два кадра: DataSetHeader и DataSetCompletion. Первый всегда является первым кадром, а второй — последним кадром. Между ними можно найти кадры, описывающие объекты Table.

Объекты Table можно кодировать двумя способами:

Как один кадр: DataTable. Это значение по умолчанию.
Кроме того, в качестве "сочетания" из четырех типов кадров: TableHeader (который является первым и описывает таблицу), TableFragment (который описывает данные таблицы), TableProgress (который является необязательным и предоставляет оценку того, насколько далеко мы в данных таблицы) и TableCompletion (который является последним кадром таблицы).

Второй вариант называется "прогрессивным режимом" и отображается только в том случае, если свойству results_progressive_enabled запроса клиента задано значение true. В этом случае каждый кадр TableFragment описывает обновление данных, накопленных всеми предыдущими кадрами таблицы, либо как операцию добавления, либо как операцию замены. (Последний используется, например, когда некоторые длительные статистические вычисления выполняются на "верхнем уровне" запроса, поэтому начальный результат агрегирования заменяется более точными результатами позже.)

DataSetHeader

Кадр DataSetHeader всегда является первым в наборе данных и отображается ровно один раз.

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

Где:

Version — версия протокола. Текущая версия — v2.0.

IsProgressive — это логический флаг, указывающий, содержит ли этот набор данных прогрессивные кадры. Прогрессивный кадр является одним из следующих:

Frame	Описание
`TableHeader`	Содержит общие сведения о таблице.
`TableFragment`	Содержит прямоугольный сегмент данных таблицы.
`TableProgress`	Содержит ход выполнения в процентах (0–100)
`TableCompletion`	Указывает, что этот кадр является последним

Приведенные выше кадры описывают таблицу. Если для флага IsProgressive не задано значение true, каждая таблица в наборе будет сериализована с помощью одного кадра:

DataTable: содержит всю необходимую клиенту информацию об одной таблице в наборе данных.

TableHeader

Запросы, выполняемые с параметром results_progressive_enabled true, могут включать этот кадр. В соответствии с этой таблицей клиенты могут ожидать чередование кадров TableFragment и TableProgress . Окончательный кадр таблицы — TableCompletion.

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

Где:

TableId — уникальный идентификатор таблицы.
TableKind может принимать одно из следующих значений:
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- TableOfContents
- QueryProperties
- QueryPlan
- Неизвестно
TableName — это имя таблицы.
Columns — это массив, описывающий схему таблицы.

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

Поддерживаемые типы столбцов описаны здесь.

TableFragment

Кадр TableFragment содержит прямоугольный фрагмент данных таблицы. Помимо фактических данных, этот кадр также содержит TableFragmentType свойство, которое сообщает клиенту, что делать с фрагментом. Фрагмент добавляется к существующим фрагментам или заменяет их.

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

Где:

TableId — уникальный идентификатор таблицы.
FieldCount — количество столбцов в таблице.
TableFragmentType описывает, что клиент должен делать с этим фрагментом. TableFragmentType может принимать одно из следующих значений:
- DataAppend
- DataReplace
Rows — это двумерный массив, содержащий данные фрагмента.

TableProgress

Кадр TableProgress может чередуться с рамкой, описанной TableFragment выше. Его единственной целью является уведомление клиента о ходе выполнения запроса.

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

Где:

TableId — уникальный идентификатор таблицы.
TableProgress — это ход выполнения в процентах (0--100).

TableCompletion

Рамка TableCompletion помечает конец передачи таблицы. Больше не будут отправляться кадры, связанные с этой таблицей.

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

Где:

TableId — уникальный идентификатор таблицы.
RowCount — общее количество строк в таблице.

DataTable

Запросы, выданные с флагом EnableProgressiveQuery false, не будут содержать кадры (TableHeader, TableFragment, TableProgressи TableCompletion). Вместо этого каждая таблица в наборе данных будет передаваться с помощью DataTable кадра, содержащего всю необходимую клиенту информацию для чтения таблицы.

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

Где:

TableId — уникальный идентификатор таблицы.
TableKind может принимать одно из следующих значений:
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- QueryProperties
- QueryPlan
- Неизвестно
TableName — это имя таблицы.
Columns — это массив, описывающий схему таблицы и включающий:

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

Rows — это двумерный массив, содержащий данные таблицы.

Значение таблиц в ответе

PrimaryResult— main табличный результат запроса. Для каждого табличного выражения одна или несколько таблиц создаются в порядке, представляющего результаты, полученные оператором . Таких таблиц может быть несколько из-за пакетов и операторов вилки.
QueryCompletionInformation — предоставляет дополнительные сведения о выполнении самого запроса, например, успешно ли он выполнен или нет, а также о том, какие ресурсы были использованы запросом (аналогично таблице QueryStatus в ответе версии 1).
QueryProperties — предоставляет дополнительные значения, такие как клиентские инструкции визуализации (созданные, например, для отражения информации в операторе отрисовки) и сведения о курсоре базы данных .
QueryTraceLog — сведения журнала трассировки производительности (возвращаются, если perftrace в свойствах запроса клиента задано значение true).

DataSetCompletion

Кадр DataSetCompletion является последним в наборе данных.

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

Где:

HasErrors имеет значение true, если при создании набора данных произошли ошибки.
Cancelled Имеет значение true, если запрос, который привел к созданию набора данных, был отменен до завершения.
OneApiErrors возвращается, только если HasErrors имеет значение true. Описание формата см. в OneApiErrors разделе 7.10.2 здесь.

Share via

Http-ответ "Запрос версии 2"

Строка состояния HTTP-ответа

Заголовки HTTP-ответа

Текст ответа HTTP (при сбое запроса)

Текст ответа HTTP (при успешном выполнении запроса)

DataSetHeader

TableHeader

TableFragment

TableProgress

TableCompletion

DataTable

Значение таблиц в ответе

DataSetCompletion

Обратная связь

Обратная связь

Дополнительные ресурсы