重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
Microsoft Graph 安全 API 提供统一的接口和架构，以与 Microsoft 和生态系统合作伙伴的安全解决方案集成。 它使客户能够简化安全运营并更好地抵御日益增长的网络威胁。 Microsoft Graph 安全 API 将查询联合到所有载入的安全提供程序并聚合响应。 使用 Microsoft Graph 安全 API 构建以下应用程序：
- 整合和关联来自多个源的安全警报。
- 从 Microsoft 365 Defender 的一部分或与 集成的服务拉取和调查所有事件和警报。
- 解锁上下文数据，以提供信息帮助调查。
- 自动执行安全任务、业务流程、工作流和报告。
- 将威胁指示器发送到 Microsoft 产品以进行自定义检测。
- 调用操作以响应新威胁。
- 提供对安全数据的可见性，以实现主动风险管理。
Microsoft Graph 安全 API 提供了以下部分中所述的关键功能。
操作（预览版）
使用 securityAction 实体立即采取措施来防御威胁。 当安全分析师发现新的指示器（如恶意文件、URL、域或 IP 地址）时，可立即在你的 Microsoft 安全解决方案中启用保护。 针对特定提供商采取操作，查看所采取的全部操作，还可在需要时取消操作。 尝试使用 Microsoft Defender for Endpoint (以前是 Microsoft Defender ATP) 的安全操作，以使用警报中发现的属性或在调查期间识别的属性阻止 Windows 终结点上的恶意活动。
注意：安全操作当前仅支持应用程序权限。
高级搜寻
高级搜寻是一种基于查询的威胁搜寻工具，可用于浏览多达 30 天的原始数据。 你可以主动检查网络中的事件来找到威胁指示器和实体。 通过灵活访问数据，可以不受约束地搜寻已知威胁和潜在威胁。
使用 runHuntingQuery 对存储在 Microsoft 365 Defender 中的数据运行 Kusto 查询语言 (KQL) 查询。 利用返回的结果集来扩充现有调查或发现网络中未检测到的威胁。
配额和资源分配
只能对最近 30 天的数据运行查询。
结果最多包括 100,000 行。
每个租户的执行次数受到限制：
- API 调用：每分钟最多 45 个请求，每小时最多 1500 个请求。
- 执行时间：每小时运行 10 分钟，每天运行 3 小时。
单个请求的最长执行时间为 200 秒。
HTTP 429 响应代码表示已达到 API 调用数或执行时间的配额。 请参阅响应正文以确认已达到的限制。
单个请求的最大查询结果大小不能超过 124 MB。 超过大小限制会导致 HTTP 400 错误请求，并显示消息“查询执行已超出允许的结果大小。 通过限制结果数来优化查询，然后重试。”
查询结果的总体大小限制为 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/beta/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 报表。
预览) (云区域
Microsoft Defender for Cloud 中) 的云区域 (云范围使您能够跨多个云提供商 (Azure、AWS 和 GCP) 和 DevOps 平台对云环境进行分组和管理。 区域是一个逻辑容器，用于对相关云环境进行分组，从而更轻松地在多云基础架构中应用一致的安全策略并监控安全状况。 一个租户最多可以有 1,000 个区域。
使用云区域 API 执行以下操作：
- 创建、更新和删除区域，以组织云环境。
- 将环境 (（例如Azure订阅、AWS 账户、GCP 项目或 DevOps 连接）) 附加和分离到区域。
- 查询区域及其关联环境。
更多信息，请参见 管理云范围和统一的基于角色的访问控制。
自定义检测
可以创建特定于安全操作的高级搜寻 自定义检测规则 ，以便主动监视威胁并采取措施。 例如，您可以创建自定义检测规则来查找已知指标或配置错误的设备。 这些会自动触发警报和你指定的任何响应操作。
配额
- 获取多个规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 300 个规则，每个租户每小时 600 个规则
- 获取单个规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则
- 创建规则：每个应用程序每分钟 10 个规则，每个应用程序每小时 1500 个规则，每个租户每小时 1800 个规则
- 更新规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1,500 个规则，每个租户每小时 1,800 个规则
- 删除规则：每个应用程序每分钟 100 个规则，每个应用程序每小时 1500 个规则，每个租户每小时 1800 个规则
警报
警报是有关客户租户中可疑活动的详细警告，Microsoft 或合作伙伴安全提供商已识别这些活动并进行了标记以供采取行动。 攻击通常针对不同类型的实体（如设备、用户和邮箱）采用各种技术。 结果是来自多个安全提供程序针对租户中的多个实体发出警报。 将各个警报拼凑在一起以深入了解攻击可能具有挑战性且耗时。
安全 API 的测试版提供两种类型的警报，它们聚合来自安全提供商的其他警报，从而更轻松地分析攻击和确定响应：
-
警报和事件 - Microsoft Graph 安全 API 中最新一代的警报。 它们由命名空间中
microsoft.graph.security定义的警报资源及其集合（事件资源）表示。 -
旧警报 - Microsoft Graph 安全 API 中的第一代警报。 它们由命名空间中
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 安全提供程序。 它们聚合不同域之间的常见警报数据，使应用程序能够统一和简化所有集成解决方案的安全问题管理。 它们使应用程序能够关联警报和上下文，以改进威胁防护和响应。
借助警报更新功能，可以通过更新 警报 实体来同步与 Microsoft Graph 安全 API 集成的不同安全产品和服务中特定警报的状态。
可通过旧 警报资源获取 来自以下安全提供程序的警报。 下表显示了对 GET 警报、PATCH 警报和通过 Webhook 订阅 (的支持) 。
| 安全提供商 | GET 警报 |
PATCH 警报 |
订阅订阅 |
|---|---|---|---|
| Microsoft Entra ID 保护 | ✓ |
提交问题 * |
✓ |
| Azure 安全中心 | ✓ |
✓ |
✓ |
Microsoft 365
|
✓ |
||
| Microsoft Defender for Cloud Apps (以前是 Microsoft Cloud App Security) | ✓ |
提交问题 * |
✓ |
| Microsoft Defender for Endpoint (以前是 Microsoft Defender ATP) ** | ✓ |
✓ |
|
| Microsoft Defender for Identity (以前是 Azure 高级威胁防护) *** | ✓ |
提交问题 * |
✓ |
| 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 的详细信息。
案例管理 (预览)
使用 案例管理 API 创建和管理安全操作中的调查案例。 API 通过入口点支持通用案例、服务创建的事件案例以及相关任务、活动、关系和附件 /security/caseManagement 。
攻击模拟和训练
攻击模拟和培训是 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 的域控制器。
- 确定准备好使用统一代理激活的服务器。
- 启用或禁用统一代理合格服务器的自动激活。
- 在符合条件的服务器上激活或停用统一代理。
- 启用或禁用在传感器激活期间自动启用所需事件审核配置。
- 显示符合迁移条件的传感器列表。
- 迁移符合迁移条件的传感器。
事件
事件是构成攻击故事的相关警报和相关数据的集合。 事件管理是 Microsoft 365 Defender 的一部分，可在 Microsoft 365 Defender 门户 (https://security.microsoft.com/) 中使用。
Microsoft 365 服务和应用将在检测到可疑或恶意事件或活动时创建警报。 单个警报可提供有关已完成或持续攻击的有价值的线索。 但是，攻击通常对不同类型的实体（如设备、用户和邮箱）使用多种技术。 结果是租户中的多个实体将收到多个警报。
由于将各个警报拼凑在一起以深入了解攻击可能具有挑战性且耗时，因此 Microsoft 365 Defender 会自动将警报及其关联信息聚合到 事件中。
将相关警报组合为一个事件可使你对攻击具有全面了解。 例如，你可以看到：
- 攻击开始的位置。
- 使用了什么策略。
- 攻击侵入租户的程度。
- 攻击范围，例如受影响的设备、用户和邮箱数。
- 与攻击有关的所有数据。
事件资源及其 API 允许对事件进行排序，以创建明智的网络安全响应。 它公开在环境保留策略中指定的时间范围内在网络中标记的事件集合及其相关 警报。
信息保护
标签 - 信息保护标签提供有关如何正确地将敏感度标签应用到信息的详细信息。 信息保护标签 API 描述对某一用户或租户应用的敏感度标签配置。
威胁评估 - Microsoft Graph 威胁评估 API 可帮助组织评估租户中任何用户收到的威胁。 这样，客户就可将其收到的垃圾电子邮件、网络钓鱼 URL 或恶意软件附件报告给 Microsoft。 在生成结果之前，Microsoft 会检查相关示例和正在运行的组织策略，以便租户管理员可以了解威胁扫描判定并调整其组织策略。 还可以用来报告合法的电子邮件，以防止遭到阻止。
注意： 建议改用 威胁提交 API。
Security Copilot (预览版)
智能 智能 Microsoft Security Copilot 副驾驶® 副驾驶® 是一种生成式 AI 支持的安全分析工具，使防御者能够快速响应威胁、以机器速度处理信号并在几分钟内评估风险暴露。 它提高了跨角色和工作流程的安全专业人员的效率，支持事件响应、威胁搜寻、情报收集、态势管理等。
Security Copilot 将自然语言提示转换为智能、可操作的指导，简化复杂的操作并弥合网络安全人才差距。 它允许防御者在几分钟内完成任务，而不是数小时或数天。
Security Copilot 资源及其 API 允许开发人员将 Security Copilot 聊天体验嵌入到自定义门户或应用程序中。 它支持使用可用的插件创建会话、提示和评估，从而实现量身定制的人工智能驱动的安全工作流程。
- Security Copilot 中的会话会存储生成的任何 AI 提示和评估结果。 会话只能由创建会话的用户查看。
- 您可以在一个会话中使用一个或多个 提示 对象。 创建提示不会自动生成 AI 结果。 需要评估 API 才能开始处理提示。
- AI 处理在 创建评估 后立即开始。 使用提示创建评估将启动 AI 推理。 该 API 允许轮询中间结果，直到 AI 评估完成。
有关更多信息，请参阅：
记录管理
大多数组织需要管理数据以主动遵守行业法规和内部政策，在发生诉讼或安全漏洞时降低风险，并让员工有效、敏捷地分享与他们相关的最新知识。 可以使用 记录管理 API 系统地将 保留标签 应用于需要不同保留设置的不同类型的内容。 例如，您可以配置从创建内容、上次修改、标记或针对特定事件类型发生事件时开始的保留期。 此外，您可以使用 文件计划描述符 来提高这些保留标签的可管理性。
安全功能分数
Microsoft 安全功能分数是一款安全分析解决方案，可让你了解安全项目组合以及如何改进这些组合。 只需一个分数，你就可以更好地了解已采取了哪些措施来降低 Microsoft 解决方案中的风险。 此外，你还可以将你的分数与其他组织比较，以了解你的分数趋势。 secureScore 和 secureScoreControlProfile 实体可帮助你平衡组织的安全性和工作效率需求，同时启用适当的安全功能组合。 还可以预测采用安全功能后的分数。
威胁情报 (预览版)
Microsoft Defender 威胁智能提供世界一流的威胁智能，帮助保护你的组织免受新式网络威胁。 您可以使用威胁智能来识别攻击者及其操作，加快检测和修复，并增强安全投资和工作流程。
威胁情报 API (预览版) 允许你操作在用户界面中找到的情报。 这包括文章和情报配置文件形式的成品情报、包括 IoC 和声誉判决在内的机器智能，最后是包括被动 DNS、cookie、组件和跟踪器在内的扩充数据。
威胁情报指示器（预览版）
注意
tiIndicator 实体已弃用，将于 2026 年 4 月删除。
威胁指示器也称为入侵指标 (IoC) ，表示有关已知威胁的数据，例如恶意文件、URL、域和 IP 地址。 客户可通过内部威胁智能收集功能生成指示器，也可从威胁智能社区、经过许可的源或其他来源获取指示器。 这些指示器随后可在各种安全工具中用来防御相关威胁。
tiIndicator 实体允许客户将威胁指示器提供给 Microsoft 安全解决方案，以对恶意活动执行阻止或警报操作，或允许已确定为与组织无关的活动，并禁止对指示器执行操作。 若要发送指标，请指定打算利用该指标的 Microsoft 安全解决方案以及要为该指标执行的操作。
你可将 tiIndicator 实体集成到应用程序中，或者使用下述集成威胁智能平台 (TIP) 之一：
- Palo Alto 网络 MineMeld 威胁智能共享
- MISP 开源威胁智能平台（通过 TI 示例提供）
通过 Microsoft Graph 安全 API 发送的威胁指示器现已在以下产品中提供：
- Microsoft Defender for Endpoint – 使你能够警报和/或阻止与恶意活动关联的威胁指示器。 还可以允许指示器，以忽略此指示器，免于对其进行自动调查。 有关支持的指示器类型以及每个租户的指示器数限制的详细信息，请参阅管理指示器。
- Microsoft Sentinel – 有关如何将威胁智能指示器发送到 Microsoft Sentinel 的最新详细说明，请参阅将威胁智能平台连接到 Microsoft Sentinel。
威胁提交
Microsoft Graph 威胁评估 API 可帮助组织评估租户中任何用户收到的威胁。 这样，客户就可将其收到的垃圾电子邮件、网络钓鱼 URL 或恶意软件附件报告给 Microsoft。 Microsoft 根据实际情况检查组织策略提交，并将其发送给人工评分员进行分析。 策略检查结果和重新扫描结果可帮助租户管理员了解威胁扫描判定并调整其组织策略。 管理员还可以使用结果来报告合法的电子邮件，以防止遭到阻止。
注意：建议使用威胁提交 API，而不是已弃用的信息保护威胁评估 API。 威胁提交 API 提供统一的安全威胁提交功能，并增加了统一结果支持、用户提交查询支持、租户允许阻止列表支持、管理员审查支持和仅应用模式支持。
Email 和协作保护
Microsoft Defender for Office 365 是一种基于云的电子邮件筛选服务，可帮助保护组织免受电子邮件和协作工具的高级威胁，例如网络钓鱼、企业电子邮件泄露和恶意软件攻击。 可以使用 Microsoft Graph analyzedemails 和 修正 API 来检索电子邮件元数据，并在已分析的邮件上执行软删除、硬删除、移至垃圾邮件、移至收件箱) 的响应操作 (。
注意：这些 API 仅适用于 Defender for Office 365 计划 2 或 Microsoft 365 A5/E5/F5/G5 安全服务计划。 有关最新的服务计划列表，请参阅 Microsoft Defender for Office 365 服务说明。
传感器
Defender for Identity 传感器管理 API 允许你创建工作区中传感器的详细报告，包括有关服务器名称、传感器版本、类型、状态和运行状况状态的信息。 它还使你能够管理传感器设置，例如添加说明、启用或禁用延迟更新，以及指定传感器连接到查询 Entra ID 的域控制器。
identityAccounts
通过 identityAccounts 资源和相关 API，可以检索由 Microsoft Defender for Identity 警报标记的用户的详细信息，并应用禁用帐户和重置受损用户的用户密码等操作。
预览版) (数据安全和治理
Microsoft Purview 统一组织数据资产中的数据治理和合规性。 它为数据发现、分类和保护提供集中控制 - 直接与 Microsoft 365 和第三方数据源集成。 将其视为管理敏感信息并确保所有数据（无论它位于数据库、文档还是云存储中）的法规合规性的指挥中心。
数据安全和治理 API 允许开发人员无缝整合 Purview 的保护，这对于 RAG 应用程序、LOB 应用程序和处理敏感数据的系统至关重要。 这些 API 提供对 Purview 策略评估引擎的编程访问，确保跨各种应用程序一致的数据安全性和治理实施。
常见用例
以下是使用 Microsoft Graph 安全 API 的一些最常用请求。
可以使用 Microsoft Graph 更改通知 订阅和接收有关 Microsoft Graph 安全 API 实体更新的通知。
后续步骤
Microsoft Graph 安全 API 可为你开辟新的方式来使用 Microsoft 及其合作伙伴的不同安全解决方案。 请按照以下步骤开始操作：
- 深入了解警报、tiIndicator（预览版）、securityAction（预览版）、secureScore 和 secureScoreControlProfiles。
- 在 Graph 资源管理器中试用 API。 在 Sample queries （示例查询） 下，选择 Show more samples （显示更多示例），并将 Security category （安全类别） 设置为 On（开）。
- 请尝试订阅和接收实体变更通知。
相关内容
编写代码并参与 此 Microsoft Graph 安全 API 示例：
探索与 Microsoft Graph 安全 API 连接的其他选项：
与社区互动：