次の方法で共有

クエリ/管理の HTTP 要求

  • [アーティクル]

要求動詞とリソース

アクション HTTP 動詞 HTTP リソース
クエリ GET /v1/rest/query
クエリ POST /v1/rest/query
Query v2 GET /v2/rest/query
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 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-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.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、、および AAD_APPLICATION_KEY は、アプリケーション認証を設定した後、関連する値Microsoft Entra置き換えますAAD_TENANT_NAME_OR_ID

    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 と dという名前nの 2 つのパラメーターが宣言されています。 これらのクエリ パラメーターの値は、要求本文の 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\"])"
        }
    }
}

詳細については、「 クエリ パラメーター」を参照してください。