查询/管理 HTTP 请求Query/management HTTP request

请求谓词和资源Request verb and resource

操作Action HTTP 谓词HTTP verb HTTP 资源HTTP resource
查询Query GETGET /v1/rest/query
查询Query POSTPOST /v1/rest/query
查询 v2Query v2 GETGET /v2/rest/query
查询 v2Query v2 POSTPOST /v2/rest/query
管理Management POSTPOST /v1/rest/mgmt

例如,若要将控制命令(“management”)发送到服务终结点,请使用以下请求行:For example, to send a control command ("management") to a service endpoint, use the following request line:

POST https://help.kusto.chinacloudapi.cn/v1/rest/mgmt HTTP/1.1

有关要包含的请求标头和正文,请参见下文。See below for the request headers and body to include.

请求标头Request headers

下表包含用于查询和管理操作的常用标头。The following table contains the common headers used for query and management operations.

标准标头Standard header 说明Description 必需/可选Required/Optional
Accept 设置为 application/jsonSet to application/json 必须Required
Accept-Encoding 支持的编码为 gzipdeflateSupported encodings are gzip and deflate 可选Optional
Authorization 请参阅身份验证See authentication 必须Required
Connection 建议启用 Keep-AliveWe recommend that you enable Keep-Alive 可选Optional
Content-Length 建议在已知的情况下指定请求正文长度We recommend that you specify the request body length when known 可选Optional
Content-Type 使用 charset=utf-8 将此项设置为 application/jsonSet to application/json with charset=utf-8 必须Required
Expect 可设置为 100-ContinueCan be set to 100-Continue 可选Optional
Host 设置为请求所发送到的限定域名(例如,help.kusto.chinacloudapi.cnSet to the qualified domain name that the request was sent to (for example, help.kusto.chinacloudapi.cn) 必须Required

下表包含用于查询和管理操作的常用自定义标头。The following table contains the common custom headers used for query and management operations. 除非另有说明,否则这些标头仅用于遥测目的,而不会影响功能。Unless otherwise indicated, these headers are used for telemetry purposes only, and have no functionality impact.

所有标头都是可选项。All headers are optional. 建议指定 x-ms-client-request-id 自定义标头。We recommend that you specify the x-ms-client-request-id custom header. 在某些情况下(例如取消正在运行的查询),此标头是必需的,因为它用于标识请求。In some scenarios, such as canceling a running query, this header is required because it's used to identify the request.

自定义标头Custom header 说明Description
x-ms-app 发出请求的应用程序的(易记)名称The (friendly) name of the application making the request
x-ms-user 发出请求的用户的(易记)名称The (friendly) name of the user making the request
x-ms-user-id x-ms-user 相同Same as x-ms-user
x-ms-client-request-id 请求的唯一标识符A unique identifier for the request
x-ms-client-version 发出请求的客户端的(易记)版本标识符The (friendly) version identifier for the client making the request
x-ms-readonly 如果已指定此项,则强制请求以只读模式运行,以防止其进行持久更改If specified, forces the request to run in read-only mode, preventing it from making long-lasting changes

请求参数Request parameters

以下参数可以在请求中传递。The following parameters can be passed in the request. 它们在请求中被编码为查询参数,或编码为正文的一部分,具体取决于是使用 GET 还是 POST。They're encoded in the request as query parameters or as part of the body, depending on whether GET or POST is used.

参数Parameter 说明Description 必需/可选Required/Optional
csl 要执行的查询或控制命令的文本Text of the query or control command to execute 必须Required
db 作用域中作为查询或控制命令目标的数据库的名称Name of the database in scope that is the target of the query or control command 对于某些控制命令是可选的。Optional for some control commands.
对于其他命令和所有查询是必需的。Required for other commands and all queries.
properties 提供客户端请求属性,这些属性修改请求的处理方式及其结果。Provides client request properties that modify how the request is processed and its results. 有关详细信息,请参阅客户端请求属性For more information, see client request properties 可选Optional

GET 查询参数GET query parameters

使用 GET 时,请求的查询参数会指定请求参数。When GET is used, the query parameters of the request specify the request parameters.

正文Body

使用 POST 时,请求正文是以 UTF-8 编码的单个 JSON 文档,其中包含请求参数的值。When POST is used, the body of the request is a single JSON document encoded in UTF-8, with the values of the request parameters.

示例Examples

此示例显示查询的 HTTP POST 请求。This example shows the HTTP POST request for a query.

POST https://help.kusto.chinacloudapi.cn/v2/rest/query HTTP/1.1

请求标头Request headers

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.chinacloudapi.cn
x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1
x-ms-user-id: EARTH\davidbg
x-ms-app: MyApp

请求正文Request body

{
  "db":"Samples",
  "csl":"print Test=\"Hello, World!\"",
  "properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"
}

此示例演示如何使用 curl 创建用于发送上述查询的请求。This example shows how to create a request that sends the query above, using curl.

  1. 获取用于身份验证的令牌。Obtain a token for authentication.

    在设置了 AAD 应用程序身份验证之后,将 AAD_TENANT_NAME_OR_IDAAD_APPLICATION_IDAAD_APPLICATION_KEY 替换为相关值Replace AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_ID, and AAD_APPLICATION_KEY with the relevant values, after having set up AAD application authentication

    curl "https://login.partner.microsoftonline.cn/AAD_TENANT_NAME_OR_ID/oauth2/token" \
      -F "grant_type=client_credentials" \
      -F "resource=https://help.kusto.chinacloudapi.cn" \
      -F "client_id=AAD_APPLICATION_ID" \
      -F "client_secret=AAD_APPLICATION_KEY"
    

    此代码片段将为你提供持有者令牌。This code snippet will provide you with the bearer token.

    {
      "token_type": "Bearer",
      "expires_in": "3599",
      "ext_expires_in":"3599", 
      "expires_on":"1578439805",
      "not_before":"1578435905",
      "resource":"https://help.kusto.chinacloudapi.cn",
      "access_token":"eyJ0...uXOQ"
    }
    
  2. 在向查询终结点发送的请求中使用持有者令牌。Use the bearer token in your request to the query endpoint.

    curl -d '{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"}}"}"' \
    -H "Accept: application/json" \
    -H "Authorization: Bearer eyJ0...uXOQ" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Host: help.kusto.chinacloudapi.cn" \
    -H "x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
    -H "x-ms-user-id: EARTH\davidbg" \
    -H "x-ms-app: MyApp" \
    -X POST https://help.kusto.chinacloudapi.cn/v2/rest/query
    
  3. 根据此规范,读取响应。Read the response according to this specification.