リンクされた作業項目のクエリ
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 を $expandParent に置き換えることで、アイテムの先祖を取得できます。
次のクエリは、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"
}
}]
}]
}
次のステップ
関連記事
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示