Microsoft Graph 安全 API 提供统一的接口和架构，以与 Microsoft 和生态系统合作伙伴的安全解决方案集成。 这使客户能够简化安全性操作和更好地抵御日益增多的网络威胁。 Microsoft Graph 安全 API 将查询联合到所有载入的安全提供程序并聚合响应。 使用 Microsoft Graph 安全 API 构建以下应用程序：
- 整合和关联来自多个源的安全警报。
- 从 Microsoft 365 Defender 的一部分或与 集成的服务拉取和调查所有事件和警报。
- 解锁上下文数据，以提供信息帮助调查。
- 自动执行安全任务、业务流程、工作流和报告。
- 将威胁指示器发送到 Microsoft 产品以进行自定义检测。
- 调用操作来响应新威胁。
- 提供对安全数据的可见性，以实现主动风险管理。
Microsoft Graph 安全 API 提供了以下部分中所述的关键功能。
高级搜寻
高级搜寻是一种基于查询的威胁搜寻工具，可用于浏览多达 30 天的原始数据。 你可以主动检查网络中的事件来找到威胁指示器和实体。 通过灵活访问数据，可以不受约束地搜寻已知威胁和潜在威胁。
使用 runHuntingQuery 对存储在 Microsoft 365 Defender 中的数据运行 Kusto 查询语言 (KQL) 查询。 使用返回的结果集来扩充现有调查或发现网络中未检测到的威胁。
配额和资源分配
以下条件与所有查询相关。
- 查询浏览并返回过去 30 天的数据。
- 结果最多可以返回 100,000 行。
- 每个租户每分钟最多可以进行 45 次调用。 调用数因租户大小而异。
- 根据租户大小为每个租户分配 CPU 资源。 如果租户达到已分配资源的 100%，则查询将被阻止，直到下一个 15 分钟周期之后。 若要避免因过度消耗而导致查询受阻，请按照 优化查询以避免达到 CPU 配额中的指南进行操作。
- 如果单个请求运行超过三分钟，它将超时并返回错误。
-
429HTTP 响应代码指示已通过发送的请求数或分配的运行时间达到了分配的 CPU 资源。 阅读响应正文以了解你达到的限制。 - 查询结果的总体大小限制为 50 MB。 此限制不仅仅指记录数量;列数、数据类型和字段长度等因素也会影响查询结果大小。
从较旧的 API 迁移
Microsoft Graph 中的高级搜寻 API 替换了通过 和https://api.security.microsoft.com/api/advancedqueries/run终结点提供的https://api.security.microsoft.com/api/advancedhunting/run旧版本 API。 较旧的 API 现已停用，并将于 2027 年 2 月 1 日停止返回数据。
若要迁移到 Microsoft Graph 中的高级搜寻 API，请更新应用程序中的以下参数：
| 主题 | 较旧参数 | Microsoft Graph |
|---|---|---|
| 终结点 | https://api.securitycenter.microsoft.com/api/advancedqueries/run https://api.security.microsoft.com/api/advancedhunting/run |
https://graph.microsoft.com/v1.0/security/runHuntingQuery |
| 资源 URI | Microsoft Defender for Endpoint 开启https://api.securitycenter.microsoft.com |
Microsoft Graph 上的 https://graph.microsoft.com |
| API 权限 |
AdvancedQuery.Read (委派) ，而 AdvancedQuery.Read.All (应用程序) Microsoft Defender for Endpoint (以前称为 Windows Defender 高级威胁防护) AdvancedHunting.Read (委派) ，而 AdvancedHunting.Read.All (应用程序在 Microsoft 威胁防护下) |
ThreatHunting.Read.All (委派和应用程序) |
| 请求正文 |
查询 属性。 例如 {"Query":"DeviceProcessEvents \|where InitiatingProcessFileName =~ 'powershell.exe' \|where ProcessCommandLine contains 'appdata'\|project Timestamp, FileName, InitiatingProcessFileName, DeviceId\|limit 2"} |
查询 和 时间跨度 属性。 例如，{"Query": "DeviceProcessEvents", "Timespan": "P90D"} |
| 响应 | 由统计信息、架构和结果组成的 QueryResponse 对象 | huntingQueryResults 资源类型“，由架构 (而不是架构) 和结果 (而不是结果) 组成。 |
有关如何授权应用调用 Microsoft Graph API 的详细信息，请参阅 代表用户获取访问权限 和在 没有用户的情况下获取访问权限。
Power Platform 流迁移 (PowerApps / Power Automate / 逻辑应用)
Microsoft Graph 没有适用于 Microsoft Defender ATP 的 Power Platform 连接器中提供的内置高级搜寻操作。 若要继续在 Power Platform 流中使用高级搜寻，请创建自定义连接器。 有关详细信息，请参阅为 Power Automate 创建 Microsoft Graph JSON 批处理自定义连接器 ，并使用上表中所述的 Microsoft Graph 参数。
Power BI 流迁移
如果使用的是通过旧 API 创建的自定义 Power BI 报表，请更新 Power BI 查询以使用上表中所述的 Microsoft Graph 参数。 有关详细信息，请参阅使用 Microsoft Graph 安全 API 和 Power BI 创建自定义 Microsoft Defender XDR 报表。
自定义检测
可以创建特定于安全操作的高级搜寻 自定义检测规则 ，以主动监视威胁并采取措施。 例如，可以创建自定义检测规则来查找已知指标或配置错误的设备。 这些规则会自动触发警报和你指定的任何响应操作。
配额
- 列出检测规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 300 个规则，每个租户每小时 600 个规则。
- 获取检测规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1500 个规则，每个租户每小时 1800 个规则。
- 创建检测规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 1500 个规则，每个租户每小时 1800 个规则。
- 更新检测规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则。
- 删除检测规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则。
警报
警报是有关客户租户中可疑活动的详细警告，Microsoft 或合作伙伴安全提供商识别这些活动并标记为采取行动。 攻击通常针对不同类型的实体（如设备、用户和邮箱）采用各种技术。 结果是来自多个安全提供程序针对租户中的多个实体发出警报。 将各个警报拼凑在一起以深入了解攻击可能具有挑战性且耗时。
安全 API 提供两种类型的警报，可聚合来自安全提供商的其他警报，从而更轻松地分析攻击和确定响应：
-
警报和事件 - 这些是 Microsoft Graph 安全 API 中最新一代的警报。 它们由命名空间中
microsoft.graph.security定义的警报资源及其集合（事件资源）表示。 -
旧警报 - 这是 Microsoft Graph 安全 AI 中的第一代警报。 它们由命名空间中
microsoft.graph定义的警报资源表示。
重要
若要查看 Sentinel 警报和事件，必须将 Sentinel 加入 Defender 门户。 有关详细信息，请参阅将 Microsoft Sentinel 连接到 Microsoft Defender 门户。
警报和事件
这些 警报 资源首先从安全提供程序服务拉取警报数据，这些服务属于 Microsoft 365 Defender 的一部分或与 365 Defender 集成。 然后，他们使用数据来返回有关已完成或正在进行的攻击、受影响的资产和相关 证据的丰富而有价值的线索。 此外，它们还会自动将具有相同攻击技术或相同攻击者的其他警报关联到 事件 中，以提供更广泛的攻击上下文。 他们建议响应和补救措施，为所有不同的提供商提供一致的可操作性。 丰富的内容使分析师更容易集体调查和响应威胁。
可通过这些丰富的警报和事件获取来自以下安全提供商的警报：
- Microsoft Entra ID 保护
- Microsoft 365 Defender
- Microsoft Defender for Cloud Apps
- Microsoft Defender for Endpoint
- Microsoft Defender for Identity
- Microsoft Defender for Office 365
- Microsoft Purview 数据丢失防护
- Microsoft Purview 内部风险管理
旧版警报
重要
旧版警报 API 已弃用，将于 2026 年 10 月 15 日停用。 迁移到新的 警报和事件 API。 有关详细信息，请参阅 从旧警报迁移到警报和事件 API。
旧警报资源联合调用受支持的 Azure 和 Microsoft 365 Defender 安全提供程序。 它们聚合不同域之间的常见警报数据，使应用程序能够统一和简化所有集成解决方案中安全问题的管理。 它们使应用程序能够关联警报和上下文，以改进威胁防护和响应。
旧版安全 API 提供警报资源，该资源联合调用受支持的 Azure 和 Microsoft 365 Defender 安全提供程序。 此 警报 资源聚合不同域之间常见的警报数据，使应用程序能够统一和简化所有集成解决方案中安全问题的管理。 这使应用程序能够关联警报和上下文，以改进威胁防护和响应。
借助警报更新功能，可以通过更新 警报 实体来同步与 Microsoft Graph 安全 API 集成的不同安全产品和服务中特定警报的状态。
可通过 警报 资源获取来自以下提供程序的警报。 下表显示了对 GET 警报、PATCH 警报和通过 Webhook 订阅 (的支持) 。
| 安全提供商 | GET 警报 |
PATCH 警报 |
订阅订阅 |
|---|---|---|---|
| Microsoft Entra ID 保护 | ✓ |
提交问题 * |
✓ |
Microsoft 365
|
✓ |
||
| Microsoft Defender for Cloud Apps | ✓ |
提交问题 * |
✓ |
| Microsoft Defender for Endpoint ** | ✓ |
✓ |
|
| Microsoft Defender for Identity *** | ✓ |
提交问题 * |
✓ |
| Microsoft Sentinel (以前Azure Sentinel) | ✓ |
在 Microsoft Sentinel 中不受支持 |
✓ |
注意： 新的提供商将不断加入 Microsoft Graph 安全生态系统。 若要请求新提供商或向现有提供商寻求扩展支持，请 在 Microsoft Graph 安全 GitHub 存储库中提交问题。
* 文件问题：警报状态会在 Microsoft Graph 安全 API 集成应用程序中更新，但不会反映在提供商的管理体验中。
** 除了 Microsoft Graph 安全 API 所需的角色之外，Microsoft Defender for Endpoint 还需要额外的用户角色。 只有同时具有 Microsoft Defender for Endpoint 和 Microsoft Graph 安全 API 角色的用户才能访问 Microsoft Defender for Endpoint 数据。 由于仅限应用程序身份验证不受此限制，因此建议使用仅限应用程序身份验证令牌。
Microsoft Defender for Identity 警报可通过 Microsoft Defender for Cloud Apps 集成获得。 这意味着仅当加入 Unified SecOps 并将 Microsoft Defender for Identity 连接到 Microsoft Defender for Cloud Apps 时，才会收到 Microsoft Defender for Identity 警报。 了解有关如何集成 Microsoft Defender for Identity 和 Microsoft Defender for Cloud Apps 的详细信息。
攻击模拟和训练
攻击模拟和培训是 Microsoft Defender for Office 365 的一部分。 此服务可让租户中的用户体验真实的恶意钓鱼攻击，并从中学习。 最终用户的社交工程模拟和培训体验有助于降低用户被这些攻击技术入侵的风险。 攻击模拟和培训 API 使租户管理员能够查看启动的模拟练习和培训，并获取有关网络钓鱼模拟中用户在线行为的派生见解的报告。
电子数据展示
Microsoft Purview 电子数据展示提供了一个端到端工作流，用于保留、收集、分析、查看和导出响应组织内部和外部调查的内容。
审核日志查询
Microsoft Purview 审核提供了一个集成解决方案，帮助组织有效响应安全事件、取证调查、内部调查和合规性义务。 数千名 Microsoft 365 服务和解决方案中执行的用户和管理员操作被捕获、记录并保留在组织的统一审核日志中。 这些事件的审核记录通过安全运营、IT 管理员、预览体验计划团队以及合规与法律支持人员进行搜索。 此功能可跨 Microsoft 365 组织查看执行的活动。
身份
运行状况问题
Microsoft Defender for Identity 运行状况问题 API 允许监视混合标识基础结构中传感器和代理的运行状况。 可以使用运行状况问题 API 检索有关传感器当前运行状况问题的信息，例如问题类型、状态、配置和严重性。 还可以使用此 API 来识别和解决可能影响传感器和代理功能或安全性的任何问题。
注意：Microsoft Defender for Identity 运行状况问题 API 仅在 Defender for Identity 计划或 Microsoft 365 E5/A5/G5/F5 安全服务计划中可用。
传感器
Defender for Identity 传感器管理 API 允许你：
- 创建工作区中传感器的详细报告，包括有关服务器名称、传感器版本、类型、状态和运行状况状态的信息。
- 管理传感器设置，例如添加说明、启用或禁用延迟更新，以及指定传感器连接到以查询 Entra ID 的域控制器。
- 识别准备激活的传感器。
- 定义基础设施中的传感器是自动激活还是手动激活。
- 确定准备好使用统一代理激活的服务器。
- 启用或禁用统一代理合格服务器的自动激活。
- 在符合条件的服务器上激活或停用统一代理。
- 启用或禁用在传感器激活期间自动启用所需事件审核配置。
identityAccounts
通过 identityAccounts 资源和相关 API，可以检索由 Microsoft Defender for Identity 警报标记的用户的详细信息，并应用禁用帐户和重置受损用户的用户密码等操作。
事件
事件是构成攻击故事的相关警报和相关数据的集合。 事件管理是 Microsoft 365 Defender 的一部分，可在 Microsoft 365 Defender 门户 (https://security.microsoft.com/) 中使用。
Microsoft 365 服务和应用将在检测到可疑或恶意事件或活动时创建警报。 单个警报可提供有关已完成或持续攻击的有价值的线索。 但是，攻击通常对不同类型的实体（如设备、用户和邮箱）使用多种技术。 结果是租户中的多个实体将收到多个警报。
由于将各个警报拼凑在一起以深入了解攻击可能具有挑战性且耗时，因此 Microsoft 365 Defender 会自动将警报及其关联信息聚合到 事件中。
将相关警报组合为一个事件可使你对攻击具有全面了解。 例如，你可以看到：
- 攻击开始的位置。
- 使用了什么策略。
- 攻击深入租户的程度。
- 攻击范围，例如受影响的设备、用户和邮箱数。
- 与攻击有关的所有数据。
事件资源及其 API 允许对事件进行排序，以创建明智的网络安全响应。 它公开在环境保留策略中指定的时间范围内在网络中标记的事件集合及其相关 警报。
信息保护
Microsoft Graph 威胁评估 API 可帮助组织评估租户中任何用户收到的威胁。 这样，客户就可将其收到的垃圾电子邮件、网络钓鱼 URL 或恶意软件附件报告给 Microsoft。 策略检查结果和重新扫描结果可帮助租户管理员了解威胁扫描判定并调整其组织策略。
记录管理
大多数组织需要管理数据以主动遵守行业法规和内部政策，在发生诉讼或安全漏洞时降低风险，并让人们有效、敏捷地共享与他们相关的最新知识。 可以使用 记录管理 API 系统地将 保留标签 应用于需要不同保留设置的不同类型的内容。 例如，您可以配置从创建内容、上次修改、标记或特定事件类型的事件发生时开始的保留期。 此外，您可以使用 文件计划描述符 来提高这些保留标签的可管理性。
安全功能分数
Microsoft 安全功能分数是一款安全分析解决方案，可让你了解安全项目组合以及如何改进这些组合。 通过单一分数，你可以更好地了解你如何降低 Microsoft 解决方案中的风险。 此外，你还可以将你的分数与其他组织比较，以了解你的分数趋势。 Microsoft Graph 安全 secureScore 和 secureScoreControlProfile 实体可帮助你平衡组织的安全性和生产力需求，同时启用适当的安全功能组合。 你也可以计划采取安全功能之后的分数。
威胁智能
Microsoft Defender 威胁智能提供世界一流的威胁智能，帮助保护你的组织免受新式网络威胁。 您可以使用威胁智能来识别攻击者及其操作，加快检测和修复，并增强安全投资和工作流程。
威胁情报 API 允许你操作在用户界面中找到的情报。 这包括文章和情报配置文件形式的成品情报、机器智能（如 IoC 和声誉判决）以及扩充数据（如被动 DNS、cookie、组件和跟踪器）。
常见用例
以下是使用 Microsoft Graph 安全 API 的一些最常用请求。
可以使用 Microsoft Graph 更改通知 订阅和接收有关 Microsoft Graph 安全实体更新的通知。
资源
编写代码并参与以下 Microsoft Graph 安全 API 示例：
与社区互动：
后续步骤
Microsoft Graph 安全 API 可为你开辟新的方式来使用 Microsoft 及其合作伙伴的不同安全解决方案。 请按照以下步骤开始操作：
- 向下滚动至 alerts、secureScore 和 secureScoreControlProfiles。
- 在 Graph 资源管理器中试用 API。 在“示例查询”中，选择“显示更多示例”并将“安全类别”设为“开启”。
- 请尝试订阅和接收实体变更通知。
相关内容
编写代码并参与 此 Microsoft Graph 安全 API 示例：
探索与 Microsoft Graph 安全 API 连接的其他选项：
与社区互动：