在 Azure DevOps 中为 Analytics 构造 OData 查询

项目
07/17/2024

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

Azure DevOps 的报告平台分析可以回答有关项目过去或当前状态的定量问题。 Analytics 支持对其元数据和实体集数据的 OData 查询。通过从 Web 浏览器执行简单的查询，可以熟悉数据模型和查询过程。

在本文中，你将了解以下内容：

如何为云或本地构建 Analytics OData 查询
如何查询分析元数据
如何查询实体集的分析 OData
支持哪些查询选项和建议的序列
强制执行服务器端分页时

可以从任何受支持的 Web 浏览器查询 Analytics。有关可用于查询分析的其他工具，请参阅 Analytics 查询工具。

注意

OData 是一种应用程序级协议，用于通过 RESTful（其中 REST=表示性状态传输）接口与数据交互），支持数据模型的说明以及根据这些模型编辑和查询数据。实体数据模型（EDM）或元数据描述分析中可用的信息，包括用于查询数据以生成报表的实体、实体类型、属性、关系和枚举。有关 OData 的概述，请参阅欢迎使用 OData。

先决条件

Access：至少是具有基本访问权限的项目的成员。
权限： 默认情况下，项目成员有权查询 Analytics 和创建视图。
有关服务和功能启用和常规数据跟踪活动的其他先决条件的详细信息，请参阅访问 Analytics 的权限和先决条件。

用于查询元数据的 URL 组件

分析在元数据 URL 上公开实体模型，该模型通过追加 $metadata 到服务根 URL 形成。 Analytics 为 Azure DevOps 中的项目或整个组织提供服务根。

可以通过查询元数据来查找以下任何数据元素。

实体类型和实体集
属性和导航属性
代理键
枚举列表
EntitySet
容器
筛选器函数（Org.OData.Capabilities.V1.FilterFunctions）
支持的聚合（Org.OData.Aggregation.V1.ApplySupported）
批处理支持（Org.OData.Capabilities.V1.BatchSupportType）

使用的 URL 取决于是查询 Azure DevOps Services（云）的数据还是本地 Azure DevOps Server。

云（Azure DevOps Services）
本地（Azure DevOps Server）

若要查询云中托管的组织或项目的元数据，请输入 URL 语法，如 Web 浏览器中所示。 {ProjectName}替换为{OrganizationName}要查询的组织名称和项目的名称。若要返回组织的所有元数据，请不要指定项目名称。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

注意

最新的 Analytics OData 版本为 v4.0-preview。可以将此版本用于针对托管服务的所有查询。有关 Analytics 版本和可用数据的详细信息，请参阅 Analytics 的数据模型。

下面是托管在 Azure DevOps Services 上的 fabrikam 组织的示例。

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

若要查询本地服务器的元数据，请在 Web 浏览器中输入 URL 语法，如下所示。 {CollectionName} {ProjectName}替换为{ServerName}本地名称。若要返回集合的所有元数据，请不要指定项目名称。

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

注意

下面是 Azure DevOps Server 2022 上命名 fabrikam-devops 和 DefaultCollection 托管的服务器的示例：

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

解释元数据响应

分析返回数据模型的 XML 文件。使用浏览器搜索函数查找特定于相关实体的信息。

提示

根据所使用的浏览器，此文件可能采用可读方式或可能未格式化。如果未设置格式，可以通过 Web 浏览器搜索找到免费的联机 XML 格式化程序。

分析元数据中定义的两个主要架构是 Microsoft.VisualStudio.Services.Analytics.Model：定义实体类型和枚举类型及其成员，以及 Default 定义实体容器和实体集以及支持的 OData 筛选器、转换和自定义聚合函数的架构。有关详细信息，请参阅 Analytics OData 元数据。

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

所有实体类型都与属性和导航属性相关联。可以使用这两种类型的属性筛选实体集的查询。这些列在元数据中 EntityType 作为或 Property NavigationalProperty。使用相关实体来指定其他筛选器，例如迭代路径、区域路径或 Teams。

以下代码片段提供实体元数据 WorkItem 的部分视图。属性对应于工作项字段以及 Analytics 捕获的特定数据，例如 LeadTimeDays 和 CycleTimeDays。导航属性对应于为实体类型捕获的其他实体集，或为实体类型捕获的特定 Analytics 数据，例如Revisions，Links和ChildrenParent。

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

用于查询实体的 URL 组件

若要查询分析数据和生成报表，通常查询实体集。有关支持的实体的概述，请参阅 Analytics OData 元数据。

以下 URL 用于查询特定 EntitySetURL，例如 WorkItems， WorkItemSnapshot和 PipelineRuns。

