クエリ/管理の HTTP 応答

  • [アーティクル]

応答の状態

HTTP 応答状態の行は、HTTP 標準の応答コードに従います。 たとえば、コード 200 は成功を示しています。

現在は次の状態コードが使用されていますが、有効な HTTP コードであればどのようなものでも返される可能性があります。

コード サブコード 説明
100 Continue クライアントは引き続き要求を送信できます。
200 OK 要求の処理が正常に開始しました。
400 BadRequest 要求の形式が正しくないため、失敗しました(完全に)。
401 権限がありません 先にクライアントを認証する必要があります。
403 Forbidden クライアント要求が拒否されました。
404 NotFound 要求は、存在しないエンティティを参照します。
413 PayloadTooLarge 要求ペイロードが制限を超えました。
429 TooManyRequests スロットリングにより、要求が拒否されました。
504 タイムアウト 要求がタイムアウトしました。
520 ServiceError サービスが要求の処理中にエラーを検出しました。

Note

200 状態コードは、要求処理が正常に開始したことを示すものであり、正常に完了したことを示すものではありません。 200 状態コードが返された後に要求の処理中に発生したエラーは「部分的なクエリエラー」と呼ばれ、このエラーが発生すると、エラーの発生をクライアントに通知するための特別なインジケーターが応答ストリームに挿入されます。

応答ヘッダー

次のカスタム ヘッダーが返されます。

カスタム ヘッダー 説明
x-ms-client-request-id 同じ名前の要求ヘッダーで送信された一意の要求識別子、または何らかの一意の識別子。
x-ms-activity-id 要求に対するグローバルで一意の相関識別子です。 サービスによって作成されます。

応答本文

状態コードが 200 の場合、応答本文は、クエリまたは管理コマンドの結果を一連の四角形のテーブルとしてエンコードする JSON ドキュメントです。 詳細については、以下参照してください。

Note

テーブルのシーケンスは、SDK によって反映されます。 たとえば、.NET Framework Kusto. Data ライブラリを使用すると、テーブルのシーケンスが SDK によって返されるオブジェクト System.Data.IDataReader の結果になります。

状態コードが 4xx または5xx エラー (401 以外) を示している場合、応答本文はエラーの詳細をエンコードする JSON ドキュメントです。 詳細については、「Microsoft Sentinel REST API ガイドライン」を参照してください。

Note

Acceptヘッダーが要求に含まれていない場合、エラーの応答本文は必ずしも JSON ドキュメントであるとは限りません。

テーブルのシーケンスの JSON エンコード

テーブルのシーケンスの JSON エンコードは、次の名前/値のペアを持つ単一の JSON プロパティ バッグです。

名前 値
テーブル Table プロパティ バッグの配列。

Table プロパティ バッグには、次の名前/値のペアがあります。

名前 値
TableName テーブルを識別する文字列。
[列] 列プロパティ バッグの配列。
行 Row 配列の配列。

Column プロパティ バッグには、次の名前/値のペアがあります。

名前 値
ColumnName 列を識別する文字列。
DataType 列の .NET の概数型を提供する文字列。
[列の型] 列のスカラー データ型を提供する文字列。

Row 配列は、それぞれの Columns 配列と同じ順序になります。 また、Row 配列には、関連する列の行の値と一致する要素が1つあります。 datetime や timespan などの JSON で表現できないスカラー データ型は、JSON 文字列として表現されます。

次の例では、型 string の1 つの列 Text と1つの行を持つ1 つのテーブルTable_0 が含まれている場合の、このようなオブジェクトの一例を示しています。

{
    "Tables": [{
        "TableName": "Table_0",
        "Columns": [{
            "ColumnName": "Text",
            "DataType": "String",
            "ColumnType": "string"
        }],
        "Rows": [["Hello, World!"]]
}

別の例を示します。

Table オブジェクトの配列を含む JSON ファイルのツリー ビューを示すスクリーンショット。

応答内のテーブルの意味

ほとんどの場合、管理コマンドは、管理コマンドによって生成された情報を含む 1 つのテーブルで結果を返します。 たとえば、 .show databases コマンドは、クラスター内のすべてのアクセス可能なデータベースの詳細を含む 1 つのテーブルを返します。

通常、クエリは複数のテーブルを返します。 各表形式ステートメントでは、ステートメントによって生成される結果を表す 1 つまたは複数のテーブルが順に生成されます。

Note

バッチおよび fork 演算子により、このようなテーブルが複数存在する場合があります)。

多くの場合、次の3つのテーブルが生成されます。

  • クライアントの視覚化の指示 ( レンダー演算子によって提供される情報)、クエリの有効な データベースカーソルに関する情報、クエリ結果キャッシュの有効な使用方法などの追加の値を提供する @ExtendedProperties テーブル。

    v1 プロトコルを使用して送信されたクエリの場合、テーブルには型 string の 1 つの列があり、その値は JSON でエンコードされた文字列です。次に例を示します。

    値
    {"Visualization":"piechart",...}
    {"Cursor":"637239957206013576"}

    v2 プロトコルを使用して送信されるクエリの場合、テーブルには次の 3 つの列があります。(1) レコードが適用される結果セット内のテーブルを示す integer という列 TableId。(2) レコードによって提供される情報の種類を示す string という列 Key (指定できる値: Visualization、 ServerCache、および Cursor)。(3) キーによって決定された情報を提供する dynamic という列 Value。

    TableId キー 値
    1 ServerCache {"OriginalStartedOn":"2021-06-11T07:48:34.6201025Z",...}
    1 グラフ {"Visualization":"piechart",...}

  • QueryStatus テーブルは、クエリ自体の実行に関する追加情報を提供します。たとえば、正常に完了したかどうかや、クエリで消費されたリソースなどです。

    テーブルの構造は次のとおりです。

    Timestamp 重大度 SeverityName StatusCode StatusDescription Count RequestId ActivityId SubActivityId ClientActivityId
    2020-05-02 06:09:12.7052077 4 Info 0 クエリが正常に完了しました 1 ... ... ... ...

    重大度の値が 2 以下の場合は、失敗を示します。

  • 最後に作成され、結果の他のテーブルが一覧表示される TableOfContents テーブル。

    この表の例を次に示します。

    Ordinal 種類 名前 Id PrettyName
    0 QueryResult PrimaryResult db9520f9-0455-4cb5-b257-53068497605a
    1 QueryProperties @ExtendedProperties 908901f6-5319-4809-ae9e-009068c267c7
    2 QueryStatus QueryStatus 00000000-0000-0000-0000-000000000000