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

项目
06/13/2024

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

支持策略和弃用信息

Microsoft Graph REST API 的新版本发布后，早期版本将停用。 Microsoft 会在停用某个版本之前至少 24 个月声明其为弃用版本。同样，对于在正式版 (正式发布) 的单个 API，Microsoft在从 GA 版本中删除 API 之前至少 24 个月声明为已弃用。

对于Microsoft Graph SDK，仅支持任何给定库的最新主版本，并使用新功能、bug 修复和解决方法进行更新。自最新主版本发布日期起 12 个月内，支持在最新版本之前的主要版本，仅用于安全修复。建议尽可能升级到最新版本的 SDK。

例如，当我们将 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 Graph 的当前版本为 v1.0。这些 API 可在终结点中 https://graph.microsoft.com/v1.0 访问。 Microsoft Graph API v1.0 版本包含已正式发布且可供生产使用的功能。有关 v1.0 API 文档，请参阅 Microsoft Graph v1.0 终结点参考。

预览状态

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

v1.0 版本中大多数 API 行为和功能与 Beta 版本相同。由于以下原因之一，某些 API 被标记为“预览版”：

API 仅在 beta 版中可用
API 在 beta 中的行为与 v1.0 不同

与 beta 终结点中的任何其他 API 一样，我们可以对标记为预览版的 API 引入中断性变更，而无需通知。请勿从生产应用中的 beta 终结点访问 API。

注意： 即使功能或产品本身已正式发布，API 也可以处于预览状态。

已弃用和不支持的版本

目前，没有 Microsoft Graph 版本已弃用或不受支持。

使用条款

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

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

通过