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 支持用户对象的以下常见操作：
- 上传 Cloud Discovery 的日志文件
- 生成阻止脚本
- 列出活动和警报
- 消除警报或解决警报问题
API URL 结构
若要使用 Defender for Cloud Apps API，必须先从租户处获取 API URL。 API URL 使用以下格式：https://<portal_url>/api/<endpoint>。
若要获取租户的 Defender for Cloud Apps API URL ，请执行以下步骤：
在 Microsoft Defender 门户中，选择“设置”。 然后选择“Cloud Apps”。 在“系统”下，选择“关于”。
在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/ |
其中“资源”表示一组相关实体。
支持哪些字段类型？
下表描述了支持的字段类型：
| 字段 | 说明 |
|---|---|
| string | 文本字符串 |
| boolean | 布尔值，表示 true/false |
| integer | 32 位带符号整数 |
| timestamp | 自纪元以来的毫秒数 |
时间戳
Defender for Cloud Apps API 中提及的时间戳是指以毫秒为单位的 Unix 时间戳。 此时间戳由自 1970-01-01 0:00:00 以来的毫秒数确定。 可以使用 get-date PowerShell cmdlet 将日期转换为时间戳。
限制
可以选择通过在请求中提供限制参数来限制请求。
支持通过以下方法提供限制参数：
- URL 编码（带
Content-Type: application/x-www-form-urlencoded标头） - 表单数据
- 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 | 对所有记录执行全文搜索 |
后续步骤
如果遇到任何问题，我们可随时提供帮助。 要获取产品问题的帮助或支持，请开立支持票证。