Defender for Cloud Apps REST API

项目
01/23/2024

本文介绍如何通过 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	数字	返回日期晚于 N 天前的所有记录
isnotset	boolean	设置为“true”时，返回指定字段中没有值的所有相关记录
isset	boolean	设置为 "true" 时，返回指定字段中已有值的所有相关记录
lt	单个值	返回其值小于提供值的所有记录
lte	单个值	返回其值小于或等于提供值的所有记录
lte_ndays	数字	返回日期早于 N 天前的所有记录
ncontains	字符串列表	返回不包含其中一个提供的字符串的所有相关记录
ndescendantof	值列表	返回与值或其后代不匹配的所有相关记录
neq	值列表	返回不包含所有提供值的所有相关记录
range	包含 "start" 和 "end" 字段的对象列表	返回属于其中一个提供的范围的所有记录
startswith	字符串列表	返回以其中一个提供的字符串开头的所有相关记录
startswithsingle	string	返回以提供的字符串开头的所有相关记录
text	string	对所有记录执行全文搜索

后续步骤

API 身份验证

如果遇到任何问题，我们可随时提供帮助。要获取产品问题的帮助或支持，请开立支持票证。

通过