高度な追求 API

  • 適用対象: Microsoft Defender for Endpoint

警告

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

Microsoft Defender for Endpoint高度なハンティング API は、高度なハンティング機能を含む Microsoft Graph セキュリティ API に移行しています。 Microsoft Graph セキュリティ API は、より広範なデータ カバレッジ、一貫性の向上、自動化とセキュリティ ワークフローのスケーラビリティの向上を提供します。 2026 年 1 月に廃止が開始されました。 提供終了が完了すると、Microsoft Defender for Endpoint高度なハンティング API は機能しなくなります。 提供終了のタイムラインについては、 MC1220762を参照してください。 移行に役立つ詳細については、「Microsoft Graph セキュリティ API の使用」を参照してください。

注:

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

ヒント

パフォーマンスを向上させるには、api.security.microsoft.com を使用する代わりに、位置情報に近いサーバーを使用します。

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com
  • aea.api.security.microsoft.com

制限事項

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

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

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

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

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

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

  • 1 つの要求のクエリ結果の最大サイズは 50 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 ロールを割り当てる必要があります。

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

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

HTTP 要求

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

要求ヘッダー

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

要求本文

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

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

応答

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

例

要求の例

要求の例を次に示します。

POST https://api.security.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) にご参加ください。

  • Last updated on