使用 OData Analytics 定义基本查询

项目
01/10/2024

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

使用 Azure DevOps 分析，可以构造基本查询和筛选查询，以返回感兴趣的数据。可以直接在浏览器中或在 Power BI 中运行这些查询。

本文基于 Azure Boards Analytics 的构造 OData 查询和元数据参考中提供的信息。此外，本文中的查询侧重于检索工作跟踪实体集，但是，这些原则适用于查询其他实体集。

本文介绍如何定义返回以下数据的查询：

项目计数（无其他数据）
项和数据计数
为区域或迭代路径定义的属性
所选列或字段
筛选的数据
返回标识、区域路径和迭代路径字段的数据
按导航属性进行筛选
查询日期范围
嵌套 expand 语句
对结果进行排序，orderby 选项

注意

分析服务在所有 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 版本控制。

先决条件

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

注意

在本文中，为 Azure DevOps Services 定义了 OData 查询 URL。若要为本地服务器构造类似的查询，请参阅 Analytics 构造 OData 查询中提供的指南。我们鼓励你调整为组织和项目提供的查询，以便熟悉使用浏览器查询 OData。

返回项计数（无其他数据）

若要了解组织或项目中定义的项数或实体数，请指定 $apply=aggregate($count as Count) 查询选项。例如，以下查询返回为组织定义的项目、工作项、区域路径和用户数。

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

提示

当运行查询的用户无法访问所有项目时，跨项目查询将失败。详细了解 Project 和组织范围内的查询中的要求。

项目计数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

工作项计数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

区域计数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

用户计数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

返回项和数据计数

若要返回项的计数以及项目的选择数据，请 $count=true 指定查询选项。例如，以下查询返回为项目定义的工作项、区域路径和用户以及指定属性的计数。有关有效属性，请参阅 Azure Boards Analytics 的元数据参考和日历日期、项目和 Azure DevOps Analytics 的用户元数据参考。

提示

如果未指定要返回的属性，Analytics 将返回为指定实体类型定义的所有属性。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

区域或迭代属性

若要查找AreaSKIterationSK区域路径或迭代路径的其他属性，请使用以下查询。

返回特定区域路径的 AreaSK

以下查询指定返回 AreaSK 为 Fabrikam Fiber\Service Delivery\InternetArea Path 定义的属性。若要指定为 Areas 实体集定义的其他属性，请参阅 Azure Boards Analytics、Areas 的元数据参考。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK

查询返回以下数据。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

返回特定迭代路径的 IterationSK

以下查询指定返回 IterationSK 为 Fabrikam Fiber\Release 1\Sprint 3迭代路径定义的属性。若要指定为 Iterations 实体集定义的其他属性，请参阅 Azure Boards Analytics 的元数据参考，迭代。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

查询返回以下数据。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

返回特定属性或字段

若要返回特定属性或工作项字段，请添加一个 $select 指定属性名称的子句。

例如，若要返回 工作项 ID、 工作项类型、标题和 工作项状态 ，请将以下子句添加到查询中。此子句指定与命名字段对应的属性。

注意

属性名称不包含任何空格。如果添加空格，查询将失败。 OData 查询需要注意间距和大小写。若要了解如何标记自定义字段属性，请参阅 Azure Boards 的元数据参考、自定义属性。

在这里，我们指定返回前三个工作项。

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

Analytics 返回以下数据。

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

。

筛选数据

若要筛选实体集以返回选择项，请指定指定 $filter 项必须满足的条件的子句。在最后一个查询的基础上，我们在此处添加一个筛选器子句，以仅返回处于“正在进行”状态的功能工作项类型。

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State

Analytics 返回以下数据。

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

指定多个筛选器子句

可以使用 AND 和 OR 指定多个筛选器子句。

例如，以下查询指定返回处于“新建”、“已提交”或“活动”状态的“用户情景”、“Bug”和“积压工作”类型（自定义工作项类型）的工作项。使用括号根据需要对筛选器子句进行分组。

