在裝置上執行即時回應命令
適用於：
重要事項
本文中的部分資訊與發行前版本產品有關，在產品正式發行前可能會大幅度修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。
想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。
注意事項
如果您是美國政府客戶，請使用 適用於美國政府客戶的 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 的速率限制是每分鐘 10 次呼叫， (HTTP 429) 回應其他要求。
25 個同時執行的會話 (超過節流限制的要求會收到「429 - 太多要求」回應) 。
如果計算機無法使用，會話會排入佇列最多三天。
RunScript 命令在 10 分鐘後逾時。
實時回應命令無法排入佇列，一次只能執行一個。
如果您嘗試執行此 API 呼叫的電腦位於未指派自動化補救層級的 RBAC 裝置群組中，您至少需要為指定的裝置群組啟用最低補救層級。
注意事項
適用於端點的Defender方案1和方案2支援裝置群組建立。
您可以在單一 API 呼叫上執行多個即時回應命令。 不過，當即時回應命令失敗時，將不會執行所有後續動作。
如果即時回應動作已在執行中，則無法在同一部計算機上執行多個實時回應會話 (後續要求會使用 HTTP 400 - ActiveRequestAlreadyExists) 來回應。
注意事項
計算機 API 中無法使用從 [裝置] 頁面起始的即時回應動作。
最低需求
在裝置上起始會話之前，請確定您符合下列需求：
確認您執行的是支援的 Windows、macOS 或 Linux 版本。
裝置必須執行下列其中一項：
Windows 11
Windows 10
- 版本 1909 或更新版本
- 具有 KB4515384的 1903版
- 版本 1809 (RS 5) 與 KB4537818
- 版本 1803 (RS 4) 與 KB4537795
- 版本 1709 (RS 3) 與 KB4537816
Windows Server 2019 - 僅適用於公開預覽
Windows Server 2022
macOS (需要額外的組態設定檔)
- 13 (Ventura)
- 12 (蒙地利)
- 11 (Big Sur)
Linux
權限
呼叫此 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱 開始使用。
| 許可權類型 | 權限 | 許可權顯示名稱 |
|---|---|---|
| 應用程式 | Machine.LiveResponse | 在特定電腦上執行實時回應 |
| 委派 (公司或學校帳戶) | Machine.LiveResponse | 在特定電腦上執行實時回應 |
HTTP 要求
POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse
要求標頭
| 名稱 | 類型 | 描述 |
|---|---|---|
| 授權 | 字串 | <持有人令牌>。 此為必要動作。 |
| Content-Type | 字串 | application/json。 此為必要動作。 |
要求內文
| 參數 | Type | 描述 |
|---|---|---|
| 留言 | 字串 | 要與動作相關聯的批注。 |
| 命令 | 陣列 | 要執行的命令。 允許的值為 PutFile、RunScript、GetFile (必須依此順序排列，且重複) 沒有限制。 |
命令
| 命令類型 | 參數 | 描述 |
|---|---|---|
| PutFile | 機碼：FileName 值： <檔名> |
將檔案從連結庫放入裝置。 檔案會儲存在工作資料夾中，而且預設會在裝置重新啟動時刪除。 注意：沒有響應結果。 |
| RunScript | 機碼：ScriptName 值： <來自連結庫的腳本> 索引鍵：自變數 |
從裝置上的連結庫執行腳本。 Args 參數會傳遞至您的腳本。 10 分鐘後逾時。 |
| GetFile | 索引鍵：路徑 值： <檔案路徑> |
從裝置收集檔案。 注意：必須逸出路徑中的反斜杠。 |
回應
如果成功，這個方法會傳回 201 Created。
動作實體。 如果找不到具有指定標識碼的機器 - 404 找不到。
範例
要求範例
以下是要求的範例。
POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse
```JSON
{
"Commands":[
{
"type":"RunScript",
"params":[
{
"key":"ScriptName",
"value":"minidump.ps1"
},
{
"key":"Args",
"value":"OfficeClickToRun"
}
]
},
{
"type":"GetFile",
"params":[
{
"key":"Path",
"value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
],
"Comment":"Testing Live Response API"
}
回應範例
以下是回應的範例。
每個命令狀態的可能值為 「Created」、“Completed” 和 “Failed”。
HTTP/1.1 200 Ok
內容類型：application/json
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
"id": "{machine_action_id}",
"type": "LiveResponse",
"requestor": "analyst@microsoft.com",
"requestorComment": "Testing Live Response API",
"status": "Pending",
"machineId": "{machine_id}",
"computerDnsName": "hostname",
"creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"errorHResult": 0,
"commands": [
{
"index": 0,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "RunScript",
"params": [
{
"key": "ScriptName",
"value": "minidump.ps1"
},{
"key": "Args",
"value": "OfficeClickToRun"
}
]
}
}, {
"index": 1,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "GetFile",
"params": [{
"key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
}
]
}
相關主題
提示
想要深入了解? 在我們的技術社群中與Microsoft安全性社群互動：Microsoft適用於端點的Defender技術社群。