查询/管理 HTTP 请求

项目
11/24/2023

请求谓词和资源

操作	HTTP 谓词	HTTP 资源
查询	GET	`/v1/rest/query`
查询	POST	`/v1/rest/query`
查询 v2	GET	`/v2/rest/query`
查询 v2	POST	`/v2/rest/query`
管理	POST	`/v1/rest/mgmt`

例如，若要将管理命令（“management”）发送到服务终结点，请使用以下请求行：

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

有关要包含的请求标头和正文，请参见下文。

请求标头

下表包含用于查询和管理操作的常用标头。

标准标头	说明	必需/可选
`Accept`	设置为 `application/json`	必须
`Accept-Encoding`	支持的编码为 `gzip` 和 `deflate`	可选
`Authorization`	请参阅身份验证	必须
`Connection`	建议启用 `Keep-Alive`	可选
`Content-Length`	建议在已知的情况下指定请求正文长度	可选
`Content-Type`	使用 `charset=utf-8` 将此项设置为 `application/json`	必须
`Expect`	可设置为 `100-Continue`	可选
`Host`	设置为请求所发送到的限定域名（例如，`help.chinaeast2.kusto.chinacloudapi.cn`）	必须

下表包含用于查询和管理操作的常用自定义标头。除非另有说明，否则这些标头仅用于遥测目的，而不会影响功能。

所有标头都是可选项。建议指定 x-ms-client-request-id 自定义标头。在某些情况下（例如取消正在运行的查询），此标头是必需的，因为它用于标识请求。

自定义标头	说明
`x-ms-app`	发出请求的应用程序的（易记）名称
`x-ms-user`	发出请求的用户的（易记）名称
`x-ms-user-id`	与 `x-ms-user` 相同
`x-ms-client-request-id`	请求的唯一标识符
`x-ms-client-version`	发出请求的客户端的（易记）版本标识符
`x-ms-readonly`	如果已指定此项，则强制请求以只读模式运行，以防止其进行持久更改

请求参数

以下参数可以在请求中传递。它们在请求中被编码为查询参数，或编码为正文的一部分，具体取决于是使用 GET 还是 POST。

参数	说明	必需/可选
`csl`	要执行的查询或管理命令的文本	必须
`db`	作用域中作为查询或管理命令目标的数据库的名称	对于某些管理命令是可选项。对于其他命令和所有查询是必需的。
`properties`	提供请求属性，以修改请求的处理方式及其结果。有关详细信息，请参阅请求属性	可选

GET 查询参数

使用 GET 时，请求的查询参数会指定请求参数。

正文

使用 POST 时，请求正文是以 UTF-8 编码的单个 JSON 文档，其中包含请求参数的值。

示例

此示例显示查询的 HTTP POST 请求。

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

请求标头

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.chinaeast2.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

请求正文

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

此示例演示如何使用 curl 创建用于发送上述查询的请求。

获取用于身份验证的令牌。

在设置了 Microsoft Entra 应用程序身份验证之后，将 AAD_TENANT_NAME_OR_ID、AAD_APPLICATION_ID 和 AAD_APPLICATION_KEY 替换为相关值

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

此代码片段将为你提供持有者令牌。

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in":"3599", 
  "expires_on":"1578439805",
  "not_before":"1578435905",
  "resource":"https://help.chinaeast2.kusto.chinacloudapi.cn",
  "access_token":"eyJ0...uXOQ"
}

在向查询终结点发送的请求中使用持有者令牌。

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.chinaeast2.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.chinaeast2.kusto.chinacloudapi.cn/v2/rest/query

根据此规范，读取响应。

设置客户端请求属性和查询参数

在以下示例正文中，csl 字段中的查询声明 n 和 d 这两个参数。这些查询参数的值在请求正文中 properties 字段下的 Parameters 字段中进行指定。 Options 字段定义客户端请求属性。

注意

非字符串和非长参数必须表示为字符串格式的 KQL 文本。

{
    "db": "Samples",
    "csl": "declare query_parameters (n:long, d:dynamic); StormEvents | where State in (d) | top n by StartTime asc",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        },
        "Parameters": {
            "n": 10, "d": "dynamic([\"ATLANTIC SOUTH\"])"
        }
    }
}

有关详细信息，请参阅查询参数。

查询/管理 HTTP 请求

请求谓词和资源

请求标头

请求参数

GET 查询参数

正文

示例

设置客户端请求属性和查询参数

其他资源