Analytics のデータ モデル

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

Azure DevOps の Analytics データ モデルはエンティティ セットで構成され、そのメンバー (エンティティ) には、フィルター処理、集計、集計できるプロパティが含まれています。 さらに、エンティティを相互に関連付ける ナビゲーション プロパティ を含み、選択、フィルター処理、グループ化のための他のプロパティへのアクセスを提供します。

Analytics データ モデルについて

Analytics サービスは、OData エンドポイントを介して Azure DevOps データにアクセスするための構造化されたアプローチを提供します。 このデータ モデルを使用すると、次のことが可能になります。

• 作業追跡データのクエリ: 作業項目、領域、イテレーション、および関連メタデータにアクセスする
• パイプライン情報の分析: ビルド およびリリース パイプライン データのクエリを実行する
• テスト結果に関するレポート: テストの実行と計画データにアクセスする
• カスタム レポートの作成: Power BI レポートとその他の分析ソリューションを構築する

スキーマ名前空間

Analytics データ モデルは、次の 2 つのスキーマ名前空間で動作します。

• Microsoft.VisualStudio.Services.Analytics.Model
• Microsoft.VisualStudio.Services.Analytics

これらの名前空間はエンティティを整理し、その構造を定義し、さまざまな Azure DevOps 機能間で一貫したデータ アクセス パターンを確保します。

エンティティ セットとエンティティ型

エンティティ型は、キーを持つ名前付き構造化型です。 各エンティティの名前付きプロパティとリレーションシップを定義します。 EntityType のキーは、WorkItemId、PipelineId、ReleasePipelineId などのプリミティブプロパティのサブセットおよびエンティティ型のその他のプロパティから構成されます。

エンティティ セットは、エンティティの名前付きコレクションです。 たとえば、 WorkItems は、 WorkItem エンティティを含むエンティティ セットです。 エンティティのキーは、エンティティ セット内のエンティティを一意に識別します。 複数のエンティティ セットで同じエンティティ型が使用されている場合、キー値の同じ組み合わせを複数のエンティティ セットに表示し、異なるエンティティ (このキーの組み合わせが表示されるエンティティ セットごとに 1 つ) を識別できます。 これらのエンティティはそれぞれ異なるエンティティ ID を持っています。エンティティ セットは、データ モデルへのエントリ ポイントを提供します。

エンティティ セットは OData メタデータで記述され、プロジェクトによって異なります。 プロジェクトの OData メタデータを要求することで、エンティティ セット、エンティティ型、プロパティの完全な一覧を調べることができます。 方法については、「 Analytics の OData クエリを作成するを参照してください。

複合エンティティ

複合エンティティは、特定のシナリオをサポートします。 システムは、より単純なエンティティからそれらを構成し、多くの場合、生成するコンピューティング リソースを増やす必要があり、より大きな結果セットを返す可能性があります。 最適なパフォーマンスを実現し、不要な調整を回避するには、シナリオに合わせて正しいエンティティに対してクエリを実行してください。

たとえば、WorkItemSnapshotWorkItemRevisionsとDatesを組み合わせて、各日付に作業項目ごとに 1 つのリビジョンが設定されるようにします。 この表現は、フィルター処理された一連の作業項目の傾向データに焦点を当てる OData クエリをサポートします。 ただし、この複合エンティティを使用して作業項目の現在の状態を照会しないでください。 代わりに、 WorkItems エンティティ セットを使用して、より迅速に実行されるクエリを生成する必要があります。

同様に、一部のエンティティにはすべての履歴値が含まれる場合もあれば、現在の値のみを含むエンティティもあります。 WorkItemRevisions にはすべての作業項目履歴が含まれています。現在の値が関心のあるシナリオでは使用しないでください。

リレーションシップ

より複雑なクエリ結果を生成するには、リレーションシップを使用してエンティティを結合します。 リレーションシップを使用して、データの拡張、フィルター処理、集計を行うことができます。

