通过

查询/管理 HTTP 请求

  • 项目

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

请求谓词和资源

操作 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 创建用于发送上述查询的请求。

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

    在设置了 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"
}

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

    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

  3. 根据此规范，读取响应。

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

在以下示例正文中，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\"])"
        }
    }
}

有关详细信息，请参阅支持的请求属性。