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

Note

Analytics サービスは、すべての Azure DevOps Services で自動的に有効になり、運用環境でサポートされます。 Power BI の統合 Analytics サービスの OData フィード へのアクセスが一般公開されています。 お使いいただき、フィードバックをお寄せください。 使用可能なデータはバージョンによって異なります。 サポートされている最新バージョンが v2.0され、最新のプレビュー バージョンが v4.0-preview。 詳細については、 OData API のバージョン管理に関するページを参照してください。

バージョン間の違い

v1.0 および v2.0: Released バージョンの OData API は安定しており、破壊的変更は含まれません。 v2.0 には、v1.0 と比較して機能強化とより多くの機能が含まれています。

v3.0-preview および v4.0-preview: 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 の詳細については、「 Data model for Analytics,Entities」を参照してください。

バージョンのライフサイクル

OData API の各バージョンは、ライフサイクル中に次の 3 つのフェーズを経ます。

1. プレビュー フェーズ

今後のバージョンの API では、破壊的変更をすべて組み合わせてリリースします。 この機能をできるだけ早く使用できるようにするために、 preview モードで新しいバージョンをリリースします。 バージョンがプレビュー モードの間も破壊的変更は引き続き可能であり、プレビュー バージョンに含まれるものがリリース バージョンに含まれるという保証はありません。 バージョンのプレビューは、リリースから少なくとも 6 週間は使用できます。

2. リリース済み

プレビュー バージョンが成熟し、リリースの準備ができたら、 -preview サフィックスなしで使用できるようになります。 リリースされたバージョンには破壊的変更は含まれませんが、データ モデルは引き続きより多くの機能で拡張される可能性があります。 リリースされたバージョンは、少なくとも 12 か月間サポートされています。

3. 非推奨

非推奨のバージョンはサポートされなくなり、これらのバージョンへの要求は満たされません。 非推奨またはサポートされていないバージョンを要求しようとすると、HTTP 410 応答コードと次のようなメッセージが表示されます。

Analytics の {version} OData エンドポイントはサポートされていません。 最新の推奨バージョンに関する情報は、ここで入手できます。 https://go.microsoft.com/fwlink/?linkid=856818

破壊的変更と非破壊的変更

Analytics によって公開されるデータ モデルは、サービスとそのクライアント間のコントラクトを定義します。 OData 仕様に従って、クライアントはデータ モデルに対する追加の変更に対して耐性を持っている必要があります。 破壊的変更は、将来のバージョンで導入されます。 詳細については、「 OData バージョン 4.0 パート 5: バージョン管理を参照してください。

Note

システムでは、ユーザー設定の作業項目フィールドはバージョン管理されません。 システムでは、ユーザー設定の作業項目フィールドはバージョン管理されません。 作業項目またはユーザー設定フィールドの種類を削除または変更すると、モデルが破壊的変更を引き起こす可能性があります。 すべての作業項目とその変更履歴には、現在のユーザー設定フィールドの構成が反映されます。

改行しない変更の例

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 フィールドが含まれます。

関連記事

• Analytics のデータ モデル
• OData バージョン 4.0 パート 5: バージョン管理