Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020
针对 Azure DevOps 的 Analytics 运行 Open Data Protocol （OData） 查询时，可以检索有关工作项的信息。 您还可以查询已链接的工作项。 工作项可以通过层级关系链接，例如以父子关系的形式。 工作项也可以以非层次结构方式链接，例如，当工作项相关或重复时。
查询链接的工作项的方式与使用导航属性筛选实体集查询的方式类似。 但链接是实体，因此存在一些额外的复杂性。 可通过两种方法查询链接的工作项：
- 通过使用
Parent或Children导航属性 - 使用
Links导航属性
在本教程中，你将：
- 构造查询以返回分层链接的工作项。
- 构造查询以返回非无层次结构链接的工作项。
注释
Azure DevOps Services 中所有服务的生产中会自动启用并支持 Analytics 服务。 Power BI 集成 和对 Analytics 服务的 OData 源 的访问权限现已普遍可用。 鼓励您使用 Analytics OData 提要并提供反馈。
可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。 有关详细信息，请参阅 OData API 版本控制。
注释
Analytics 服务会在生产环境中为 Azure DevOps Server 2020 及更高版本的所有新项目集合自动安装并支持。 Power BI 集成 和对 Analytics 服务的 OData 源 的访问权限现已普遍可用。 鼓励您使用 Analytics OData 提要并提供反馈。 如果从 Azure DevOps Server 2019 升级，可以在升级期间安装 Analytics 服务。
可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。 有关详细信息，请参阅 OData API 版本控制。
先决条件
| 类别 | 要求 |
|---|---|
| 访问级别 |
-
项目成员。 - 至少 基本 访问权限。 |
| 权限 | 默认情况下，项目成员有权查询 Analytics 和创建视图。 有关服务和功能启用和常规数据跟踪活动的其他先决条件的详细信息，请参阅 访问 Analytics 的权限和先决条件。 |
注释
本文中的示例使用以下格式的 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)
响应列出了有关 ID 为 479 和 480 的特性任务项的信息。 这些功能是 ID 为 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": [
"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 项目和 fabrikam 组织中查询 ID 为 1048 的工作项的父项。
请求
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"
}
}]
}]
}