OData API のバージョン管理

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

Analytics サービスが成熟するにつれて、Microsoft はユーザーに一貫性と信頼性を提供することに専念しています。 そのため、Analytics for Azure DevOps には、これらのバージョン用に設計されたクライアントと互換性のあるバージョン管理された OData API が用意されています。 各バージョンは、より多くの機能と破壊的変更によって強化される場合があります。 互換性のない変更や破壊的変更は、今後のバージョンの API にロールインされます。

API バージョンは要求パスの _odata 要素に従い、サポートされているバージョンの 1 つとして 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 の統合 と、Analytics Service の OData フィード へのアクセスが一般公開されています。 使用してフィードバックを送信することをお勧めします。 使用可能なデータはバージョンに依存します。 サポートされている最新バージョンは であり v2.0、最新のプレビュー バージョンは です v4.0-preview。 詳細については、「 OData API のバージョン管理」を参照してください。

プレビュー バージョン

• v3.0 プレビュー
• v4.0-preview

リリースされたバージョン

• v1.0
• v2.0

各バージョンでサポートされているエンティティ セット

各 API バージョンでサポートされている EntitySet の詳細については、「 Data model for Analytics, Entities」を参照してください。

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

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

プレビュー

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

バージョンのプレビューは、リリース後少なくとも 6 週間利用できるようになります。

リリース済み

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

非推奨

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

分析用 {version} OData エンドポイントはサポートされていません。 最新の推奨バージョンに関する情報については、こちらを参照してください。 https://go.microsoft.com/fwlink/?linkid=856818

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

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

Note

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

破壊的でない変更の例

エンティティに新 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: バージョン管理