查询 V2 HTTP 响应

适用于:✅Azure 数据资源管理器

HTTP 响应状态行

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

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

注意

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

HTTP 响应标头

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

  1. x-ms-client-request-id:服务返回一个不透明字符串,以标识用于关联目的的请求/响应对。 如果请求包含客户端请求 ID,则其值将在此处显示,否则将返回某个随机字符串。

  2. 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 对象编码为两个帧 :DataSetHeaderDataSetCompletion。 前者始终是第一个帧,而后者始终是最后一个帧。 在它们“之间”,可以找到描述 Table 对象的帧。

可以通过两种方式对 Table 对象进行编码:

  1. 作为单个帧:DataTable。 这是默认设置。

  2. 或者,作为四种帧的“混合”: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,则进行的查询可能包含此帧。 根据此表,客户端可以期望得到一个包含 TableFragmentTableProgress 帧的交织序列。 表的最后一帧是 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 时,发出的查询将不包括任何帧(TableHeaderTableFragmentTableProgressTableCompletion)。 相反,数据集中的每个表都将使用 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 部分。