查询链接的工作项

项目
01/13/2024

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

跨链接查询工作项非常类似于使用典型的导航属性。不过，链接本身是实体，因此存在一些额外的复杂性。

可通过两种方式查询链接的工作项。第一个是父级/子层次结构，第二个是 Links 导航属性。

在本文中，你将了解：

如何构造查询以分层方式返回链接的工作项
如何构造查询以返回非分层（相关、直接）链接的工作项

注意

分析服务在所有 Azure DevOps Services 的生产中自动启用和支持。对 Analytics Service 的 OData 源的 Power BI 集成和访问已正式发布。我们鼓励你使用它并提供反馈。可用数据依赖于版本。支持的最新版本是 v2.0，最新的预览版本是 v4.0-preview。有关详细信息，请参阅 OData API 版本控制。

注意

Azure DevOps Server 2020 及更高版本的所有新项目集合都会自动安装并支持 Analytics 服务。对 Analytics Service 的 OData 源的 Power BI 集成和访问已正式发布。我们鼓励你使用它并提供反馈。如果从 Azure DevOps Server 2019 升级，则可以在升级期间安装 Analytics 服务。

可用数据依赖于版本。支持的最新版本是 v2.0，最新的预览版本是 v4.0-preview。有关详细信息，请参阅 OData API 版本控制。

注意

Analytics 服务为 Azure DevOps Server 2019 提供预览版。可以为项目集合启用或安装它。 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 属性包含 $expand 通过父/子链接相关的项。

示例：父查询到子查询

若要返回有关项的子项的信息，请使用 $expand Children 导航属性。以下代码片段请求从 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)

响应返回的功能为 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 项目返回工作项 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

响应返回功能 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"

查询非分层链接

除了父级/子层次结构之外，项目还可以与链接类型（如 Related 或 Duplicate）的其他项直接相关。 使用 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"
            }
        }]
    }]
}

示例：特定类型的链接

你可能还对项目之间的特定链接类型感兴趣。在子句中$filter指定 LinkTypeName 属性。以下查询示例扩展了所有相关链接，并筛选出工作项 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))

响应

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

后续步骤

浏览分析元数据

通过

查询链接的工作项

父子层次结构

示例：父查询到子查询

示例：子查询到父查询

查询非分层链接

示例：请求项的链接

示例：请求链接项的详细信息

示例：特定类型的链接

后续步骤

相关文章

反馈

其他资源