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

Переключение служб с помощью раскрывающегося списка версий . Дополнительные сведения о навигации.
Область применения: ✅ Microsoft Fabric ✅ Azure Data Explorer

Строка состояния ответа 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.

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

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

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

DataSetHeader

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

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

Where:

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

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

Рамка	Description
`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,
}

Where:

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
}

Where:

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

TableProgresss

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

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

Where:

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

TableCompletion

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

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

Where:

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

DataTable

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

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

Where:

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

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

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

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

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

DataSetCompletion

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

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

Where:

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-02-05

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

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

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

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

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

DataSetHeader

TableHeader

TableFragment

TableProgresss

TableCompletion

DataTable

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

DataSetCompletion

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

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