分析のベスト プラクティス

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

Analytics は Azure DevOps のレポート プラットフォームであり、データから洞察を得て、データ主導の意思決定を行うことができます。 Analytics は、高速な読み取りアクセスとサーバー ベースの集計用に最適化されており、データを視覚化して分析するためのさまざまなツールを提供します。 この記事では、Azure DevOps で Analytics を使用するためのベスト プラクティスについて説明します。

前提条件

• アクセス: 少なくとも Basic アクセス権を持つプロジェクトのメンバーである。
• 権限: 既定では、プロジェクト メンバーは Analytics にクエリを実行し、ビューを作成する権限を持ちます。
• サービスと機能の有効化と一般的なデータ追跡アクティビティに関するその他の前提条件の詳細については、「Analytics にアクセスするためのアクセス許可と前提条件」を参照してください。

• 拡張機能開発者の場合は、必ず OData Analytics クエリ ガイドラインを確認 してください。

Analytics メタデータについて理解する

Analytics メタデータに対してクエリを実行して、エンティティの種類、エンティティ セット、プロパティ、列挙リストについて理解を深めます。 詳細については、Azure Boards の Analytics サービス、Analytics OData メタデータ、エンティティとプロパティのリファレンスのクエリを参照してください。

必要なデータを返すようにクエリを構成する

レポートを作成するために必要な最小限のデータ セットに対してクエリを実行するには、次のプラクティスに従います。

• 作成するレポートをサポートするエンティティ セットを選択します
• クエリ パーツを実行順序で指定する
• クエリで要求する列を制限する
• プレビュー クエリを作成する
• アクセスできるプロジェクトにクエリを制限する

レポートをサポートするエンティティ セットを選択する

Analytics データ モデルではいくつかの EntitySets サポートがありますが、レポートの生成に使用されるのはごくわずかです。EntitySets レポートの作成に使用されるカテゴリは、次の 3 つに分類されます。

• 現在: 内に含まれている現在の構成に関する情報がEntitySetEntityTypes含まれています。
• スナップショット: 履歴データと日付関連データを組み合わせた複合エンティティ。 スナップショット エンティティは、集計レポートをサポートするために使用することを目的としています。
• リビジョン: 履歴情報が含まれています。 たとえば、 WorkItemRevision 作業項目の履歴に関するデータを保持します。

レポートをサポートするために指定する EntityTypes のクイック リファレンスを次に示します。 これらの EntityTypes の詳細については、Analytics のデータ モデルに関するページを参照してください。

クエリ パーツを実行順序で指定する

さまざまなクエリ 部分に推奨される順序は、評価される順序である次の順序で指定することです。 各クエリ パーツの説明については、「Analytics サービスのクエリ」の「クエリ オプション」を参照してください。

1. $apply
2. $filter
3. $orderby
4. $expand
5. $select
6. $skip
7. $top

すべてのクエリに or $select 句を$apply含める必要があります。そうしないと、警告メッセージが表示されることがあります。

クエリで要求する列を制限する

句を使用して返すデータの列を $select 指定します。 カスタマイズを使用すると、作業項目に多数のフィールドを関連付けることができます。 クエリが参照するプロパティまたはフィールドが多いほど、処理コストが高くなります。 生成するレポートを検討し、必要なフィールドのみを要求していることを確認します。

たとえば、フィルター処理された一連の作業項目の ID、作業項目の種類、タイトル、および状態フィールドを返すには、次 $select の句 $select=WorkItemId, WorkItemType, Title, Stateを指定します。

プロパティとそれに対応するフィールド名の一覧を検索するには、Azure Boards のエンティティとプロパティのリファレンスを参照してください。

プレビュー クエリを作成する

プレビュー クエリは、1 つのレコードまたはレコードの小さなサブセットを返すクエリです。 プレビュー クエリを作成することで、必要なデータを要求するようにクエリを調整できます。 最小限のクエリから始めることで、必要なレコードと必要な列データを確実に指定できるようにクエリを構築できます。

を apply=aggregate($count as Count)使用すると、要求しているレコードの数を識別できます。 たとえば、次の構文では、Fabrikam Fiber プロジェクトの作業項目の数を照会します。

https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $apply=aggregate($count as Count)

応答は、合計 1,415 個の作業項目を返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam Fbier/_odata/v4.0-preview/$metadata#WorkItems(Count)",
   "value": [
  {
     "@odata.id": null,
   "Count": 1415
  }
  ]
}

アクセスできるプロジェクトにクエリを制限する

プロジェクト スコープ クエリは 1 つのプロジェクトに関する情報を返しますが、組織スコープのクエリはプロジェクトの境界を越える情報を返すように設計されています。 組織のスコープクエリでは、プロジェクトのアクセス許可がないためにクエリがブロックされないように、より広範なユーザーアクセス許可または慎重なスコープ制限が必要です。

1 つ以上のプロジェクトにアクセスできるが、すべてのプロジェクトにはアクセスできない場合、組織スコープのクエリを送信すると、エラー メッセージが表示されます。

"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."

詳細については、「プロジェクトと組織スコープのクエリ」を参照してください。

警告とエラー メッセージを確認する

Analytics は、受信した各クエリのルールに対する違反を確認します。 違反を検出すると、警告メッセージが返されます。 これらのメッセージを確認して、クエリ構造を修正または改善することをお勧めします。

関連記事

• Analytics サービスとは
• Analytics の OData クエリを作成する
• Analytics OData メタデータ
• OData Analytics クエリのガイドライン