此外，还可以应用各种函数，例如containsstartswith，endswith等等。请参阅支持的 OData 功能和子句、支持的函数。

返回标识、区域路径和迭代路径字段的数据

Select 属性与导航属性相关联，无法使用语句直接访问 $select 。必须使用 $expand 语句返回感兴趣的数据。这些属性通常与其自身的多个属性相关联。例如，使用“标识”字段，可以指定以返回用户名或用户电子邮件。

下表提供了有关如何扩展其中几个属性的示例。

类型字段	引用的属性	要包含的示例子句
DateTime	`DateSK`	`$expand=CreatedDate($select=Date)` 或 `$expand=CreatedDate($select=WeekStartingDate)`
标识	`UserSK`	`$expand=AssignedTo($select=UserName)` 或 `$expand=AssignedTo($select=UserEmail)`
区域	`AreaSK`	`$expand=Area($select=AreaName)` 或 `$expand=Area($select=AreaPath)`
迭代	`IterationSK`	`$expand=Iteration($select=IterationName)` 或 `$expand=Iteration($select=IterationPath)` 或 `$expand=Iteration($select=StartDate)`
集成	`ProjectSK`	`$expand=Project($select=ProjectName)`
组	`TeamSK`	`$expand=Teams($select=TeamName)`

若要指定需要展开的多个属性，请在以 comman 分隔的列表内的单个 expand 子句中指定它们。

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

将导航属性指定为筛选条件的一部分时，必须以所需格式指定它。

例如，以下子句指定根据为 项目定义的迭代 1 筛选工作项。

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

在此示例中， Iteration 是导航属性名称，对应于 IterationPath 迭代的完整路径。若要使用另一个实体作为筛选器，请将导航属性后跟斜杠，后跟要筛选的字段的名称。

下面是完整的 OData 查询：

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

下面是另一个请求 Fabrikam Fiber\Service Delivery\Voice Area Path 下前五个工作项的示例。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

提示

不能直接在语句中使用 $select 导航属性。相反，需要使用 $expand。

上一个迭代路径筛选示例不返回迭代路径，因为它包含在相关实体中。若要返回相关实体中的数据，请添加语句 $expand ：

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

以下示例返回分配给工作项 ID 480 的信息。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

可以看到，迭代路径在结果中展开，并返回所有迭代数据。数据可能比所需数据多。

若要返回较少的数据，请针对迭代添加 $select 语句：

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

然后返回以下数据。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

查询日期范围

以下示例返回其更改日期大于 2021 年 1 月 1 日的工作项。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

以下示例返回在 2021 年 4 月 26 日至 4 月 30 日这一周发生的更改日期的工作项。

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

嵌套 expand 语句

在 OData 中，可以嵌套 $expand 语句。例如，可以编写上一个查询语句来显示迭代所属的项目：

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

它返回以下 JSON：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

还可以合并 $expand 和 $select 语句。例如，可以将上一个查询更改为仅返回迭代名称和迭代路径：

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

它返回以下 JSON：

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

请注意，此处的结果仅显示 IterationId 和 IterationPath，并且 Project 是 JSON 结果中的嵌套对象。要注意的另一个关键项是 URL 本身。使用 $select 语句和 $expand 子句时，必须使用分号（;)之前 $expand）。任何其他操作都会导致错误。

对结果进行排序， `orderby` 选项

指定用于 $orderby 对结果进行排序的选项，或指定返回结果的顺序。可以使用关键字 (keyword)ascdesc或分别按升序或降序排序。显示一些示例

排序依据	要包含的子句
工作项 ID	`/WorkItems?$orderby=WorkItemId`
工作项 ID 降序	`/WorkItems?$orderby=WorkItemId desc`
工作项类型和状态	`/WorkItems?$orderby=WorkItemType,State`

后续步骤

Project 和 organization-scoped 查询