查詢連結的工作專案

文章
01/13/2024

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

跨鏈接查詢工作專案非常類似使用一般導覽屬性。不過，連結本身是實體，因此會有一些額外的複雜度。

有兩種方式可以查詢連結的工作專案。第一個是 Parent/Child 階層，第二個是 Links 導覽屬性。

在本文中，您將瞭解：

如何建構查詢以階層方式傳回（父子式）連結的工作專案
如何建構查詢以非階層方式傳回非階層式（相關、直接）連結的工作專案

注意

所有 Azure DevOps Services 的生產環境中都會自動啟用及支援 Analytics 服務。 Power BI 整合及存取 Analytics Service 的 OData 摘要已正式推出。我們鼓勵您使用它，並提供意見反應給我們。可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

注意

Azure DevOps Server 2020 和更新版本的所有新專案集合都會在生產環境中自動安裝並支援 Analytics 服務。 Power BI 整合及存取 Analytics Service 的 OData 摘要已正式推出。我們鼓勵您使用它，並提供意見反應給我們。如果您從 Azure DevOps Server 2019 升級，則可以在升級期間安裝 Analytics 服務。

可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

注意

Azure DevOps Server 2019 的 Analytics 服務處於預覽狀態。您可以啟用或安裝專案集合。 Power BI 整合和分析服務的 OData 摘要存取處於預覽狀態。我們鼓勵您使用它，並提供意見反應給我們。

可用的數據與版本相關。最新支援的版本是 v2.0，而最新的預覽版本是 v4.0-preview。如需詳細資訊，請參閱 OData API 版本控制。

注意

本文所示的範例是以 Azure DevOps Services URL 為基礎。針對 Azure DevOps Server，您必須將 URL 取代為內部部署伺服器。

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

父子式階層

您可以在 Parent 和 Children 屬性上使用來包含透過 Parent/Child 連結 $expand 相關的專案。

範例：父子查詢

若要傳回項目子系的相關信息，請在 $expand Children 導覽屬性上使用。下列代碼段要求從 Fabrikam Fiber 專案傳回工作專案標識碼 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)

回應會傳回特徵 479 和 480，這是史詩 359 的子系。

注意

大部分要求工作專案連結資訊的 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將 Children 取代為 Parent，您可以擷取專案的祖系。

下列查詢要求從 Fabrikam Fiber 專案傳回工作專案標識碼 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

回應會傳回功能 480，這是產品待辦專案 1048 的父代。

回應

@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"

查詢非階層式連結

除了 Parent/Child 階層之外，專案也可以直接與具有相關或重複等連結類型的其他項目相關。 Links 導覽屬性可讓您要求這些關聯性。

範例：要求項目的連結

若要擷取與專案相關聯的連結，您可以使用 $expandLinks 導覽屬性。在此範例中， 會針對與工作專案 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 或 SourceWorkItem 導覽屬性上使用來包含連結工作專案$expand的詳細數據。在此範例中，我們會針對每個連結擷取 目標工作專案的 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"
            }
        }]
    }]
}

下一步

探索分析元數據

分享方式：

查詢連結的工作專案

父子式階層

範例：父子查詢

範例：子系對父查詢

查詢非階層式連結

範例：要求項目的連結

範例：要求鏈接專案的詳細數據

範例：特定類型的連結

下一步

意見反映

意見反映

更多資源

分享方式：

查詢連結的工作專案

父子式階層

範例：父子查詢

範例：子系對父查詢

查詢非階層式連結

範例：要求項目的連結

範例：要求鏈接專案的詳細數據

範例：特定類型的連結

下一步

相關文章

意見反映

意見反映

更多資源