教學指南：查詢已連結的工作項目

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

當您針對 Azure DevOps 的分析執行開放式數據通訊協定（OData）查詢時，您可以擷取工作專案的相關信息。您也可以查詢連結的工作專案。工作專案可以階層式連結，例如在父系或子系關係中。工作專案也可以以非階層方式連結，例如當工作專案相關或重複時。

查詢連結工作專案的方式類似於您使用導覽屬性來篩選實體集查詢的方式。但鏈接是實體，因此會有一些額外的複雜度。有兩種方式可以查詢連結的工作專案：

使用 Parent 或 Children 導覽屬性
使用 Links 導覽屬性

在本教學課程中，您會：

建構查詢以傳回階層式連結的工作專案。
建構查詢以傳回非階層式連結的工作專案。

備註

Azure DevOps Services 內所有服務的生產環境中會自動啟用及支援 Analytics 服務。 Power BI 整合及存取 Analytics 服務的 OData 摘要已正式推出。建議您使用 Analytics OData 摘要並提供意見反應。

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

備註

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

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

先決條件

類別	需求
存取層級	- 專案成員。 - 至少擁有基本存取權限。
許可	根據預設，項目成員具有查詢分析及建立檢視的許可權。如需有關服務與功能啟用和一般數據追蹤活動之其他必要條件的詳細資訊，請參閱存取分析的許可權和必要條件。

備註

本文中的範例會使用下列格式的 Azure DevOps Services URL：

https://analytics.dev.azure.com/{organization-name}/{project-name}/_odata/{version}

針對 Azure DevOps Server，請改用下列格式，其中包含內部部署伺服器：

https://{server-name}:{port}/tfs/{organization-name}/{project-name}/_odata/{version}

查詢父工作專案或子工作專案

您可以使用$expand選項，透過Parent和Children導覽屬性上的父子連結來查詢相關專案。

範例：要求專案的子系

若要傳回項目子系的相關信息，請在 $expand 導覽屬性上使用 Children 。下列 OData 程式代碼會查詢 fabrikam 組織中的 Fabrikam Fiber 專案。它傳回 ID 359 的工作項目之子項。

要求

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

回應會列出標識碼為 479 和 480 的功能工作專案相關信息。這些功能是標識碼為 359 的 Epic 工作項目的子系。

備註

大部分的 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": [
        "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": [{
        "WorkItemId": 359,
        "Title": "Phase 1 - Customer access and engagement 5",
        "WorkItemType": "Epic",
        "State": "In Progress",
        "Children": [{
            "WorkItemId": 480,
            "Title": "Customer Phone - Phase 1",
            "WorkItemType": "Feature",
            "State": "In Progress"
        },
        {
            "WorkItemId": 479,
            "Title": "Customer Web - Phase 1",
            "WorkItemType": "Feature",
            "State": "In Progress"
        }]
    }]
}

範例：請求項目的父項

藉由在 Children 選項中將 Parent 替換為 $expand，您可以擷取項目的祖系。

下列程式代碼會查詢 Fabrikam Fiber 專案中，標識碼為 1048 的工作專案的父項，以及 Fabrikam 組織。

要求

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

回應會列出 ID 為 480 的功能相關信息，這是 ID 為 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": [
        "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": [{
        "WorkItemId": 1048,
        "Title": "Support reset",
        "WorkItemType": "Product Backlog Item",
        "State": "New",
        "Parent": {
                "WorkItemId": 480,
                "Title": "Customer Phone - Phase 1",
                "WorkItemType": "Feature",
                "State": "In Progress"
        }
    }]
}

查詢非階層連結

除了父子連結之外，其他類型，例如 Related 或 Duplicate 也可以連結工作專案。您可以使用 Links 導覽屬性來要求透過非階層關聯性連結之工作專案的相關信息。

範例：要求項目的連結

若要擷取與專案相關聯的連結，您可以使用 $expand 導覽屬性上的 Links 選項。下列查詢會擷取與工作專案 363 相關聯之所有連結的 SourceWorkItemId、 TargetWorkItemId和 LinkTypeName 值。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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"
        }]
    }]
}

範例：要求鏈接專案的詳細資訊

您可以使用或 $expand 導覽屬性上的 TargetWorkItem 選項來查詢連結工作項目SourceWorkItem的詳細資訊。

如同上一個查詢，下列查詢會擷取與工作專案相關聯之所有連結的 SourceWorkItemId、 TargetWorkItemId和 LinkTypeName 值。但此查詢也會擷取每個鏈接目標工作專案的 WorkItemId、Title 和 State 值。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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": "Issue 10",
                "State": "Active"
            }
        }]
    }]
}

範例：要求特定類型的連結

如果您對專案之間的特定連結類型感興趣，您可以在子句中使用 LinkTypeName$filter 屬性。下列查詢會展開所有 Related 連結，並篩選出工作專案 103 的所有其他連結類型。

要求

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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": "Issue 10",
                "State": "Active"
            }
        }]
    }]
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17