查询/管理 HTTP 响应Query/management HTTP response

响应状态Response status

HTTP 响应状态行遵循 HTTP 标准响应代码的要求。The HTTP response status line follows the HTTP standard response codes. 例如,代码 200 指示成功。For example, code 200 indicates success.

当前使用了以下状态代码,但可能会返回任何有效的 HTTP 代码。The following status codes are currently in use, although any valid HTTP code may be returned.

代码Code 子代码Subcode 说明Description
100100 继续Continue 客户端可以继续发送请求。Client can continue to send the request.
200200 OKOK 请求已成功开始处理。Request started processing successfully.
400400 BadRequestBadRequest 请求格式不正确且已(永久)失败。Request is badly formed and failed (permanently).
401401 未授权Unauthorized 客户端需要先进行身份验证。Client needs to authenticate first.
403403 禁止Forbidden 客户端请求被拒绝。Client request is denied.
404404 NotFoundNotFound 请求引用了一个不存在的实体。Request references a non-existing entity.
413413 PayloadTooLargePayloadTooLarge 请求有效负载超出了限制。Request payload exceeded limits.
429429 TooManyRequestsTooManyRequests 由于限制,请求已被拒绝。Request has been denied because of throttling.
504504 超时Timeout 请求已超时。Request has timed out.
520520 ServiceErrorServiceError 服务处理请求时发现一个错误。Service found an error while processing the request.

备注

状态代码为 200 表明请求处理已成功开始,而不是已成功完成。The 200 status code shows that the request processing has successfully started, and not that it has successfully completed. 在处理请求期间在返回状态代码 200 之后发生的失败称为“部分查询失败”。在发生这种失败时,会将特殊指示符注入到响应流中,向客户端发出相应警报。Failures encountered during request processing after the 200 status code has returned are called "partial query failures", and when they are encountered, special indicators are injected into the response stream to alert the client that they occurred.

响应标头Response headers

将返回以下自定义标头。The following custom headers will be returned.

自定义标头Custom header 说明Description
x-ms-client-request-id 在具有相同名称的请求标头中发送的唯一请求标识符,或某个唯一标识符。The unique request identifier sent in the request header of the same name, or some unique identifier.
x-ms-activity-id 请求的全局唯一相关标识符。A globally unique correlation identifier for the request. 它是由服务创建的。It's created by the service.

响应正文Response body

如果状态代码为 200,则响应正文是一个 JSON 文档,该文档将查询或控制命令的结果编码为一个矩形表序列。If the status code is 200, the response body is a JSON document that encodes the query or control command's results as a sequence of rectangular tables. 有关详细信息,请参阅下文。See below for details.

备注

此表序列通过 SDK 反映。The sequence of tables is reflected by the SDK. 例如,使用 .NET Framework Kusto.Data 库时,表的序列将成为 SDK 返回的 System.Data.IDataReader 对象中的结果。For example, when using the .NET Framework Kusto.Data library, the sequence of tables then becomes the results in the System.Data.IDataReader object returned by the SDK.

如果状态代码指示了 401 之外的 4xx 或 5xx 错误,则响应正文是对失败详细信息进行了编码的 JSON 文档。If the status code indicates a 4xx or a 5xx error, other than 401, the response body is a JSON document that encodes the details of the failure. 有关详细信息,请参阅 Microsoft REST API 准则For more information, see Microsoft REST API Guidelines.

备注

如果请求中未包含 Accept 标头,则失败的响应正文不一定是 JSON 文档。If the Accept header is not included with the request, the response body of a failure is not necessarily a JSON document.

表序列的 JSON 编码JSON encoding of a sequence of tables

表序列的 JSON 编码是包含以下名称/值对的单个 JSON 属性包。The JSON encoding of a sequence of tables is a single JSON property bag with the following name/value pairs.

名称Name ValueValue
Tables 表属性包的数组。An array of the Table property bag.

表属性包具有以下名称/值对。The Table property bag has the following name/value pairs.

名称Name ValueValue
TableNameTableName 用于标识表的字符串。A string that identifies the table.
Columns 列属性包的数组。An array of the Column property bag.
“行”Rows 行数组的数组。An array of the Row array.

列属性包具有以下名称/值对。The Column property bag has the following name/value pairs.

