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

  • [アーティクル]

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

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

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

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

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

Note

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

Note

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

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

Note

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

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

Note

この記事に示す例は、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 の子を返すように要求します。

Request

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 を返します。

Note

作業項目のリンク情報を要求するほとんどの 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"

例: 子から親へのクエリ

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

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

Request

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 ナビゲーション プロパティを使用すると、これらのリレーションシップを要求できます。

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

Request

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 ナビゲーション プロパティまたは SourceWorkItem ナビゲーション プロパティを使用$expandして、リンクされた作業項目の詳細を含めることができます。 この例では、各リンクのターゲット作業項目の WorkItemId、Title、State を取得します。

Request

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"
            }
        }]
    }]
}

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

Request

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))

Response

{
    "@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 メタデータを探索する