查询 V2 HTTP 响应

项目
01/27/2024

HTTP 响应状态行

如果请求成功，则 HTTP 响应状态代码为 200 OK。 HTTP 响应正文是一个 JSON 数组，如下所述。

如果请求失败，则 HTTP 响应状态代码为 4xx 或 5xx 错误。原因短语将包含有关失败的更多信息。 HTTP 响应正文是一个 JSON 对象，如下所述。

注意

请求可能返回状态代码“200 OK”，但 HTTP 响应正文将指示错误。如果在已返回 HTTP 状态行后引发错误，则可能发生这种情况。阅读者应明确地检查是否存在这种情况。

HTTP 响应标头

无论请求是成功还是失败，响应中都包含两个自定义 HTTP 标头：

x-ms-client-request-id：服务返回一个不透明字符串，以标识用于关联目的的请求/响应对。如果请求包含客户端请求 ID，则其值将在此处显示，否则将返回某个随机字符串。
x-ms-activity-id：服务返回一个不透明字符串，以唯一标识用于关联目的的请求/响应对。与 x-ms-client-request-id 不同，此标识符不受请求中任何信息影响，并且每个响应也是唯一的。

HTTP 响应正文（请求失败时）

请求失败时，HTTP 响应正文是一个根据 OneApiErrors 规则设置格式的 JSON 文档。有关 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 数组。

从逻辑上讲，V2 响应描述一个 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 是表的唯一 ID。
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 是表的唯一 ID。
FieldCount 是表中的列数。
TableFragmentType 描述客户端应如何处理此片段。 TableFragmentType 是下列项之一：
- DataAppend
- DataReplace
Rows 是包含片段数据的二维数组。

TableProgress

TableProgress 帧可以与上面所述的 TableFragment 帧交织出现。其唯一用途是告知客户端查询进度。

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

其中：

TableId 是表的唯一 ID。
TableProgress 是以百分比表示的进度 (0-100)。

TableCompletion

TableCompletion 帧标记表传输的结束。不会再发送与该表相关的帧。

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

其中：

TableId 是表的唯一 ID。
RowCount 是表中的总行数。

DataTable

当 EnableProgressiveQuery 标志设置为 false 时，发出的查询将不包括任何帧（TableHeader、TableFragment、TableProgress 和 TableCompletion）。相反，数据集中的每个表都将使用 DataTable 帧进行传输，该帧包含客户端读取该表需要的所有信息。

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

其中：

TableId 是表的唯一 ID。
TableKind 是下列项之一：
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- QueryProperties
- QueryPlan
- 未知
TableName 是表的名称。
Columns 是描述表的架构的数组，并且包括：

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

Rows 是包含表的数据的二维数组。

响应中的表的含义

PrimaryResult - 查询的主要表格结果。对于每个表格表达式语句，将按顺序生成一个或多个表，表示该语句产生的结果。由于存在批次和分支运算符，可能会有多个这样的表。
QueryCompletionInformation - 提供有关查询本身的执行的附加信息（例如，它是否已成功完成）以及查询使用的资源（类似于 v1 响应中的 QueryStatus 表）。
QueryProperties - 提供附加值，如客户端可视化效果说明（例如，发出这些说明以反映 render 运算符中的信息）和数据库游标信息。
QueryTraceLog - 性能跟踪日志信息（当客户端请求属性中的 perftrace 设置为 true 时返回）。

DataSetCompletion

DataSetCompletion 帧是数据集中的最后一帧。

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

其中：

如果生成数据集时出现错误，则 HasErrors 为 true。
如果导致生成数据集的请求在完成前被取消，则 Cancelled 为 true。
只有 HasErrors 为 true 时才会返回 OneApiErrors。有关 OneApiErrors 格式的说明，请参阅此处的 7.10.2 部分。