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

  • [アーティクル]

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 のデータ モデルに関するページを参照してください。

Azure DevOps データ Current スナップショット リビジョン
Azure Boards WorkItems WorkItemSnapshot
WorkItemBoardSnapshot		 WorkItemRevisions
Azure Pipelines Pipelines
PipelineTasks		 ParallelPipelineJobsSnapshot
PipelineRuns, PipelineRunActivityResults
Azure Pipelines とテスト TestResultsDaily TestRuns
Azure Test Plans Tests
TestConfiguration
TestPoints
WorkItems		 TestResultsDaily
TestPointHistorySnapshot

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

さまざまなクエリ 部分に推奨される順序は、評価される順序である次の順序で指定することです。 各クエリ パーツの説明については、「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 は、受信した各クエリのルールに対する違反を確認します。 違反を検出すると、警告メッセージが返されます。 これらのメッセージを確認して、クエリ構造を修正または改善することをお勧めします。

レートの制限と調整

Azure DevOps Services の Analytics に対して行われたクエリには、レート制限が適用されます。 短時間で大量のデータを返すように要求するクエリが多すぎると、サービスが調整される可能性があります。 詳細については、「レートと使用量の制限」を参照してください。

Organization 設定>Usage に移動し、フィルターを実行することで、サービスと個人の使用状況を確認できます。 たとえば、次の図は、Jamal Hartnett による Analytics サービスへの使用状況を示しています。

1 人のユーザーと分析の [使用状況] ページのスクリーンショット。