名称Name ValueValue
ColumnNameColumnName 用于标识列的字符串。A string that identifies the column.
数据类型DataType 一个字符串,提供列的大致 .NET 类型。A string that provides the approximate .NET Type of the column.
ColumnTypeColumnType 一个字符串,提供列的标量数据类型A string that provides the scalar data type of the column.

行数组的顺序与相应列数组的顺序相同。The Row array has the same order as the respective Columns array. 行数组还有一个与相关列的行值相符的元素。The Row array also has one element that coincides with the value of the row for the relevant column. 不能用 JSON 表示的标量数据类型(例如 datetimetimespan)表示为 JSON 字符串。Scalar data types that can't be represented in JSON, such as datetime and timespan, are represented as JSON strings.

下面的示例显示了一个可能的此类对象,其中包含单个名为 Table_0 的表,该表具有类型为 string 的单个列 Text 以及单个行。The following example shows one possible such object, when it contains a single table called Table_0 that has a single column Text of type string, and a single row.

{
    "Tables": [{
        "TableName": "Table_0",
        "Columns": [{
            "ColumnName": "Text",
            "DataType": "String",
            "ColumnType": "string"
        }],
        "Rows": [["Hello, World!"]]
}

另一个示例:Another example:

此屏幕截图显示了一个 JSON 文件(包含一个表对象数组)的树视图。

响应中的表的含义The meaning of tables in the response

在大多数情况下,控制命令返回包含单个表的结果,其中包含由控制命令生成的信息。In most cases, control commands return a result with a single table, containing the information generated by the control command. 例如,.show databases 命令返回单个表,其中包含群集中所有可访问的数据库的详细信息。For example, the .show databases command returns a single table with the details of all accessible databases in the cluster.

查询通常会返回多个表。Queries generally return multiple tables. 对于每个表格表达式语句,将按顺序生成一个或多个表,表示该语句产生的结果。For each tabular expression statement, one or more tables are generated in-order, representing the results produced by the statement.

备注

由于存在批次分支运算符,可能会有多个这样的表。There can be multiple such tables because of batches and fork operators).

通常会生成三个表:Three tables are often produced:

  • @ExtendedProperties 表,提供附加的值,例如客户端可视化效果说明。An @ExtendedProperties table that provides additional values, such as client visualization instructions. 例如,生成这些值来反映 render 运算符数据库游标中的信息。These values are generated, for example, to reflect the information in render operator) and database cursor.

    此表包含 string 类型的单个列,其中包含类似于 JSON 的值:This table has a single column of type string, holding JSON-like values:

    ValueValue
    {"Visualization":"piechart",...}{"Visualization":"piechart",...}
    {"Cursor":"637239957206013576"}{"Cursor":"637239957206013576"}
  • QueryStatus 表,提供有关查询本身的执行的附加信息(例如,它是否已成功完成)以及查询使用的资源。A QueryStatus table that provides additional information about the execution of the query itself, such as, if it completed successfully or not, and what were the resources consumed by the query.

    此表具有以下结构:This table has the following structure:

    TimestampTimestamp severitySeverity SeverityNameSeverityName StatusCodeStatusCode StatusDescriptionStatusDescription 计数Count RequestIdRequestId ActivityIdActivityId SubActivityIdSubActivityId ClientActivityIdClientActivityId
    2020-05-02 06:09:12.70520772020-05-02 06:09:12.7052077 44 信息Info 00 查询已成功完成Query completed successfully 11 ...... ...... ...... ......

    严重性值为 2 或更小表示失败。Severity values of 2 or smaller indicate failure.

  • TableOfContents 表是最后创建的,它列出结果中的其他表。A TableOfContents table, which is created last, and lists the other tables in the results.

    下面是此表的一个示例:An example for this table is:

    OrdinalOrdinal 种类Kind 名称Name IDId PrettyNamePrettyName
    00 QueryResultQueryResult PrimaryResultPrimaryResult db9520f9-0455-4cb5-b257-53068497605adb9520f9-0455-4cb5-b257-53068497605a
    11 QueryPropertiesQueryProperties @ExtendedProperties 908901f6-5319-4809-ae9e-009068c267c7908901f6-5319-4809-ae9e-009068c267c7
    22 QueryStatusQueryStatus QueryStatusQueryStatus 00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000