OData API 版本控制

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022

Azure DevOps 分析提供与针对特定版本的客户端兼容的版本化 OData API。每个版本可能包含增强功能和非中断性变更，而后续版本中将引入中断性变更。

API 版本遵循 _odata 请求路径中的元素，可以是受支持的版本之一： v1.0、 v2.0、 v3.0-preview 或 v4.0-preview。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/$metadata

注意

Azure DevOps Services 中所有服务的生产中会自动启用并支持 Analytics 服务。 Power BI 集成和对 Analytics 服务 OData 源的访问已正式发布。建议你使用 Analytics OData 源并提供反馈。

可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。有关详细信息，请参阅 OData API 版本控制。

注意

Azure DevOps Server 2020 及更高版本的所有新项目集合都会自动安装并在生产环境中支持 Analytics 服务。 Power BI 集成和对 Analytics 服务 OData 源的访问已正式发布。建议你使用 Analytics OData 源并提供反馈。如果从 Azure DevOps Server 2019 升级，可以在升级期间安装 Analytics 服务。

可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。有关详细信息，请参阅 OData API 版本控制。

版本之间的差异

v1.0 和 v2.0：OData API 的已发布版本稳定，不包括中断性变更。 v2.0 包括与 v1.0 相比的增强功能和更多功能。

v3.0-preview 和 v4.0-preview：预览版本可能包括中断性变更，不能保证在最终版本中具有相同的功能。它们提供对已发布版本中尚不可用的新功能和改进的早期访问。

为什么选择特定版本？

稳定性： 如果需要稳定且可靠的 API 而不进行中断性变更，则应选择其中一个已发布版本（v1.0 或 v2.0）。
新功能： 如果要利用最新功能和改进，可以选择预览版之一（v3.0-preview 或 v4.0-preview）。但是，这些版本可能包括重大更改，并且随时可能会更改。
兼容性： 确保所选的版本与现有客户端和系统兼容。 API 版本遵循 _odata 请求路径中的元素，可以是受支持的版本之一：v1.0、v2.0、v3.0-preview 或 v4.0-preview。

每个版本支持的实体集

有关每个 API 版本支持哪些 EntitySet 的信息，请参阅分析、实体的数据模型。

版本生命周期

每个版本的 OData API 在其生命周期内都经历以下三个阶段。

1. 预览阶段

我们会在 API 的未来版本中发布并合并所有重大变更。为了尽早提供此功能，我们在预览模式下发布新版本。在版本处于预览模式时，仍可能进行中断性变更，并且不能保证预览版中包含的内容包含在已发布版本中。版本预览版在发布后至少六周可用。

2. 已发布

预览版成熟且准备好发布后，就会去掉 -preview 后缀并正式发布。已发布的版本不包括重大变更，尽管数据模型可能仍会通过增加功能来扩展。我们对已发布版本至少提供 12 个月的支持。

3. 已弃用

不再支持已弃用的版本，并且不满足对这些版本的请求。如果尝试请求已弃用或不受支持的版本，则会收到 HTTP 410 响应代码和消息，例如：

Analytics 的 {version} OData 终结点不受支持。此处提供了有关最新推荐版本的信息： https://go.microsoft.com/fwlink/?linkid=856818

重大更改与非重大更改

Analytics 公开的数据模型定义服务与其客户端之间的协定。根据 OData 规范，客户端必须能够容忍对数据模型的累加性更改。未来版本中将引入中断性变更。有关详细信息，请参阅 OData 版本 4.0 第 5 部分：版本控制。

注意

系统不会对任何自定义工作项字段进行版本控制。系统不会对任何自定义工作项字段进行版本控制。删除或更改工作项或自定义字段的类型可能会导致模型发生重大更改。所有工作项及其修订都反映当前的自定义域配置。

非中断性变更示例

请考虑一种场景，其中向 User 实体添加一个新的 UserType 属性。例如，v1.0 版本的元数据显示在以下语法中。

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- New User Type property -->
    <Property Name="UserType" Type="Edm.Int32">
        <Annotation Term="Display.DisplayName" String="User Type"/>
    </Property>
    <!-- New User Type property -->
</EntityType>

在 v4.0-preview 版本中，元数据通过累加性更改进行扩充。这些更改也可以在早期版本中提供。

<EntityType Name="User">
  <Key>
    <PropertyRef Name="UserSK"/>
  </Key>
  <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="UserId" Type="Edm.Guid">
    <Annotation Term="Display.DisplayName" String="User Id"/>
  </Property>
  <Property Name="UserName" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Name"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="UserEmail" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Email"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="GitHubUserId" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="GitHub User Id"/>
  </Property>
  <Property Name="UserType" Type="Microsoft.VisualStudio.Services.Analytics.Model.UserType">
    <Annotation Term="Display.DisplayName" String="User Type"/>
  </Property>
</EntityType>

重大变更的示例

假设我们恢复到User实体的原始结构，从而移除之前可用的某个功能。

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid" Nullable="false">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- User Type property has been removed -->
</EntityType>

由于删除 UserType 字段是一项中断性变更，因此在 API 版本 v2.0 之前不会删除该字段。数据模型的 v1.0 版本继续包含UserType该字段。

反馈

此页面是否有帮助？

Last updated on 2026-05-13