高度な追求 API

  • [アーティクル]

適用対象:

警告

この高度なハンティング API は、機能が制限された古いバージョンです。 より多くのテーブルを照会できる高度なハンティング API のより包括的なバージョンは、 Microsoft Graph セキュリティ API で既に使用できます。 「Microsoft Graph セキュリティ API を使用した高度なハンティング」を参照してください

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

注:

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

ヒント

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

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

制限事項

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

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

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

    • API 呼び出し: 1 分あたり最大 45 呼び出し、1 時間あたり最大 1,500 呼び出し。
    • 実行時間: 1 時間ごとに 10 分の実行時間、1 日に 3 時間の実行時間。

  4. 1 つの要求の最大実行時間は 200 秒です。

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

  6. 1 つの要求のクエリ結果の最大サイズは 124 MB を超えることはできません。 超過した場合、HTTP 400 Bad Request とメッセージ "クエリの実行が許可された結果サイズを超えました。 結果の数を制限してクエリを最適化し、再試行してください" が発生します。

アクセス許可

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

アクセス許可の種類 アクセス許可 アクセス許可の表示名
アプリケーション AdvancedQuery.Read.All Run advanced queries
委任 (職場または学校のアカウント) AdvancedQuery.Read Run advanced queries

注:

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

  • ユーザーは、Microsoft Entra IDでロールをView Data割り当てる必要があります
  • ユーザーは、デバイス グループの設定に基づいてデバイスにアクセスする必要があります (詳細については、「デバイス グループのCreateと管理」を参照してください)

デバイス グループの作成は、Defender for Endpoint プラン 1 とプラン 2 でサポートされています。

HTTP 要求

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

要求ヘッダー

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

要求本文

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

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

応答

成功した場合、このメソッドは応答本文で 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"
        }
    ]
}

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティ (Microsoft Defender for Endpoint Tech Community) にご参加ください。