项目范围和组织范围的查询

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

使用适用于 Azure DevOps 的分析，可以构造限定为项目或组织或集合的查询。 可以直接在浏览器中或在 Power BI 中运行这些查询。

项目范围查询有助于回答有关单个项目的问题，而组织和集合范围的查询允许回答跨项目边界的问题。 组织和集合范围内的查询需要更广泛的用户权限或仔细的范围限制，以确保由于缺少权限，查询不会被阻止。

注意

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

先决条件

• 若要查看 Analytics 数据并查询服务，你需要是具有 基本 访问权限或更高访问权限的项目的成员。 默认情况下，向所有项目成员授予查询 Analytics 和定义 Analytics 视图的权限。
• 若要了解有关服务和功能启用以及常规数据跟踪活动的其他先决条件，请参阅 访问 Analytics 的权限和先决条件。

重要

如果你无权访问组织中的所有项目，建议向所有查询应用项目筛选器。 将数据拉取到 Power BI 或 Excel 等客户端工具中时，使用项目路径语法是确保所有数据受给定项目约束的最佳方式。 建议仅在需要报告两个或多个项目时，才使用组织范围的或集合范围的查询。

项目范围的查询

通过将 OData URL 输入到受支持的 Web 浏览器中来构造查询。

项目级 OData 查询的基本 URL 如以下语法所示。

云 （Azure DevOps Services）

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

在提供的示例中，请替换为{OrganizationName}{ProjectName}要查询的组织名称和项目的名称。

本地 （Azure DevOps Server）

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

在提供的示例中，进行以下替换：

• analytics.dev.azure.com 与 {ServerName}:{Port}/tfs/
• {CollectionName} 具有项目集合名称（默认值为 DefaultCollection）
• {ProjectName} 包含要查询的项目的名称。

注意

本文中提供的其余示例基于 Azure DevOps Services URL。 需要在 Azure DevOps Server URL 中替换这些示例。

返回工作项计数

例如，以下项目范围的查询返回特定项目的工作项计数。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

例如，Fabrikam Fiber 项目的查询返回 7126 个工作项的计数。 计数中不包括已删除的工作项。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

返回项目区域路径

同样，以下查询字符串将返回特定项目的区域：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

它等效于组织范围的查询的以下筛选器：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

例如，Fabrikam Fiber 项目的查询返回为区域路径定义的所有属性，因为查询中未 $select 应用任何运算符。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

以下示例显示了为单个区域路径返回的数据。

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

使用 $expand 选项

将项目范围的查询与选项结合使用 $expand 时，无需提供其他筛选器。

例如，以下项目范围的筛选器：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

自动筛选以强制实施安全性：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

组织范围的查询

组织级别查询的基本 URL 如下所示：

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

将组织范围的查询与选项 $expand 一起使用时，必须提供另一个筛选器。

例如，以下组织范围的查询，该查询使用检索 $expand 所有工作项的子项。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

它需要另一个筛选器来验证子级是否仅限于指定的项目：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

返回所有工作项的父项

以下查询使用选项 $expand 检索所有工作项的父项。

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

它需要另一个筛选器来验证父级是否仅限于指定的项目：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

如果没有其他筛选器，则如果任何工作项的父项引用您没有读取访问权限的项目中的工作项，则请求将失败。

项目级安全限制

分析对与项目级别安全性相关的查询语法还有一些限制。

any或all筛选器应用于基本实体的 $expand。 对于基于项目的筛选器，在使用以下项时 $expand，我们显式忽略筛选器：

例如，以下查询：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

解释为：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

如果无权访问所有项目，将失败。

若要解决此问题，需要在以下项中添加额外的表达式 $filter：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

$level仅当有权访问集合中的所有项目或使用项目范围的查询时，才支持使用：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

分析不支持使用 $it 子句的项目的任何跨级别引用。 例如，以下查询引用根工作项的 ProjectName 别名 $it ，该别名不受支持：

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

下一步

查询聚合数据

相关文章

• 查询指南