新增、更新或刪除掃描定義

發行項
08/14/2024

適用於：

想要體驗適用於端點的 Microsoft Defender 嗎？注册免費試用版。

想要體驗Microsoft Defender 弱點管理嗎？深入瞭解如何註冊 Microsoft Defender 弱點管理公開預覽試用版。

重要事項

本文中的部分資訊與發行前版本產品有關，在產品正式發行前可能會大幅度修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

注意事項

如果您是美國政府客戶，請使用適用於美國政府客戶的 Microsoft Defender 中所列的 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 的速率限制為每分鐘 100 次呼叫，每小時 1,500 次呼叫。

您可以根據您設定的保留期間，張貼在上次看到的計算機上。

權限

呼叫此 API 需要下列其中一個許可權。若要深入瞭解，包括如何選擇許可權，請參閱使用適用於端點的 Defender API。

許可權類型	權限	許可權顯示名稱
應用程式	Machine.ReadWrite.All	讀取和寫入所有掃描資訊。
委派 (公司或學校帳戶)	Machine.Read.Write	讀取和寫入所有掃描資訊。

注意事項

使用使用者認證取得權杖時：

若要檢視使用者至少必須具有下列角色許可權的數據： ViewData 或 TvmViewData (如需詳細資訊，請參閱建立和管理角色)
若要編輯數據，使用者至少必須具有下列角色許可權： ManageSecurity (如需詳細資訊，請參閱建立和管理角色)

HTTP 要求

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

要求標頭

名稱	類型	描述
授權	字串	持有人 {token}。必要。
Content-Type	字串	application/json。必要。

要求內文

在要求本文中，提供具有下列參數的 JSON 物件：

參數	Type	描述
scanType	Enum	掃描的類型。可能的值為：「Windows」、“Network” 必要。
scanName	字串	掃描的名稱。必要。
isActive	布林值	掃描是否正在執行的狀態。必要。
目標	字串	要掃描的目標逗號分隔清單，包括IP位址或主機名。必要。
intervalInHours	臨界值	掃描執行的間隔。必要。
targetType	字串	目標欄位中的目標類型。可能的類型為「IP 位址」或「主機名」。預設值為IP位址。必要。
scannerAgent	物件	計算機標識碼。必要。
scanAuthenticationParams	物件	代表驗證參數的物件，請參閱預期欄位的驗證參數物件屬性。建立新的掃描時，這個屬性是必要的，而且在更新掃描時是選擇性的。

回應

如果成功，這個方法會傳回 200 - 確定回應碼，以及回應本文中新的或更新的掃描定義。

新增掃描的範例要求

以下是新增掃描的要求範例。

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"],
}

提示

想要深入了解? 在我們的技術社群中與Microsoft安全性社群互動：Microsoft適用於端點的Defender技術社群。

共用方式為