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 服務。 Power BI 整合 及存取 Analytics 服務的 OData 摘要 已正式推出。 建議您使用 Analytics OData 摘要並提供意見反應。

可用的數據與版本相關。 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 回應碼和訊息，例如：

不支援分析的 {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 2.0 版之前，不會移除欄位。 數據模型的 v1.0 版會繼續包含 UserType 欄位。

相關文章

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