リンクされた作業項目のクエリ

[アーティクル]
02/22/2025

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

リンク間での作業項目のクエリは、一般的なナビゲーションプロパティの使用とよく似ています。ただし、リンク自体はエンティティであるため、複雑さが増します。

リンクされた作業項目を照会するには、2 つの方法があります。 1 つ目は親/子階層で、2 つ目は Links ナビゲーションプロパティです。

この記事では、次の内容について説明します。

階層的 (親子) のリンクされた作業項目を返すクエリを作成する方法
非階層 (関連、直接) のリンクされた作業項目を返すクエリを作成する方法

手記

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

手記

Analytics サービスは、Azure DevOps Server 2020 以降のすべての新しいプロジェクトコレクションに対して、運用環境で自動的にインストールされ、サポートされます。 Power BI 統合と、Analytics サービスの OData フィードへのアクセスが一般公開されています。お使いいただき、フィードバックをお寄せください。 Azure DevOps Server 2019 からアップグレードした場合は、アップグレード中に Analytics サービスをインストールできます。

使用可能なデータはバージョンによって異なります。サポートされている最新バージョンが v2.0され、最新のプレビューバージョンが v4.0-preview。詳細については、OData API のバージョン管理を参照してください。

手記

Analytics サービスは、Azure DevOps Server 2019 のプレビュー段階です。プロジェクトコレクションのを有効またはインストール。 Power BI 統合、Analytics Service の OData フィードへのアクセスはプレビュー段階です。お使いいただき、フィードバックをお寄せください。

前提条件

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

手記

この記事に示す例は、Azure DevOps Services URL に基づいています。 Azure DevOps Server の場合は、オンプレミスサーバーの URL に置き換える必要があります。

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

親子階層

Parent プロパティと Children プロパティの $expand を使用して、親/子リンクを介して関連する項目を含めることができます。

例: 親から子へのクエリ

アイテムの子に関する情報を取得するには、Children ナビゲーションプロパティで $expand を使用します。次のコードスニペットは、Fabrikam Fiber プロジェクトから作業項目 ID 359 の子要素を返すようにリクエストします。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 359&$select=WorkItemId, Title, WorkItemType, State&$expand=Children($select=WorkItemId,Title, WorkItemType, State)

応答は、エピック 359 の子である機能 479 と 480 を返します。

手記

作業項目のリンク情報を要求するほとんどの OData クエリでは、結果が返されますが、警告も返されます。この警告は、OData Analytics クエリガイドラインで説明されている推奨されるクエリガイドラインに従うことをお勧めします。ただし、提供されているクエリの例は有効です。

応答

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Children(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
 0	
   WorkItemId	359
   Title	"Phase 1 - Customer access and engagement 5"
   WorkItemType	"Epic"
   State	"In Progress"
   Children	
      0	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"
      1	
        WorkItemId	479
        Title	"Customer Web - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

例: 子から親へのクエリ

$expand オプション子親に置き換えることで、アイテムの先祖を取得できます。

次のクエリは、Fabrikam Fiber プロジェクトから作業項目 ID 1048 の親を返すように要求します。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,State&$expand=Parent($select=WorkItemId,Title,WorkItemType, State)&$filter=WorkItemId eq 1048

応答は、製品バックログ項目 1048 の親である機能 480 を返します。

応答

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Parent(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
  0	
     WorkItemId	1048
     Title	"Support reset"
     WorkItemType	"Product Backlog Item"
     State	"New"
     Parent	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

非階層リンクのクエリ

親/子階層に加えて、アイテムは、関連や重複などのリンクの種類を持つ他のアイテムに直接関連付けることができます。 リンク ナビゲーションプロパティを使用すると、これらのリレーションシップを要求できます。

例: アイテムのリンクを要求する

アイテムに関連付けられているリンクを取得するには、Links ナビゲーションプロパティを $expand できます。この例では、作業項目 363 に関連付けられているすべてのリンクについて、SourceWorkItemId、TargetWorkItemId、および LinkTypeName が取得されます。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20363&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName)

応答

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName))",
    "value": [{
        "WorkItemId": 363,
        "Title": "Welcome back page",
        "WorkItemType": "Product Backlog Item",
        "State": "Done",
        "Links": [{
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 400,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 470,
            "LinkTypeName": "Tested By"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 501,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 1079,
            "LinkTypeName": "Tested By"
        }
    }]
}

例: リンクされたアイテムの詳細を要求する

リンクされた作業アイテムの詳細を含めるには、TargetWorkItem のナビゲーションプロパティとして $expand を使用するか、SourceWorkItem のナビゲーションプロパティを使用します。この例では、リンクごとに対象の作業項目の WorkItemId、Title、および State を取得します。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$expand=TargetWorkItem($select=WorkItemId,Title,State))

応答

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 48,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 48,
                "Title": "Story 15",
                "State": "Resolved"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 50,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 50,
                "Title": "Story 17",
                "State": "Active"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 55,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 55,
                "Title": "Story 22",
                "State": "New"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

例: 特定の種類のリンク

アイテム間の特定の種類のリンクにも関心がある場合があります。 $filter 句で LinkTypeName プロパティを指定します。次のクエリ例では、すべての関連リンクを展開し、作業項目 103 の他のすべてのリンクの種類を除外します。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId eq 103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$filter=LinkTypeName eq 'Related';$expand=TargetWorkItem($select=WorkItemId,Title,State))

応答

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

次の手順

Analytics メタデータを探索する

Analytics の OData クエリを構築する
OData Analytics を使用して基本的なクエリを作成する
直接リンクを含む作業項目のサンプルレポート
要件追跡サンプル報告書

次の方法で共有

リンクされた作業項目のクエリ

前提条件

親子階層

例: 親から子へのクエリ

例: 子から親へのクエリ

非階層リンクのクエリ

例: アイテムのリンクを要求する

例: リンクされたアイテムの詳細を要求する

例: 特定の種類のリンク

次の手順

フィードバック

その他のリソース

次の方法で共有

リンクされた作業項目のクエリ

前提 条件

親子階層

例: 親から子へのクエリ

例: 子から親へのクエリ

非階層リンクのクエリ

例: アイテムのリンクを要求する

例: リンクされたアイテムの詳細を要求する

例: 特定の種類のリンク

次の手順

関連記事

フィードバック

その他のリソース

前提条件