OData API 版本控制

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

隨著 Analytics 服務成熟，我們專用於為使用者提供一致性和可靠性。 因此，適用于 Azure DevOps 的分析會提供版本化 OData API，其與針對這些版本設計的用戶端相容。 每個版本都可以使用更多功能和非中斷性變更來增強。 不相容或重大變更將會匯總至未來的 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 服務。 Power BI 整合 和存取 Analytics Service 的 OData 摘要 已正式推出。 我們鼓勵您使用它，並提供意見反應給我們。 可用的資料與版本相依。 最新支援的版本為 v2.0 ，而最新的預覽版本為 v4.0-preview 。 如需詳細資訊，請參閱 OData API 版本設定。

預覽版本

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

發行的版本

• v1.0
• v2.0

每個版本支援的實體集

如需每個 API 版本所支援 EntitySet 的相關資訊，請參閱 分析、實體的資料模型。

版本生命週期

每個版本的 OData API 都會在其生命週期期間經歷三個階段。

預覽

所有重大變更都會在未來的 API 版本中合併併發行。 若要儘快提供這項功能，請以 預覽 模式妥善發行新版本。 當版本處於預覽模式時，仍可能進行重大變更。 此外，不保證預覽版本中所包含的內容將會包含在發行的版本中。

在發行版本本之後，版本預覽至少可使用六周。

已發行

一旦預覽版本成熟足以供發行使用，它就會在沒有 -preview 尾碼的情況下提供。 不會對發行的版本引進任何重大變更，但資料模型仍可能會隨著加法功能而成長。 發行的版本至少支援 12 個月。

已被取代

不再支援已淘汰的版本。 對已淘汰版本提出的要求將無法完成。 如果您嘗試要求已被取代或不支援的版本，您會收到 HTTP 410 回應碼和如下的訊息：

不支援 {version} 適用于 Analytics 的 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>

重大變更的範例

現在，請考慮我們還原為使用者實體的原始結構，導致移除先前可用的功能。

<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 2.0 版之前，將不會移除欄位。 資料模型的 v1.0 版會繼續包含 UserType 欄位。

相關文章

• 分析的資料模型
• OData 4.0 版第 5 部分：版本控制