云（Azure DevOps Services）
本地（Azure DevOps Server）

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

下面是 fabrikam 组织的示例 ，它返回为 Fabrikam Fiber 项目定义的工作项计数。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

该示例返回 1399 个工作项。

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

下面是 fabrikam 服务器 DefaultCollection 的示例，该服务器返回为 Fabrikam 项目定义的工作项计数。

https://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

该示例返回 1399 个工作项。

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

注意

如果未包含或$select$apply子句，将收到警告，例如"VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."，它等效于对实体集执行 select 语句并返回所有列和所有行。如果有大量记录，可能需要几秒钟时间。如果工作项超过 10,000 个，则会强制实施服务器驱动的分页。

为了避免遇到使用限制，请始终包含或$select$apply子句。

有关实体元数据属性和关系信息，请参阅以下文章：

示例：查询特定实体集

若要查询特定实体集，例如 WorkItems， Areas或 Projects添加实体集的名称： /WorkItems、 /Areas或 /Projects。有关实体集的完整列表，请参阅 Analytics 的数据模型。

云（Azure DevOps Services）
本地（Azure DevOps Server）

例如，可以通过查询 /Projects 并选择返回 ProjectName 属性来获取为组织定义的项目列表。对于 fabrikam 组织，URL 如下所示。

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics 返回为 fabrikam 组织定义的这些项目的项目名称。

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

以下示例查询Projects实体集以返回 fabrikam 服务器上 DefaultCollection 上定义的所有项目的名称，

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

该示例返回三个项目名称。

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

查询选项

查询选项是一组应用于资源的查询字符串参数，可帮助控制在 URL 中为资源返回的数据量。

应按照下表中列出的顺序指定查询选项。

查询选项	备注
`$apply`	可以应用于查询的转换集，例如：`filter`、、`groupbyaggregate`、、 `expand,` `compute` `concat` 有关示例，请参阅使用 Analytics 聚合工作跟踪数据。
`$compute`	支持的 OData 函数，可以指定用于定义可在、`$filter`或`$orderby`表达式中使用的`$select`计算属性。
`$filter`	用于筛选返回的资源列表。为集合中的每个资源计算指定的 `$filter` 表达式，并且只有表达式计算结果为 true 的项才会包含在响应中。表达式的计算结果为 false 或为 null 的资源，或因权限而不可用的引用属性，将从响应中省略。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$orderby`	用于指定应返回记录的顺序。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$top`/`$skip`	用于限制返回的记录数。有关示例，请参阅 Project 和组织范围的查询。
`$select`/`$expand`	用于 `$select` 指定生成报表所需的列。用于 `$expand` 嵌套其他查询选项。每个 `expandItem` 计算结果相对于包含要展开的导航或流属性的实体。以分号分隔的查询选项列表（括在括号中）到导航属性名称。允许的系统查询选项包括`$filter`、、`$select`、`$orderby$skip`、`$top`、`$count`、 `$search`和 `$expand`。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$skiptoken`	用于跳过指定数量的记录。
`$count` 或 `$count=true`	输入 `$count` 以仅返回记录数。 Enter `$count=true`返回记录计数和查询的数据。有关示例，请参阅使用 Analytics 聚合工作跟踪数据。

提示

避免在单个查询中混合 $apply 和 $filter 子句。若要筛选查询，有两个选项：（1）使用 $filter 子句或（2）使用 $apply=filter() 组合子句。这些选项中的每一个都可以自行工作，但将它们组合在一起可能会导致一些意外的结果。

强制实施服务器端分页

当查询结果超过 10000 条记录时，分析会强制分页。在这种情况下，你将获得第一页的数据和链接，以获取下一页。可以在 JSON 输出末尾找到链接（@odata.nextLink）。它类似于原始查询后 $skip 跟或 $skiptoken。例如：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

注意

将数据拉取到 Power BI Desktop 或 Excel 等客户端工具中时，工具将自动跟踪下一个链接并加载所有必需的记录。

后续步骤

使用 OData Analytics 构造基本查询

通过

在 Azure DevOps 中为 Analytics 构造 OData 查询

先决条件

用于查询元数据的 URL 组件

解释元数据响应

用于查询实体的 URL 组件

示例：查询特定实体集

查询选项

强制实施服务器端分页

后续步骤

反馈

其他资源

通过

在 Azure DevOps 中为 Analytics 构造 OData 查询

先决条件

用于查询元数据的 URL 组件

解释元数据响应

相关实体和导航属性

用于查询实体的 URL 组件

示例：查询特定实体集

查询选项

强制实施服务器端分页

后续步骤

相关文章

反馈

其他资源