一部のナビゲーション プロパティでは 1 つのエンティティが生成され、その他のプロパティはエンティティのコレクションになります。 次の図は、選択エンティティとそのナビゲーション プロパティを示しています。 わかりやすくするために、一部の複合エンティティとリレーションシップは省略されています。

エンティティのリレーションシップについて

Analytics データ モデルでは、いくつかの種類のリレーションシップが使用されます。

• 一対多: 単一の親エンティティが複数の子エンティティに関連します（例：1つの領域から多くの作業項目）。
• 多対一: 複数のエンティティが1つの親エンティティに関連する（例: 多数のWorkItemが1つの領域に関連する場合）
• 1 対 1: 1 つのエンティティが、他の 1 つのエンティティに正確に関連付けられます
• 多対多: 複数のエンティティが複数の他のエンティティに関連します（例: WorkItems が Tags に関連する場合）

リレーションシップ キー

外部ツールがエンティティを結合できるように、エンティティリレーションシップも外部キーとして表されます。 これらのプロパティにはサフィックス "SK" があり、整数または GUID のデータ型です。 日付プロパティには、 YYYYMMDDという形式の、対応する整数の日付キー プロパティがあります。

作業追跡エンティティの種類とエンティティ セット

指定された API バージョンでは、次のエンティティ型とエンティティ セットがサポートされています。 完全なリファレンスについては、「 Work tracking metadata reference for Azure Boards Analytics(Azure Boards Analytics の作業追跡メタデータ リファレンスを参照してください。

レポート用の主要な作業追跡エンティティ

レポートを作成するときは、次のプライマリ エンティティ セットを検討してください。

• 現在の状態レポート: 現在の作業項目の状態に WorkItems を使用する
• 履歴傾向レポート: 時間の経過に伴う傾向分析に WorkItemSnapshot を使用する
• 詳細な変更追跡: 包括的な履歴に WorkItemRevisions を使用する
• ボード固有のレポート: かんばんボード分析に WorkItemBoardSnapshot を使用する

Analytics データ モデルを使用するためのベスト プラクティス

パフォーマンスの最適化

1. 適切なエンティティを選択する: 状態レポートに現在の状態エンティティ (WorkItems) を使用し、傾向のスナップショット エンティティを使用する
2. 早期フィルター: データ取得後ではなくエンティティ レベルでフィルターを適用する
3. データ範囲の制限: 日付フィルターを使用して履歴データ クエリを制限する
4. 適切な集計を使用する: 可能な場合は組み込みの集計関数を活用する

クエリのデザイン パターン

現在の状態クエリ

/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State

履歴傾向クエリ

/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK

リレーションシップ ナビゲーション

/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)

回避する一般的な落とし穴

• 現在の状態にリビジョン エンティティを使用する: WorkItemRevisionsで十分な場合はWorkItemsを使用しないでください
• リレーションシップを拡張しすぎ: 必要なナビゲーション プロパティのみを展開する
• 不足しているフィルター: 常に大きなエンティティ セットをフィルター処理してパフォーマンスを向上させる
• 複合エンティティの無視: 傾向分析に WorkItemSnapshot などの複合エンティティを使用する

バージョンに関する考慮事項

API のバージョンが異なると、さまざまな機能が提供されます。

• v1.0: 基本的な作業追跡エンティティ
• v2.0: プロセスと強化されたフィルター機能を追加しました
• v3.0-preview: パイプラインとテスト エンティティを追加しました
• v4.0-preview: 強化された複合エンティティと追加のパイプライン メトリック

レポートの要件とアクセスする必要があるエンティティに基づいて、適切なバージョンを選択します。

関連記事

• OData Analytics クエリのガイドライン
• WIT 分析
• データの集計
• Analytics OData メタデータの探索
• 作業の追跡、処理、およびプロジェクトの制限
• Analytics ビューのデータセットの設計
• Analytics の OData クエリを作成する
• 分析のセキュリティとアクセス許可