高度なハンティング API

適用対象:

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

注意

米国政府機関のお客様の場合は、Microsoft Defender for Endpointに記載されている URI を米国政府機関のお客様に使用してください。

ヒント

パフォーマンスを向上させるために、地理的な場所に近いサーバーを使用できます。

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

制限事項

  1. 過去 30 日間のデータに対してのみクエリを実行できます。

  2. 結果には最大 100,000 行が含まれます。

  3. テナントごとに実行回数が制限されます。

    • API 呼び出し: 1 分あたり最大 45 回の呼び出し、1 時間あたり最大 1500 回の呼び出し。
    • 実行時間: 1 時間ごとに実行時間が 10 分、実行時間が 1 日に 3 時間です。
  4. 1 つの要求の最大実行時間は 10 分です。

  5. 429 応答は、要求の数または CPU によってクォータ制限に達することを表します。 応答本文を読み取って、どの制限に達したかを理解します。

  6. 1 つの要求のクエリ結果の最大サイズは 124 MB を超えることはできません。 超過した場合は、"クエリの実行が許可された結果サイズを超えました。 結果の量を制限してクエリを最適化し、もう一度やり直してください"と表示されます。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法など、詳細については、「Microsoft Defender for Endpoint API の使用」を参照してください。

アクセス許可の種類 アクセス許可 アクセス許可の表示名
アプリケーション AdvancedQuery.Read.All '高度なクエリを実行する'
委任 (職場または学校のアカウント) AdvancedQuery.Read '高度なクエリを実行する'

注意

ユーザー資格情報を使用してトークンを取得する場合:

  • ユーザーが "データの表示" AD ロールを持っている必要がある
  • ユーザーは、デバイス グループの設定に基づいてデバイスにアクセスできる必要があります (詳細については、「 デバイス グループの作成と管理 」を参照してください)

HTTP 要求

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

要求ヘッダー

ヘッダー
Authorization ベアラー {token}。 必須
Content-Type application/json

要求本文

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。

パラメーター 種類 説明
Query テキスト 実行するクエリ。 必須

応答

成功した場合、このメソッドは 200 OK を返し、応答本文で QueryResponse オブジェクトを返します。

要求の例

以下は、要求の例です。

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run
{
    "Query":"DeviceProcessEvents
|where InitiatingProcessFileName =~ 'powershell.exe'
|where ProcessCommandLine contains 'appdata'
|project Timestamp, FileName, InitiatingProcessFileName, DeviceId
|limit 2"
}

応答の例

以下は、応答の例です。

注意

簡潔にするために、ここに示す応答オブジェクトが切り捨てられる場合があります。 実際の呼び出しではすべてのプロパティが返されます。

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}