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

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

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

前提条件

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

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

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

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

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

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

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

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

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

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

レポートをサポートするために指定する EntityTypes のクイック リファレンスを次に示します。 これらの EntityTypes の詳細については、「 Data model for Analytics」を参照してください。

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

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

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

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

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

$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."

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

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

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

関連記事

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