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
https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/$metadata
注意
Analytics サービスは、すべてのAzure DevOps Servicesの運用環境で自動的に有効になり、サポートされます。
Power BI の統合 と、Analytics Service の OData フィード へのアクセスが一般公開されています。 使用してフィードバックを送信することをお勧めします。
使用可能なデータはバージョンに依存します。 サポートされている最新バージョンは であり v2.0
、最新のプレビュー バージョンは です v4.0-preview
。 詳細については、「 OData API のバージョン管理」を参照してください。
注意
Analytics サービスは、Azure DevOps Server 2020 以降のバージョンのすべての新しいプロジェクト コレクションに対して、運用環境で自動的にインストールされ、サポートされます。 Power BI の統合 と、Analytics Service の OData フィード へのアクセスが一般公開されています。 使用してフィードバックを送信することをお勧めします。 2019 Azure DevOps Serverからアップグレードした場合は、アップグレード中に Analytics サービスをインストールできます。
使用可能なデータはバージョンに依存します。 サポートされている最新バージョンは であり v2.0
、最新のプレビュー バージョンは です v4.0-preview
。 詳細については、「 OData API のバージョン管理」を参照してください。
注意
Analytics サービスは、Azure DevOps Server 2019 のプレビュー段階です。 プロジェクト コレクションに対 して有効またはインストール できます。 Power BI 統合 と Analytics サービスの 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
。