共用方式為


查詢連結的工作專案

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 導覽屬性可讓您要求這些關聯性。

若要擷取與專案相關聯的連結,您可以使用 $expand Links 導覽屬性。 在此範例中, 會針對與工作專案 363 相關聯的所有連結,擷取 SourceWorkItemIdTargetWorkItemIdLinkTypeName

要求

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

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

您可以在 TargetWorkItemSourceWorkItem 導覽屬性上使用 來包含連結工作專案$expand的詳細數據。 在此範例中,我們會針對每個連結擷取 目標工作專案的 WorkItemIdTitleState

要求

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

下一步