Defender for Cloud应用 REST API
注意
我们重命名了Microsoft Cloud App Security。 现在称为Microsoft Defender for Cloud Apps。 在接下来的几周内，我们将更新此处和相关页面中的屏幕截图和说明。 有关更改的详细信息，请参阅 此公告。 若要了解有关 Microsoft 安全服务最近重命名的详细信息，请参阅 Microsoft Ignite Security 博客。
Microsoft Defender for Cloud Apps现在是Microsoft 365 Defender的一部分。 Microsoft 365 Defender门户允许安全管理员在一个位置执行其安全任务。 这将简化工作流，并添加其他Microsoft 365 Defender服务的功能。 Microsoft 365 Defender是监视和管理 Microsoft 标识、数据、设备、应用和基础结构安全性的家。 有关这些更改的详细信息，请参阅Microsoft 365 Defender中的Microsoft Defender for Cloud Apps。
本文介绍如何通过 HTTPS 与 Defender for Cloud 应用进行交互。
Microsoft Defender for Cloud Apps API 通过 REST API 终结点提供对Defender for Cloud应用的编程访问。 应用程序可以使用 API 对Defender for Cloud应用数据和对象执行读取和更新操作。 例如，Defender for Cloud应用 API 支持用户对象的以下常见操作：
- 上传 Cloud Discovery 的日志文件
- 生成阻止脚本
- 列出活动和警报
- 消除警报或解决警报问题
API URL 结构
若要使用Defender for Cloud应用 API，必须先从租户获取 API URL。 API URL 使用以下格式： https://<portal_url>/api/<endpoint>
若要获取租户的Defender for Cloud应用门户 URL，请执行以下步骤：
在Defender for Cloud应用门户中，选择菜单栏中的问号图标。 然后选择“关于”。
在Defender for Cloud“应用”屏幕中，可以看到门户 URL。
获取门户 URL 后，将 /api 后缀添加到其中以获取 API URL。 例如，如果门户的 URL 为 https://mytenant.us2.contoso.com，则 API URL 为 https://mytenant.us2.contoso.com/api。
API 令牌
Defender for Cloud应用需要服务器所有 API 请求标头中的 API 令牌，例如：
Authorization: Token <your_token_key>
个人 API 令牌的位置 <your_token_key> 。
有关 API 令牌的详细信息，请参阅 管理 API 令牌。
示例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.com/api/example-endpoint"
哪些操作受支持？
下表描述了支持的操作：
| 资源 | HTTP 谓词 | URI 路由 |
|---|---|---|
| 活动 | GET 或 POST | /api/v1/activities/ |
| 警报 | GET 或 POST | /api/v1/alerts/ |
| Cloud Discovery | GET、POST 或 PUT | /api/v1/discovery/ |
| 数据扩充 | GET、POST 或 DELETE | /api/subnet/ |
| 实体 | GET 或 POST | /api/v1/entities/ |
| 文件 | GET 或 POST | /api/v1/files/ |
其中 Resource 表示一组相关实体。
支持哪些字段类型？
下表描述了支持的字段类型：
| 字段 | 说明 |
|---|---|
| 字符串 | 文本字符串 |
| boolean | 表示 true/false 的布尔值 |
| integer | 32 位带符号整数 |
| timestamp | 自纪元以来的毫秒数 |
时间戳
Defender for Cloud应用 API 中的时间戳提及以毫秒为单位的 Unix 时间戳。 此时间戳由自 1970-01-01 0：00：00 以来的毫秒数确定。 可以使用 get-date PowerShell cmdlet 将日期转换为时间戳。
限制
可以通过在请求中提供限制参数来选择限制请求。
提供限制参数支持以下方法：
- 带有
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>.contoso.com/api/example-endpoint" -d '{
"filters": {
"some.field": {
"eq": ["value1", "value2"],
"isset": true
},
"some.field2": {
"gte": 5
}
},
"skip": 5,
"limit": 10
}'
运算符
注意
并非所有运算符都与所有筛选器兼容。
下表描述了支持的运算符：
| 运算符 | 响应类型 | 说明 |
|---|---|---|
| contains | 字符串列表 | 返回包含其中一个提供的字符串的所有相关记录 |
| deq | 值列表 | 返回包含一个值不等于所提供的值的所有记录 |
| 子代 | 值列表 | 返回与值或子代匹配的所有相关记录 |
| 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 | 字符串 | 返回从提供的字符串开始的所有相关记录 |
| text | 字符串 | 对所有记录执行全文搜索 |
后续步骤
若遇到任何问题，可随时向我们寻求帮助。 若要获取帮助或支持以解决产品问题，请打开支持票证。