在设备上运行实时响应命令
适用于：
重要
本文中的某些信息与预发行的产品有关，该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
希望体验 Microsoft Defender for Endpoint？ 注册免费试用版。
注意
如果你是美国政府客户，请使用 适用于美国政府客户的 Microsoft Defender for Endpoint 中列出的 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 for Endpoint 计划 1 和计划 2 支持创建设备组。
可以在单个 API 调用上运行多个实时响应命令。 但是，当实时响应命令失败时，不会执行所有后续操作。
如果实时响应操作已在运行，则无法在同一 (台计算机上执行多个实时响应会话，后续请求将使用 HTTP 400 - ActiveRequestAlreadyExists) 响应。
注意
从“设备”页启动的实时响应操作在 machineactions API 中不可用。
最低要求
在设备上启动会话之前，请确保满足以下要求：
验证是否正在运行受支持的 Windows、macOS 或 Linux 版本。
设备必须运行以下任一项：
Windows 11
Windows 10
Windows Server 2019 - 仅适用于公共预览版
- 版本 1903 或 (KB4515384) 更高版本
- 具有 KB4537818) 的版本 1809 (
Windows Server 2022
macOS (需要其他配置文件)
- 13 (文图拉)
- 12 (蒙特利)
- 11 (大苏尔)
Linux
权限
要调用此 API，需要以下权限之一。 若要了解详细信息（包括如何选择权限），请参阅 入门。
| 权限类型 | 权限 | 权限显示名称 |
|---|---|---|
| 应用程序 | Machine.LiveResponse | 在特定计算机上运行实时响应 |
| 委派（工作或学校帐户） | Machine.LiveResponse | 在特定计算机上运行实时响应 |
HTTP 请求
POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse
请求标头
| 名称 | 类型 | 说明 |
|---|---|---|
| Authorization | String | 持有者<令牌>。 必填。 |
| Content-Type | string | application/json. 必需。 |
请求正文
| 参数 | 类型 | 说明 |
|---|---|---|
| 评论 | 字符串 | 要与操作关联的注释。 |
| 命令 | Array | 要运行的命令。 允许的值为 PutFile、RunScript、GetFile (必须按此顺序排列，对重复) 没有限制。 |
命令
| 命令类型 | 参数 | 说明 |
|---|---|---|
| PutFile | 项：FileName 值： <文件名> |
将库中的文件放入设备。 文件保存在工作文件夹中，并在设备重启时默认删除。 注意：没有响应结果。 |
| RunScript | 键：ScriptName 值： <库中的脚本> 键：Args |
在设备上从库运行脚本。 Args 参数将传递给脚本。 10 分钟后超时。 |
| GetFile | 键：路径 值： <文件路径> |
从设备收集文件。 注意：必须转义路径中的反斜杠。 |
响应
如果成功，此方法返回 201 Created。
操作实体。 如果未找到具有指定 ID 的计算机 - 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"
}
响应示例
以下是响应示例。
每个命令状态的可能值为“已创建”、“已完成”和“失败”。
HTTP/1.1 200 Ok
Content-type：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 for Endpoint 技术社区。