Microsoft Graph 的版本控制、支持和中断性变更策略Versioning, support, and breaking change policies for Microsoft Graph

本文介绍了 Microsoft Graph 的支持和重大更改策略,以及当前可用的 Microsoft Graph API 版本。This article describes the support and breaking change policies for Microsoft Graph and the versions of the Microsoft Graph API that are currently available.

支持策略和弃用信息Support policy and deprecation information

Microsoft Graph 遵循 Microsoft 生命周期策略Microsoft Graph follows the Microsoft Lifecycle Policy.

由于已发布新版本的 Microsoft Graph REST API 和 Microsoft Graph SDK,之前的版本将停用。Microsoft 将在停用 API 或 SDK 之前至少 24 个月声明弃用的版本。As new versions of the Microsoft Graph REST APIs and Microsoft Graph SDKs are released, earlier versions will be retired. Microsoft will declare a version as deprecated at least 24 months in advance of retiring an API or an SDK.

递增 API 的主要版本(例如,从 v1.0 到 v2.0)时,我们将通知立即弃用当前版本(在此示例中为 v1.0),在通知 24 个月后,我们将不再支持该版本。When we increment the major version of the API (for example, from v1.0 to v2.0), we are announcing that the current version (in this example, v1.0) is immediately deprecated and we will no longer support it 24 months after the announcement. 出于服务安全或运行状况可靠性问题的考虑,我们可能会对此策略作例外处理。We might make exceptions to this policy for service security or health reliability issues.

当 API 被标记为已弃用时,我们强烈建议你尽快迁移到最新版本。When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. 某些情况下,我们将公布新应用程序必须在原始 API 弃用后不久开始使用新的 API。In some cases, we will announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated. 在这些情况下,仅当前使用已弃用 API 的活动应用程序能够继续使用它们。In those cases, only active applications that currently use the deprecated APIs can continue to use them.

API 协定和非后向兼容更改API contract and non-backward compatible changes

Microsoft Graph 在版本中进行了许多更改。这些更改已在 Microsoft Graph 更改日志中列出。随着向 Microsoft Graph 中添加新功能和数据,我们将递增 API 版本号,以对 API 进行任意不向后兼容更改。Microsoft Graph has a log of changes across versions. These changes are listed in the Microsoft Graph Changelog. As new functionality and data is added to Microsoft Graph, we will increment the API version number for any non-backward compatible changes to the API.

非后向兼容更改的示例如下:The following are examples of non-backward compatible changes:

  • 对与资源关联的 URL 或基本请求/响应进行更改Changes to the URL or fundamental request/response associated with a resource
  • 删除、重命名或更改声明的属性的类型Removal, rename, or change to the type of a declared property
  • 删除或重命名 API 或 API 参数Removal or rename of APIs or API parameters
  • 添加所需的请求标头Addition of a required request header

向后兼容的更改示例如下:The following are examples of backward compatible changes:

  • 添加可为 Null 或具有默认值的属性Addition of properties that are nullable or have a default value
  • 向枚举添加成员Addition of a member to an enumeration
  • 删除、重命名或更改开放扩展的类型Removal, rename, or change to the type of an open extension
  • 删除、重命名或更改注释的类型Removal, rename, or change to the type of an annotation
  • 向现有集合引入分页Introduction of paging to existing collections
  • 更改错误代码Changes to error codes
  • 更改属性的顺序Changes to the order of properties
  • 更改不透明字符串(如资源 ID)的长度或格式Changes to the length or format of opaque strings, such as resource IDs

注意: 随着时间的推移,我们将更新向后兼容更改的列表。如果你生成了自己的客户端代理(如 WCF 客户端),我们的建议是,客户端应用程序应准备接收之前未由 Microsoft Graph API 服务定义的属性和派生类型。Microsoft Graph API 遵循 Microsoft REST API 准则模型版本控制部分中描述的指导。Note: Over time, we will update the list of backward compatible changes. If you generate your own client proxies (like WCF clients), our guidance is that your client applications should be prepared to receive properties and derived types not previously defined by the Microsoft Graph API service. Microsoft Graph API follows the guidance described in the Model Versioning section in the Microsoft REST API guidelines.


以下版本的 Microsoft Graph API 目前可用。The following versions of the Microsoft Graph API are currently available.

Beta 版Beta version

通常,API在 beta 版本中首次亮相,并且可以在 终结点中访问。In general, APIs debut in the beta version and are accessible in the endpoint. 如需了解 beta API 文档,请参阅 Microsoft Graph beta 终结点参考For beta API documentation, see Microsoft Graph beta endpoint reference. 预计将不时地对 beta 版本进行重大更改。Expect breaking changes to the beta version from time to time. 请勿对 /beta API 产生生产依赖性。Do not take a production dependency on /beta APIs.

我们无法保证将测试功能升级至当前版本。当 Microsoft Graph API 团队认为测试功能可正式发布 (GA) 时,我们将把该功能添加到最新的当前版本中。如果功能升级将导致当前版本出现重大更改,则版本号将递增,而新版本将成为当前版本。我们的开发者社区可以在 UserVoice 上发布功能请求,包括对新功能的请求以及将现有的测试 API 升级到当前版本的请求。We make no guarantees that a beta feature will be promoted to the current version. When the Microsoft Graph API team believes that a beta feature is ready for general availability (GA), we will add that feature to the latest current version. If the promotion of the feature would result in a breaking change to the current version, the version number will be incremented, with the new version becoming the current version. Our developer community can post feature request on UserVoice, including requests for new features as well as requests to promote existing beta APIs to the current version.

当前版本Current version

Microsoft Graph 的当前版本为 v1.0。Microsoft Graph API /v1.0 版本在 中公开,包含可正式发布和可用于生产的功能。可以浏览 v1.0 API 文档The current version of Microsoft Graph is v1.0. Exposed under, the Microsoft Graph API /v1.0 version contains features that are generally available and ready for production use. Browse the documentation for the v1.0 APIs.

预览状态Preview status

功能或 API 标记为“(预览)”,以表示其行为在 beta 终结点中为_唯一_。A feature or API is labelled as "(preview)" to indicate its behavior is unique in the beta endpoint.

v1.0 版本中大多数功能和 API 行为与 Beta 版本相同。The behavior of most features and APIs in the v1.0 version is in parity with the beta version. 在以下两种情况之一中,“预览”限定了少数功能和 API:"preview" qualifies a minority of features and APIs in one of the following two cases:

  • 仅可在 Beta 中使用Available in only beta
  • Beta 版中的提供的内容与 v1 不同Available in beta differently than in v1

与 Beta 终结点中的任何其他 API 一样,在文档中标记为“(预览)”的 API 可能会遇到重大更改,恕不另行通知。Like any other API in the beta endpoint, APIs marked in the documentation as "(preview)" may experience breaking changes without notice. 请勿从生产应用程序中的 beta 终结点访问 API。Do not access APIs from the beta endpoint in production apps.

已弃用和不支持的版本Deprecated and unsupported versions

目前没有弃用的 Microsoft Graph 版本。There are currently no deprecated versions of Microsoft Graph.

使用条款Terms of use

使用 Microsoft Graph API 即表示你同意 Microsoft API 使用条款By using the Microsoft Graph APIs, you agree to the Microsoft APIs Terms of Use.

你的反馈对我们非常重要。Your feedback is important to us. 请在 StackOverflow 上与我们联系。Connect with us on StackOverflow. 使用 [microsoft-graph] 标记安全。Tag your questions with [microsoft-graph].