OData API 版本控制

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

随着 Analytics 服务的成熟，我们致力于为用户提供一致性和可靠性。 因此，Analytics for Azure DevOps 提供版本控制 OData API，该 API 与针对这些版本设计的客户端兼容。 可以通过更多功能和非中断性变更来增强每个版本。 不兼容或中断性变更将滚动到 API 的未来版本。

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

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

注意

Analytics 服务在生产环境中自动启用并支持所有Azure DevOps Services。 Power BI 集成 和对分析服务的 OData 源 的访问已正式发布。 我们鼓励你使用它并向我们提供反馈。 可用数据依赖于版本。 支持的最新版本是 v2.0，最新的预览版本是 v4.0-preview。 有关详细信息，请参阅 OData API 版本控制。

预览版

• v3.0-preview
• v4.0-preview

已发布版本

• v1.0
• v2.0

每个版本支持的实体集

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

版本生命周期

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

预览

所有中断性变更将在 API 的未来版本中合并并一起发布。 若要尽早提供此功能，请在 预览 模式下发布新版本。 当版本处于预览模式时，仍可能发生中断性变更。 此外，不保证预览版中包含的内容将包含在已发布版本中。

版本预览版在发布后至少 6 周内可用。

Released（已释放）

预览版本成熟到足以发布后，它将在没有 -preview 后缀的情况下可用。 不会对已发布版本引入中断性变更，但数据模型仍可能会随着附加功能而增长。 发布的版本将至少支持 12 个月。

已放弃

不再支持已弃用的版本。 不会满足对已弃用版本发出的请求。 如果尝试请求已弃用或不受支持的版本，将收到 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 预览 版，元数据已扩充。 更改是累加的，可以在以前的版本中提供。

<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 部分：版本控制