Microsoft Graph 的版本控制、支持和重大更改策略

  • 项目

本文介绍了 Microsoft Graph 的支持和重大更改策略，以及当前可用的 Microsoft Graph API 版本。

支持策略和弃用信息

Microsoft Graph 遵循 Microsoft 生命周期策略。

由于已发布新版本的 Microsoft Graph REST API 和 Microsoft Graph SDK，之前的版本将停用。 Microsoft 会在停用某个版本之前至少 24 个月声明其为弃用版本。 同样，对于通常可用的 (GA) 单个 API，Microsoft 会在从 GA 版本将其删除之前至少 24 个月时声明其为弃用产品。

例如，当我们将 API 的主版本 (（从 v1.0 增加到 v2.0) ）时，我们宣布当前版本 (在此示例中，v1.0) 将立即弃用，在发布后的 24 个月将不再支持它。 出于服务安全或运行状况可靠性问题的考虑，我们可能会对此策略作例外处理。

当 API 被标记为已弃用时，我们强烈建议你尽快迁移到最新版本。 在某些情况下，我们将宣布新应用程序将在原始 API 弃用后不久开始使用新 API。 在这些情况下，仅当前使用已弃用 API 的活动应用程序能够继续使用它们。

API 协定和非后退兼容更改

Microsoft Graph 在版本中进行了许多更改。 这些更改已在 Microsoft Graph 更改日志中列出。 将新功能和数据添加到 Microsoft Graph 后，我们会递增 API 版本号，以便对 API 进行任何非后退兼容更改。

下面是非后退兼容更改的示例：

  • 对与资源关联的 URL 或基本请求/响应进行更改
  • 删除、重命名或更改声明的属性的类型
  • 删除或重命名 API 或 API 参数
  • 添加所需的请求标头

向后兼容的更改示例如下：

  • 添加可为 Null 或具有默认值的属性
  • 向枚举添加成员
  • 删除、重命名或更改开放扩展的类型
  • 删除、重命名或更改注释的类型
  • 向现有集合引入分页
  • 更改错误代码
  • 更改属性的顺序
  • 更改不透明字符串（例如资源 ID）的长度或格式

请注意：随着时间的推移，我们将更新后向兼容更改的列表。 如果你生成了自己的客户端代理（如 WCF 客户端），我们的建议是，客户端应用程序应准备接收之前未由 Microsoft Graph API 服务定义的属性和派生类型。 Microsoft Graph API 遵循 Microsoft REST API 准则中模型版本控制部分描述的指导。

版本

以下版本的 Microsoft Graph API 目前可用。

Beta 版

通常，API在 beta 版本中首次亮相，并且可以在 https://graph.microsoft.com/beta 终结点中访问。 如需了解 beta API 文档，请参阅 Microsoft Graph beta 终结点参考。 预计在 beta 版中将会不时对 API 进行重大更改和弃用。 不要对 beta API 进行生产依赖。

我们无法保证 beta 功能将升级至当前版本。 当 Microsoft 图形 API 团队认为 beta 功能已准备好正式发布时，我们会将该功能添加到最新版本。 如果提升该功能会导致对当前版本进行中断性变更，则版本号将递增，新版本将成为当前版本。 我们的开发人员社区可以在 Microsoft 365 开发人员平台创意论坛上发布功能请求，包括新功能请求和将现有 beta API 推广到当前版本的请求。

当前版本

Microsoft Graph 的当前版本为 v1.0。 Microsoft Graph API v1.0 版本在 https://graph.microsoft.com/v1.0 中公开，包含可正式发布和可用于生产的功能。 浏览 v1.0 API 的文档。

预览状态

Microsoft Graph 中的 API 或功能标记为“ (预览) ”，以指示其行为在 beta 终结点中 是唯一 的。

v1.0 版本中大多数 API 行为和功能与 Beta 版本相同。 在以下两种情况之一中，“预览”限定了少数 API 和功能：

  • 仅可在 Beta 中使用
  • Beta 版中提供的内容与 v1.0 不同

与 Beta 终结点中的任何其他 API 一样，在文档中标记为“（预览）”的 API 可能会遇到重大更改，恕不另行通知。 请勿从生产应用中的 beta 终结点访问 API。

例如，攻击模拟培训是 Microsoft 365 Defender 门户中管理员通常可以使用的一项功能。 当用于攻击模拟训练的 REST API 仅在 beta 终结点的 Microsoft Graph 中可用时，REST API 文档 将标记为“ (预览) ”。 “(预览)”标签适用于 Microsoft Graph 中的 REST API 及其文档，即使服务本身通常可用。

已弃用和不支持的版本

目前没有弃用的 Microsoft Graph 版本。

使用条款

使用 Microsoft Graph API 即表示你同意 Microsoft API 使用条款。

你的反馈对我们非常重要。 在 Microsoft Q&A 上联系我们。 使用 [microsoft-graph-*] 标记安全。