共用方式為

查詢/管理 HTTP 要求

  • 發行項

適用於： ✅Microsoft網狀架構✅Azure 數據總管

要求動詞和資源

動作 HTTP 指令動詞 HTTP 資源
Query GET /v1/rest/query
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 要求本文的媒體類型。 使用 charset=utf-8設定為 application/json 。 必要
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 是否使用 GET 或 POST，在要求中編碼為查詢參數或主體的一部分。

參數 描述 必要/選用
csl 要執行的查詢或管理命令文字。 必要
db 查詢或管理命令的目標資料庫名稱。 某些管理命令的選擇性。
所有查詢和其他所有指令都需要 。
properties 修改要求處理方式及其結果的要求屬性。 如需詳細資訊，請參閱 要求屬性。 選擇性

GET 查詢參數

使用 GET 要求時，查詢參數會指定要求參數。

本文

使用 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. 取得用於驗證的令牌。

    在設定 Microsoft Entra 應用程式驗證之後，以相關的值取代AAD_TENANT_NAME_OR_ID、 AAD_APPLICATION_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的兩個參數。 這些查詢參數的值會指定於 Parameters 要求本文中欄位底下的 properties 欄位內。 欄位 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"
        }
    }
}