OData API 版本控制

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

注意

分析服务在所有 Azure DevOps Services 的生产中自动启用和支持。 对 Analytics Service 的 OData 源的 Power BI 集成和访问已正式发布。 我们鼓励你使用它并提供反馈。 可用数据依赖于版本。 支持的最新版本是 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 部分：版本控制。

注意

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

非中断性变更示例

请考虑将新 UserType 属性添加到实体的方案 User 。 例如，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该字段。

相关文章

• Analytics 数据模型
• OData 版本 4.0 第 5 部分：版本控制