ウイルス対策スキャン API を実行する

[アーティクル]
08/14/2024

適用対象:

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

注:

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

ヒント

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

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

API の説明

デバイスで Microsoft Defender ウイルス対策スキャンを開始します。

制限事項

この API のレート制限は、1 分あたり 100 呼び出しと 1 時間あたり 1500 呼び出しです。

注:

このページでは、API を使用したマシンアクションの実行に焦点を当てます。 Microsoft Defender for Endpoint を使用した応答アクション機能の詳細については、「コンピューターで応答アクションを実行する」を参照してください。

重要

このアクションは、Windows 10 バージョン 1709 以降および Windows 11 のデバイスで使用できます。
Microsoft Defender ウイルス対策スキャンは、Microsoft Defender ウイルス対策がアクティブなウイルス対策ソリューションであるかどうかに関係なく、他のウイルス対策ソリューションと共に実行できます。 Microsoft Defender ウイルス対策はパッシブモードにすることができます。詳細については、「Microsoft Defender ウイルス対策の互換性」を参照してください。

アクセス許可

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

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	Machine.Scan	'スキャンマシン'
委任 (職場または学校のアカウント)	Machine.Scan	'スキャンマシン'

注:

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

ユーザーには、少なくとも "アクティブな修復アクション" というロールアクセス許可が必要です (詳細については、「ロールの作成と管理」を参照してください)
ユーザーは、デバイスグループの設定に基づいてデバイスにアクセスできる必要があります (詳細については、「デバイスグループの作成と管理」を参照してください)

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

HTTP 要求

POST https://api.security.microsoft.com/api/machines/{id}/runAntiVirusScan

要求ヘッダー

名前	型	説明
Authorization	String	ベアラー {token}。必須。
Content-Type	string	application/json

要求本文

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

パラメーター	型	説明
コメント	文字列	アクションに関連付けるコメント。必須。
ScanType	String	スキャンの種類を定義します。必須。

ScanType は 実行するスキャンの種類を制御し、次のいずれかになります。

クイック: デバイスでクイックスキャンを実行する
Full: デバイスでフルスキャンを実行する

応答

成功した場合、このメソッドは応答本文に 201、Created 応答コード、 MachineAction オブジェクトを返します。

同じデバイスに対してウイルス対策スキャンを実行するために複数の API 呼び出しを送信すると、"アクションは既に進行中です" というメッセージが表示された "保留中のマシンアクション" または HTTP 400 が返されます。

例

要求

以下は、要求の例です。

POST https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runAntiVirusScan

{
  "Comment": "Check machine for viruses due to alert 3212",
  "ScanType": "Full"
}

ヒント

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

次の方法で共有