在 Azure DevOps 中为 Analytics 构造 OData 查询

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

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

注意

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

本文介绍如何：

创建 Analytics OData 查询。
查询分析元数据。
查询实体集的分析 OData。
按建议的顺序使用查询选项。
了解服务器端分页。

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

先决条件

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

查询元数据

分析通过将附加到服务根 URL，形成的元数据 URL 处公开$metadata。 Analytics 为 Azure DevOps 项目或整个组织和集合提供服务根。

可以查询元数据以查找以下任何数据元素：

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

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

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata

以下示例查询 fabrikam 组织的元数据。

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

在查询字符串中， analytics.dev.azure.com 是 Analytics 服务根 URL，后跟组织名称、项目名称、OData 版本和 $metadata 指定。

若要查询服务器的元数据，请在 Web 浏览器中输入以下 URL 语法。将<ServerName>、<CollectionName>和<ProjectName>替换为要查询的服务器、集合和项目的名称。若要返回集合的所有元数据，请不要指定项目名称。

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata

以下示例查询服务器 fabrikam-devops 及其 DefaultCollection 的元数据。

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

注意

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

解释元数据响应

分析返回数据模型的 XML 文件。使用浏览器搜索函数查找感兴趣的实体的信息。

提示

根据浏览器，此文件可能不是以人工可读方式格式化的。可以通过 Web 搜索找到免费的联机 XML 格式化程序。

分析元数据定义以下主要架构。

Microsoft.VisualStudio.Services.Analytics.Model 定义实体类型和枚举类型及其成员。
架构 Default 定义实体容器和实体集以及支持的 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>

有关详细信息，请参阅 Analytics OData 元数据。

所有实体类型都具有可用于筛选查询的属性和导航属性。这些属性在每个 Property 下的元数据中列出为 NavigationProperty 或 EntityType。可以使用相关实体来指定更多筛选器，例如迭代路径、区域路径或团队。

以下代码片段显示了实体元数据 WorkItem 的部分视图。属性对应于分析捕获的工作项字段和特定数据，例如 LeadTimeDays 和 CycleTimeDays。导航属性对应于为实体类型捕获的其他实体集和特定分析数据，例如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"/>
...

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

查询实体集

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

使用以下 URL 语法查询特定的 EntitySet，例如 WorkItems，WorkItemSnapshot 或 PipelineRuns。替换 <EntitySet> 为要搜索的实体，并将 <QueryOptions> 替换为中描述的查询选项中的相应选项。

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

以下示例查询Fabrikam Fiber组织中fabrikam项目的工作项计数。

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
   }
 ]
}

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

以下示例查询 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子句。如果未包含$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或$apply子句等效于对实体集中执行select语句，从而返回所有列和所有行。如果有大量记录，查询可能需要几秒钟时间。如果项目超过 10,000 个，则强制执行服务器端分页。

示例：查询特定实体集

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

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

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 并选择返回 ProjectName 属性来获取为服务器和集合定义的项目列表。以下示例显示了在DefaultCollection服务器上的fabrikam查询 URL。

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

使用查询选项

查询选项是查询字符串参数，可帮助控制为资源返回的数据量。按照下表中列出的顺序指定查询选项。

查询选项	Description
`$apply`	将转换应用于查询，例如`filter`、`groupby`、`aggregate`、`compute`或`expandconcat`。有关示例，请参阅使用 Analytics 聚合工作跟踪数据。
`$compute`	在`$select`、`$filter`或`$orderby`表达式中定义计算属性。
`$filter`	筛选返回的资源列表。查询评估查询范围中每个资源指定的`$filter`表达式，仅包括在响应中结果为`true`的项。在响应中省略那些表达式求值为 `false` 或 `null` 的资源，或者因权限限制而无法访问引用属性的资源。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$orderby`	指定要返回记录的序列。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$top`/`$skip`	限制返回的记录数。有关示例，请参阅 Project 和组织范围的查询。
`$select`	指定所需的列。
`$expand`	嵌套其他查询选项。每个 `expandItem` 计算结果相对于包含要展开的导航或流属性的实体。为导航属性名称提供以逗号分隔的查询选项列表（括在括号中）。允许的系统查询选项包括`$filter`、、`$select`、`$orderby$skip`、`$top`、`$count`、 `$search`和 `$expand`。有关示例，请参阅使用 Analytics 查询工作跟踪数据。
`$skiptoken`	跳过指定数量的记录。
`$count` 或 `$count=true`	仅返回记录数。 Enter `$count=true`返回记录计数和查询的数据。有关示例，请参阅使用 Analytics 聚合工作跟踪数据。

提示

避免在单个查询中混合 $apply 和 $filter 子句。若要筛选查询，可以使用 $filter 子句或使用 $apply=filter() 组合条件。这两个选项都起作用，但在单个查询中合并它们可能会导致意外结果。

了解如何进行服务器端分页

当查询结果超过 10,000 条记录时，分析会强制分页。在这种情况下，您可以获得数据的第一页和一个链接以便获取下一页。在拉取数据时，Power BI Desktop 或 Excel 等客户端工具会自动遵循 @odata.nextLink 并加载所有必需的记录。

可以在 JSON 输出的末尾找到 @odata.nextLink 链接。链接类似于原始查询，后接 $skip 或 $skiptoken。例如：

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

后续步骤

使用 OData Analytics 构造基本查询

反馈

此页面是否有帮助？

Last updated on 2025-11-07