查询/管理 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/json Set to application/json |
必须Required |
Accept-Encoding |
支持的编码为 gzip 和 deflate Supported encodings are gzip and deflate |
可选Optional |
Authorization |
请参阅身份验证See authentication | 必须Required |
Connection |
建议启用 Keep-Alive We 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/json Set to application/json with charset=utf-8 |
必须Required |
Expect |
可设置为 100-Continue Can be set to 100-Continue |
可选Optional |
Host |
设置为请求所发送到的限定域名(例如,help.kusto.chinacloudapi.cn )Set 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.
获取用于身份验证的令牌。Obtain a token for authentication.
在设置了 AAD 应用程序身份验证之后,将
AAD_TENANT_NAME_OR_ID
、AAD_APPLICATION_ID
和AAD_APPLICATION_KEY
替换为相关值ReplaceAAD_TENANT_NAME_OR_ID
,AAD_APPLICATION_ID
, andAAD_APPLICATION_KEY
with the relevant values, after having set up AAD application authenticationcurl "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" }
在向查询终结点发送的请求中使用持有者令牌。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
根据此规范,读取响应。Read the response according to this specification.