Defender for Cloud Apps REST API
本文介绍如何通过 HTTPS 与Defender for Cloud Apps交互。
Microsoft Defender for Cloud Apps API 通过 REST API 终结点提供对Defender for Cloud Apps的编程访问。 应用程序可以使用 API 对Defender for Cloud Apps数据和对象执行读取和更新操作。 例如，Defender for Cloud Apps API 支持用户对象的以下常见操作：
- 上传用于云发现的日志文件
- 生成块脚本
- 列出活动和警报
- 消除或解决警报
API URL 结构
若要使用 Defender for Cloud Apps API，必须先从租户获取 API URL。 API URL 使用以下格式： https://<portal_url>/api/<endpoint>。
若要获取租户的Defender for Cloud Apps API URL，请执行以下步骤：
在Microsoft Defender门户中，选择“设置”。 然后选择“ 云应用”。 在“ 系统”下，选择“ 关于”。
在“关于Defender for Cloud Apps”屏幕中，可以看到 API URL。
获得 API URL 后，向其添加 /api 后缀以获取 API URL。 例如，如果门户的 URL 为 https://mytenant.us2.contoso.com，则 API URL 为 https://mytenant.us2.portal.cloudappsecurity.com/api。
API 令牌
Defender for Cloud Apps要求在向服务器发出的所有 API 请求的标头中提供 API 令牌，如下所示：
Authorization: Token <your_token_key>
其中 <your_token_key> 是个人 API 令牌。
有关 API 令牌的详细信息，请参阅 管理 API 令牌。
API 令牌 - 示例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"
支持哪些操作？
下表描述了支持的操作：
| 资源 | HTTP 谓词 | URI 路由 |
|---|---|---|
| 活动 | GET 或 POST | /api/v1/activities/ |
| 警报 | GET 或 POST | /api/v1/alerts/ |
| 数据扩充 | GET、POST 或 DELETE | /api/subnet/ |
| 实体 | GET 或 POST | /api/v1/entities/ |
| 文件 | GET 或 POST | /api/v1/files/ |
其中 ，Resource 表示一组相关实体。
支持哪些字段类型？
下表描述了支持的字段类型：
| 字段 | 说明 |
|---|---|
| string | 文本字符串 |
| boolean | 表示 true/false 的布尔值 |
| integer | 32 位带符号整数 |
| 时间戳 | 自纪元以来的毫秒数 |
时间 戳
Defender for Cloud Apps API 中提及时间戳是指 Unix 时间戳（以毫秒为单位）。 此时间戳由自 1970-01-01 0：00：00 以来的毫秒数确定。 可以使用 get-date PowerShell cmdlet 将日期转换为时间戳。
限制
可以通过在请求中提供限制参数来选择限制请求。
支持以下方法提供 limit 参数：
- 带有
Content-Type: application/x-www-form-urlencoded标头) 的 URL 编码 ( - 表单数据
- JSON 正文 (和
Content-Type: multipart/form-data适当的边界标头)
注意
- 如果未提供任何限制，则默认设置为 100。
- 对使用 API 令牌发出的所有请求的响应限制为最多 100 个项。
- 所有 API 请求的限制限制为每个租户每分钟 30 个请求。
筛选器
当你有大量结果时，你会发现使用筛选器微调请求很有用。 本部分介绍可与 筛选器一起使用的 和 运算符的结构。
结构
执行查询时，某些 API 终结点支持筛选器。 在其相关部分中，你将找到一个参考，其中列出了该资源的所有可用可筛选字段和支持的运算符。
大多数筛选器支持多个值，以提供强大的查询。 组合筛选器和运算符时，我们使用 AND 作为筛选器之间的逻辑运算符。
筛选器 - 示例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
"filters": {
"some.field": {
"eq": ["value1", "value2"],
"isset": true
},
"some.field2": {
"gte": 5
}
},
"skip": 5,
"limit": 10
}'
运算符
注意
并非所有运算符都与所有筛选器兼容。
下表描述了支持的运算符：
| 运算符 | 响应类型 | 说明 |
|---|---|---|
| contains | 字符串列表 | 返回包含其中一个提供的字符串的所有相关记录 |
| deq | 值列表 | 返回包含一个值不等于所提供的值的所有记录 |
| descendantof | 值列表 | 返回与其匹配值或后代的所有相关记录 |
| doesnotstartwith | 字符串列表 | 返回不以每个提供的字符串开头的所有相关记录 |
| endswith | 字符串列表 | 返回以提供的字符串之一结尾的所有相关记录 |
| eq | 值列表 | 返回包含其中一个提供值的相关记录 |
| gt | 单个值 | 返回值大于所提供值的所有记录 |
| gte | 单个值 | 返回值大于或等于所提供的值的所有记录 |
| gte_ndays | number | 返回日期晚于 N 天前的所有记录 |
| isnotset | boolean | 设置为“true”时，返回指定字段中没有值的所有相关记录 |
| isset | boolean | 设置为“true”时，返回在指定字段中具有值的所有相关记录 |
| lt | 单个值 | 返回值小于提供值的所有记录 |
| lte | 单个值 | 返回值小于或等于提供值的所有记录 |
| lte_ndays | number | 返回日期早于 N 天的所有记录 |
| ncontains | 字符串列表 | 返回未包含提供的字符串之一的所有相关记录 |
| ndescendantof | 值列表 | 返回与其值不匹配的所有相关记录或后代 |
| neq | 值列表 | 返回所有相关记录，但不包含所有提供的值 |
| range | 包含“start”和“end”字段的对象列表 | 返回其中一个提供的范围中的所有记录 |
| startswith | 字符串列表 | 返回所有相关记录，以提供的字符串之一开头 |
| startswithsingle | string | 返回以提供的字符串开头的所有相关记录 |
| text | string | 对所有记录执行全文搜索 |
后续步骤
如果你遇到任何问题，我们随时为你提供帮助。 若要获取有关产品问题的帮助或支持，请 开具支持票证。