次の方法で共有

スキャン定義を追加、更新、または削除する

  • [アーティクル]

適用対象:

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

Microsoft Defender 脆弱性の管理を体験するには Microsoft Defender 脆弱性の管理パブリック プレビュー試用版にサインアップする方法について説明します。

重要

この記事の一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここで提供されるいかなる情報に関して、明示または黙示を問わず、いかなる保証も行いません。

注:

米国政府機関のお客様は、 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 の説明

認証されたスキャンを追加、更新、または削除する API。

制限事項

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

構成した保有期間に従って、最後に表示されたマシンに投稿できます。

アクセス許可

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

アクセス許可の種類 アクセス許可 アクセス許可の表示名
アプリケーション Machine.ReadWrite.All すべてのスキャン情報を読み書きします。
委任 (職場または学校のアカウント) Machine.Read.Write すべてのスキャン情報を読み書きします。

注:

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

  • データを表示するには、ユーザーが少なくとも次のロールアクセス許可を持っている必要があります: ViewData または TvmViewData (詳細については、「 ロールの作成と管理 」を参照してください)
  • データを編集するには、ユーザーが少なくとも次のロールのアクセス許可を持っている必要があります: ManageSecurity (詳細については、「 ロールの作成と管理 」を参照してください)

HTTP 要求

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

要求ヘッダー

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

要求本文

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

パラメーター 型 説明
scanType 列挙 スキャンの種類。 使用可能な値は、"Windows"、"ネットワーク" です。 必須。
scanName String スキャンの名前。 必須。
isActive ブール型 スキャンがアクティブに実行されているかどうかを示す状態。 必須。
target String スキャンするターゲットのコンマ区切りのリスト (IP アドレスまたはホスト名)。 必須。
intervalInHours Int スキャンを実行する間隔。 必須。
targetType String ターゲット フィールドのターゲットの種類。 使用可能な種類は、"IP アドレス" または "ホスト名" です。 既定値は IP アドレスです。 必須。
scannerAgent オブジェクト マシン ID。 必須です。
scanAuthenticationParams オブジェクト 認証パラメーターを表すオブジェクトについては、「想定されるフィールドの 認証パラメーター オブジェクトのプロパティ 」を参照してください。 このプロパティは、新しいスキャンを作成するときに必須であり、スキャンを更新する場合は省略可能です。

応答

成功した場合、このメソッドは 200 - Ok 応答コードと、応答本文の新しいスキャン定義または更新されたスキャン定義を返します。

新しいスキャンを追加する要求の例

新しいスキャンを追加する要求の例を次に示します。

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

 {
"scanType": "Windows", 
"scanName": "Test Windows scan", 
"isActive": true, 
"target": "127.0.0.1", 
"intervalInHours": 1, 
"targetType": "Ip",
"scannerAgent": {
    "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
}

応答の例

応答の例を下に示します。

 {
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Windows scan",
    "isActive": true,
    "target": "127.0.0.1",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "username@test.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }

}

スキャンを更新する要求の例

スキャンを更新する要求の例を次に示します。

PATCH  https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca 

{
"scanName": "Test Update Windows scan", 
"isActive": false, 
"target": "127.0.0.2,127.0.0.3", 
"intervalInHours": 1, 
"targetType": "Ip",
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
 }

応答の例

応答の例を下に示します。

{
    "@odata.context": "https://localhost:1059/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Update Windows scan",
    "isActive": false,
    "target": "127.0.0.2,127.0.0.3",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "userName@microsoft.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }
}

スキャンを削除する要求の例

スキャンを削除する要求の例を次に示します。

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/BatchDelete

{
  "ScanDefinitionIds": ["td32f17af-5cc2-4e4e-964a-4c4ef7d216e2", "ab32g20af-5dd2-4a5e-954a-4c4ef7d216e2"],
}

ヒント

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