使用 Microsoft Graph 安全 API

Microsoft Graph 安全 API 提供统一的接口和架构，用于与 Microsoft 和生态系统合作伙伴的安全解决方案集成。 这使客户能够简化安全性操作和更好地抵御日益增多的网络威胁。 Microsoft Graph 安全 API 将查询联合到所有载入的安全提供程序并聚合响应。 使用 Microsoft Graph 安全 API 生成以下应用程序：

• 合并并关联来自多个源的安全警报。
• 从属于 Microsoft 365 Defender 或与 Microsoft 365 Defender 集成的服务拉取和调查所有事件和警报。
• 解锁上下文数据，以提供信息帮助调查。
• 自动执行安全任务、业务流程、工作流和报告。
• 将威胁指示器发送到 Microsoft 产品进行自定义检测。
• 调用 操作以响应新威胁。
• 提供对安全数据的可见性，以实现主动风险管理。

Microsoft Graph 安全 API 提供关键功能，如以下部分所述。

高级搜寻

高级搜寻是基于查询的威胁搜寻工具，可用于浏览长达 30 天的原始数据。 你可以主动检查网络中的事件来找到威胁指示器和实体。 通过灵活访问数据，可以不受约束地搜寻已知威胁和潜在威胁。

使用 runHuntingQuery 对 Microsoft 365 Defender 中存储的数据运行Kusto 查询语言 (KQL) 查询。 使用返回的结果集来扩充现有调查或发现网络中未检测到的威胁。

配额和资源分配

以下条件与所有查询相关。

1. 查询浏览并返回过去 30 天的数据。
2. 结果最多可返回 100,000 行。
3. 每个租户每分钟最多可以进行 45 次调用。 每个租户的调用次数因大小而异。
4. 根据租户大小为每个租户分配 CPU 资源。 如果租户在下一个 15 分钟周期之后达到已分配资源的 100%时，将阻止查询。 若要避免因过度消耗而阻止查询，请遵循 优化查询以避免达到 CPU 配额中的指导。
5. 如果单个请求运行时间超过三分钟，则会超时并返回错误。
6. 429 HTTP 响应代码指示你已按发送的请求数或分配的运行时间到达分配的 CPU 资源。 阅读响应正文以了解达到的限制。

警报

警报是有关客户租户中可疑活动的详细警告，Microsoft 或合作伙伴安全提供商识别并标记为要采取行动。 攻击通常对不同类型的实体（如设备、用户和邮箱）采用各种技术。 结果是来自租户中多个实体的多个安全提供程序发出的警报。 将单个警报拼凑在一起以深入了解攻击可能具有挑战性且非常耗时。

安全 API 提供两种类型的警报，这些警报聚合来自安全提供程序的其他警报，使分析攻击和确定响应更容易：

• 警报和事件 - 这些是 Microsoft Graph 安全 API 中的最新一代警报。 它们由命名空间中microsoft.graph.security定义的警报资源及其集合事件资源表示。
• 旧警报 - 这是 Microsoft Graph 安全 API 中的第一代警报。 它们由 命名空间中microsoft.graph定义的警报资源表示。

警报和事件

这些 警报 资源首先从属于 Microsoft 365 Defender 或与 Microsoft 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 数据丢失防护

旧警报

注意

旧警报 API 已弃用，将于 2026 年 4 月删除。 建议迁移到新的 警报和事件 API。

旧警报资源联合调用受支持的 Azure 和 Microsoft 365 Defender 安全提供程序。 它们聚合不同域之间的常见警报数据，使应用程序能够跨所有集成解决方案统一和简化对安全问题的管理。 它们使应用程序能够关联警报和上下文，以改善威胁防护和响应。

旧版安全 API 提供 警报 资源，用于联合调用受支持的 Azure 和 Microsoft 365 Defender 安全提供程序。 此 警报 资源聚合不同域中常见的警报数据，使应用程序能够统一和简化跨所有集成解决方案的安全问题管理。 这使应用程序能够关联警报和上下文，以改善威胁防护和响应。

使用警报更新功能，可以通过更新警报实体来跨与 Microsoft Graph 安全 API 集成的不同安全产品和服务同步特定 警报 的状态。

来自以下提供程序的 警报可通过警报 资源获取。 下表显示了通过 webhook) 对 GET 警报、PATCH 警报和订阅 (的支持。

安全提供商	GET 警报	PATCH 警报	订阅订阅
Microsoft Entra ID 保护	✓	提交问题 *	✓
Microsoft 365 默认 Cloud App Security 自定义警报	✓	提交问题	提交问题
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 Defender for Endpoint需要 Microsoft Graph 安全 API 所需的用户角色。 只有 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 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 使你能够操作用户界面中发现的智能。 这包括文章和 Intel 配置文件形式的完成智能、计算机智能（例如 IoC 和信誉判断）以及扩充数据（如被动 DNS、Cookie、组件和跟踪器）。

常见用例

下面是使用 Microsoft Graph 安全 API 的一些最常用的请求。

用例	REST 资源	在 Graph 浏览器中试调用
更新安全功能分数控制配置文件	更新 secureScoreControlProfile	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}
警报和事件
列出警报	List alerts	https://graph.microsoft.com/v1.0/security/alerts_v2
更新警报	更新警报	https://graph.microsoft.com/v1.0/security/alerts/{id}
列出事件	列出事件	https://graph.microsoft.com/v1.0/security/incidents
使用警报列出事件	列出事件	https://graph.microsoft.com/v1.0/security/incidents?$expand=alerts
更新事件	更新事件	https://graph.microsoft.com/v1.0/security/incidents/{id}
电子数据展示
列出电子数据展示案例	List eDiscoveryCases	https://graph.microsoft.com/v1.0/security/cases/eDiscoveryCases
列出电子数据展示案例操作	List caseOperations	https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/{id}/operations
旧警报
列出警报	List alerts	https://graph.microsoft.com/v1.0/security/alerts
更新警报	更新警报	https://graph.microsoft.com/v1.0/security/alerts/{alert-id}
安全功能分数
列出安全功能分数	列出 secureScore	https://graph.microsoft.com/v1.0/security/secureScores
获取安全功能分数	获取 secureScore	https://graph.microsoft.com/v1.0/security/secureScores/{id}
列出安全功能分数控制配置文件	列出 secureScoreControlProfiles	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles
获取安全功能分数控制配置文件	获取 secureScoreControlProfile	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}

可以使用 Microsoft Graph Webhook 订阅和接收有关 Microsoft Graph 安全实体更新的通知。

资源

编写代码并参与以下 Microsoft Graph 安全 API 示例：

• ASP.NET (C#) 示例
• Python 示例
• Node.js (JavaScript) 示例

与社区互动：

• 加入技术社区
• 在 StackOverflow 上讨论

后续步骤

Microsoft Graph 安全 API 可以开辟新方式，让你与 Microsoft 和合作伙伴的不同安全解决方案互动。 请按照以下步骤开始操作：

• 向下滚动至 alerts、secureScore 和 secureScoreControlProfiles。
• 在 Graph 资源管理器中试用 API。 在“示例查询”中，选择“显示更多示例”并将“安全类别”设为“开启”。
• 请尝试订阅和接收实体变更通知。

相关内容

编写代码并参与 此 Microsoft Graph 安全 API 示例：

• PowerShell 示例

探索使用 Microsoft Graph 安全 API 进行连接的其他选项：

• 适用于逻辑应用、流和 Power 应用的 Microsoft Graph 安全连接器
• Jupyter Notebook 示例

与社区互动：

• 加入技术社区
• 在 StackOverflow 上讨论