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

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 のバージョン管理に関するページを参照してください。

前提条件

• 分析データを表示してサービスにクエリを実行するには、 Basic アクセス以上のプロジェクトのメンバーである必要があります。 既定では、すべてのプロジェクト メンバーには、Analytics のクエリと 分析ビューの定義に対するアクセス許可が付与されます。
• サービスと機能の有効化と一般的なデータ追跡アクティビティに関するその他の前提条件については、「 Analytics にアクセスするためのアクセス許可と前提条件」を参照してください。

重要

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

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

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

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

クラウド (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 場合は、別のフィルターを指定する必要があります。

たとえば、次の組織スコープのクエリでは、an を使用 $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 には、プロジェクト レベルのセキュリティに関連するクエリ構文に関するいくつかの制限があります。

またはallフィルターはany、$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)

次のステップ

集計データのクエリ

関連記事

• クエリのガイドライン