プロジェクトと組織スコープのクエリ

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

Azure DevOps 用の Analytics を使用すると、プロジェクトまたは組織またはコレクションを対象とするクエリを作成できます。 これらのクエリは、ブラウザーまたは Power BI 内で直接実行できます。

プロジェクト スコープ クエリは、1 つのプロジェクトに関する質問に回答するのに役立ちますが、組織とコレクションのスコープクエリでは、プロジェクトの境界を越えた質問に回答できます。 組織およびコレクションスコープのクエリでは、アクセス許可がないためにクエリがブロックされないように、より広範なユーザーアクセス許可または慎重なスコープ制限が必要です。

Note

Analytics サービスは、すべての Azure DevOps Services で自動的に有効になり、運用環境でサポートされます。 Power BI の統合 Analytics サービスの OData フィード へのアクセスが一般公開されています。 お使いいただき、フィードバックをお寄せください。 使用可能なデータはバージョンによって異なります。 サポートされている最新バージョンが v2.0され、最新のプレビュー バージョンが v4.0-preview。 詳細については、 OData API のバージョン管理に関するページを参照してください。

前提条件

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

重要

組織内のすべてのプロジェクトにアクセスできない場合は、すべてのクエリにプロジェクト フィルターを適用することをお勧めします。 Power BI や Excel などのクライアント ツールにデータをプルする場合、すべてのデータが特定のプロジェクトによって制約されるようにするには、プロジェクト パス構文を使用するのが最適な方法です。 2 つ以上のプロジェクトについてレポートする必要がある場合にのみ、組織スコープまたはコレクション スコープのクエリを使用することをお勧めします。

プロジェクト スコープクエリ

サポートされている Web ブラウザーに OData URL を入力してクエリを作成。

プロジェクト レベルの OData クエリのベース URL は、次の構文に示されています。

Cloud (Azure DevOps Services

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

提供されている例では、 {OrganizationName} と {ProjectName} を、クエリを実行する組織とプロジェクトの名前に置き換えます。

オンプレミス (Azure DevOps Server

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/

提供されている例では、次の置き換えを行います。

• {ServerName}:{Port}/tfs/ を含む analytics.dev.azure.com
• {CollectionName} プロジェクト コレクション名 (既定値は DefaultCollection)
• {ProjectName} クエリを実行するプロジェクトの名前を指定します。

Note

この記事で提供される残りの例は、Azure DevOps Services URL に基づいています。 例を実行するには、Azure DevOps サーバーの URL に置き換える必要があります。

作業項目の数を返す

たとえば、次のプロジェクト スコープクエリは、特定のプロジェクトの作業項目の数を返します。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

たとえば、Fabrikam Fiber プロジェクトのクエリでは、7126 個の作業項目の数が返されます。 削除された作業項目はカウントに含まれません。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

プロジェクト領域パスを返す

同様に、次のクエリ文字列は、特定のプロジェクトの領域を返します。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

これは、組織スコープのクエリに対する次のフィルターと同じです。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

たとえば、Fabrikam Fiber プロジェクトのクエリでは、 $select 演算子がクエリに適用されていないため、エリア パスに対して定義されているすべてのプロパティが返されます。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

次の例は、1 つのエリア パスに対して返されるデータを示しています。

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

$expand オプションの使用

$expand オプションでプロジェクト スコープのクエリを使用する場合は、他のフィルターを指定する必要はありません。

たとえば、次のプロジェクト スコープ フィルターです。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

は、セキュリティを適用するために自動的にフィルター処理されます。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

組織スコープのクエリ

組織レベルのクエリのベース URL は次のとおりです。

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

$expand オプションで組織スコープのクエリを使用する場合は、別のフィルターを指定する必要があります。

たとえば、次の組織スコープのクエリでは、 $expand を使用してすべての作業項目の子を取得します。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

子が指定されたプロジェクトに制限されていることを確認するには、別のフィルターが必要です。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

すべての作業項目の親を返す

次のクエリでは、 $expand オプションを使用して、すべての作業項目の親を取得します。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

親が指定されたプロジェクトに制限されていることを確認するには、別のフィルターが必要です。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

他のフィルターがないと、作業項目の親が読み取りアクセス権を持たないプロジェクト内の作業項目を参照している場合、要求は失敗します。

プロジェクト レベルのセキュリティ制限

Analytics には、プロジェクト レベルのセキュリティに関連するクエリ構文に関するいくつかの制限があります。

anyフィルターまたはall フィルターは、$expandの基本エンティティに適用されます。 プロジェクトに基づくフィルターの場合、 $expandを使用する場合、フィルターは明示的に無視されます。

たとえば、以下のクエリ:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

次のように解釈されます。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

すべてのプロジェクトにアクセスできない場合は失敗します。

この制限を回避するには、 $filterに式を追加する必要があります。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

$levelの使用は、コレクション内のすべてのプロジェクトにアクセスできる場合、またはプロジェクト スコープクエリを使用する場合にのみサポートされます。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

analytics では、 $it 句を使用したプロジェクトのクロスレベル参照はサポートされていません。 たとえば、次のクエリでは、サポートされていない$itエイリアスを使用してルート作業項目のProjectNameを参照しています。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

次のステップ

集計データのクエリ

関連記事

• クエリのガイドライン