通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

查询/管理 HTTP 请求

  • 项目

适用于：✅Microsoft Fabric✅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.kusto.windows.net/v1/rest/mgmt HTTP/1.1

请参阅 请求标头 和 正文 ，了解要包含的内容。

请求标头

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

标准标头 说明 必需/可选
Accept 客户端接收的媒体类型。 设置为 application/json。 必须
Accept-Encoding 支持的内容编码。 支持的编码为 gzip 和 deflate。 可选
Authorization 身份验证凭据。 有关详细信息，请参阅 身份验证。 必须
Connection 连接是否在操作后保持打开状态。 建议设置为 Connection Keep-Alive. 可选
Content-Length 请求正文的大小。 指定已知时的请求正文长度。 可选
Content-Type 请求正文的媒体类型。 设置为 application/json . charset=utf-8. 必须
Expect 来自服务器的预期响应。 它可以设置为 100-Continue. 可选
Host 请求发送到的限定域名。 例如，help.kusto.windows.net。 必须

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

所有标头都是可选项。 但是，我们建议指定 x-ms-client-request-id 自定义标头。 在某些情况下（例如取消正在运行的查询）是必需的， 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 请求时，查询参数指定请求参数。

Body

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

示例

以下示例显示了查询的 HTTP POST 请求。

POST https://help.kusto.windows.net/v2/rest/query HTTP/1.1

请求标头

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.windows.net
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. 获取用于身份验证的令牌。

    AAD_APPLICATION_ID设置 Microsoft Entra 应用程序身份验证后，替换AAD_TENANT_NAME_OR_ID相关值，并将其AAD_APPLICATION_KEY替换为相关值。

    curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
  -F "grant_type=client_credentials" \
  -F "resource=https://help.kusto.windows.net" \
  -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.kusto.windows.net",
  "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.kusto.windows.net" \
-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.windows.net/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\"])"
        }
    }
}

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

发送显示数据库缓存策略命令

以下示例发送一个请求来显示 Samples 数据库缓存策略。


{
    "db": "Samples",
    "csl": ".show database Samples policy caching",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        }
    }
}