Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020
Azure DevOps 的分析数据模型由实体集组成，其成员（实体）包含可以筛选、聚合和汇总的属性。 此外，它们还包含 将实体与其他实体相关的导航属性 ，从而提供对其他属性的访问权限，以便进行选择、筛选和分组。
注意
Azure DevOps Services 中所有服务的生产中会自动启用并支持 Analytics 服务。 Power BI 集成 和对 Analytics 服务的 OData 源 的访问权限现已普遍可用。 鼓励您使用 Analytics OData 提要并提供反馈。
可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。 有关详细信息，请参阅 OData API 版本控制。
注意
Azure DevOps Server 2020 及更高版本的所有新项目集合都会自动安装并支持 Analytics 服务。 Power BI 集成 和对 Analytics 服务的 OData 源 的访问权限现已普遍可用。 鼓励您使用 Analytics OData 提要并提供反馈。 如果从 Azure DevOps Server 2019 升级，可以在升级期间安装 Analytics 服务。
可用数据依赖于版本。 OData API 的最新支持版本是 v2.0，最新的预览版本是 v4.0-preview。 有关详细信息，请参阅 OData API 版本控制。
了解分析数据模型
Analytics 服务提供通过 OData 终结点访问 Azure DevOps 数据的结构化方法。 使用此数据模型，可以：
- 查询工作跟踪数据：访问工作项、区域、迭代和相关元数据
- 分析管道信息：查询生成和发布管道数据
- 报告测试结果：访问测试执行和规划数据
- 创建自定义报表：生成 Power BI 报表和其他分析解决方案
架构命名空间
Analytics 数据模型在两个模式命名空间上进行操作：
Microsoft.VisualStudio.Services.Analytics.ModelMicrosoft.VisualStudio.Services.Analytics
这些命名空间组织实体并定义其结构，确保跨不同 Azure DevOps 功能的一致数据访问模式。
实体集和实体类型
实体类型命名为具有键的结构化类型。 它们定义每个实体的命名属性和关系。 基于EntityType的键由一部分基元属性（例如WorkItemId、PipelineId、ReleasePipelineId）以及实体类型的其他属性组成。
实体集是实体的命名集合。 例如， WorkItems 是包含实体的 WorkItem 实体集。 实体的键唯一标识实体集中的实体。 如果多个实体集使用相同的实体类型，则键值的相同组合可以出现在多个实体集中并标识不同的实体，每个实体集显示此组合键。 其中每个实体都有不同的实体 ID。实体集提供数据模型中的入口点。
实体集在 OData 元数据中描述，并且因项目而异。 可以通过请求项目的 OData 元数据来浏览实体集、实体类型和属性的完整列表。 若要了解如何操作，请参阅 为 Analytics 构造 OData 查询。
复合实体
复合实体支持特定方案。 系统从更简单的实体组成它们，通常需要更多的计算资源才能生成，并可能返回更大的结果集。 若要实现最佳性能并避免不必要的限制，请确保查询方案的正确实体。
例如， WorkItemSnapshot 合并 WorkItemRevisions 并 Dates 让每个日期为每个工作项都有一个修订。 此表示形式支持 OData 查询，这些查询侧重于筛选的工作项集的趋势数据。 但是，不应使用此复合实体来查询工作项的当前状态。 相反，应使用 WorkItems 实体集生成更快运行的查询。
同样，某些实体可能包含所有历史值，而另一些实体可能仅包含当前值。
WorkItemRevisions 包含所有工作项历史记录，在当前值感兴趣的情况下，不应使用这些历史记录。
关系
若要生成更复杂的查询结果，可以使用关系合并实体。 可以使用关系来扩展、筛选或汇总数据。
某些导航属性会导致单个实体，而另一些则会导致实体集合。 下图显示了选择实体及其导航属性。 为清楚起见，省略了一些复合实体和关系。
了解实体关系
Analytics 数据模型使用多种关系类型：
- 一对多：单个父实体与多个子实体相关（例如，一个区域对应多个工作项）
- 多对一：多个实体与单个父实体相关（例如，多个工作项与一个区域）
- 一对一：单个实体与另一个实体完全相关
- 多对多：多个实体与多个其他实体相关（例如，工作项与标签之间的关系）
关系键
实体关系也表示为外键，以便外部工具可以联接实体。 这些属性具有后缀“SK”，并且是整数或 GUID 数据类型。 日期属性具有以下格式的相应整数日期键属性： YYYYMMDD。
工作跟踪实体类型和实体集
指示的 API 版本支持以下实体类型和实体集。 有关完整参考，请参阅 Azure Boards Analytics 的工作跟踪元数据参考。
EntityType/EntitySet |
说明 | v1.0 | v2.0 | v3.0-preview | v4.0-preview |
|---|---|---|---|---|---|
|
区域/ 地区 |
工作项 “区域路径”，具有用于按区域层次结构分组和筛选的属性。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
迭代/ 迭代次数 |
工作项 迭代路径，具有用于按迭代层次结构分组和筛选的属性。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
BoardLocation/ BoardLocations |
板单元位置（由板柱、泳道和拆分标识）包括历史板设置。 有关每个板字段的说明，请参阅 “工作流”和“板”字段。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
CalendarDate/ 日期 |
用于使用关系筛选和分组其他实体的日期。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
项目/ 项目 |
为组织定义的所有项目 (云) 或项目集合 (本地) 。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
处理/ 进程 |
用于展开或筛选工作项和工作项类型的积压工作信息。 有关使用 进程 筛选报表的示例，请参阅 要求跟踪示例报表。 | ✔️ | ✔️ | ✔️ | |
|
标记/ 标记 |
每个项目的所有工作项标记。 有关使用 标记 筛选报表的示例，请参阅 发布进度示例报表。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
团队/ 团队 |
为项目定义的所有团队。 有关使用 Teams 筛选报表的示例，请参阅 向 Power BI 报表添加团队切片器。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
用户/ 用户 |
用于展开或筛选各种工作项属性的用户信息，例如 “分配给”， 创建者。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
工作项板快照/ 工作项看板快照 |
（复合）每个日历日期（包括板位置）上每个工作项的状态，用于生成趋势报告。 有关示例报表，请参阅 (CFD) 示例报表的累积流程图。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
WorkItemLink/ 工作项链接 |
工作项之间的链接，例如， Child、 Parent 和 Related。 仅包含最新修订的链接，不包含历史记录。 不包括超链接。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
WorkItemRevision/ 工作项修订 |
所有历史工作项修订，包括当前修订。 不包括已删除的工作项。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
WorkItemSnapshot/ WorkItemSnapshot |
(复合) 每个日历日期上每个工作项的状态，用于支持趋势报告。 有关示例报告，请参阅 Bug 趋势示例报告。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
WorkItem/ WorkItems |
工作项的当前状态。 用于支持状态报告。 有关示例报表，请参阅 将子工作项值汇总到父示例报表。 | ✔️ | ✔️ | ✔️ | ✔️ |
|
WorkItemTypeField/ 工作项类型字段 |
每个工作项类型和进程的工作项属性。 用于支持生成报表。 | ✔️ | ✔️ | ✔️ | ✔️ |
用于报告的关键工作追踪实体
生成报表时，请考虑以下主要实体集：
-
当前状态报告：使用
WorkItems来显示当前工作项状态 -
历史趋势报告：用于
WorkItemSnapshot一段时间内的趋势分析 -
详细更改跟踪：使用
WorkItemRevisions以获取全面的历史记录 -
板特定报告：用于
WorkItemBoardSnapshot看板分析
管道实体类型和实体集
v3.0-preview 或 v4.0-preview Analytics 版本支持以下实体类型和实体集。 有关完整参考，请参阅 管道元数据参考。
| 实体类型/实体集合 | 说明 | v3.0-preview | v4.0-preview |
|---|---|---|---|
| 分支 分支 |
有关测试或管道中使用的分支的基本信息。 有关示例报表，请参阅 进度状态示例报告。 | ✔️ | ✔️ |
|
ParallelPipelineJobsSnapshot/ ParallelPipelineJobsSnapshot |
(复合) 支持了解并行管道消耗。 有关并行管道测试的详细信息，请参阅 使用 Visual Studio 测试任务并行运行测试。 | ✔️ | |
| 管道 管道 |
管道的属性。 | ✔️ | ✔️ |
|
PipelineJob/ PipelineJobs |
管道运行中特定作业的单个执行结果。 | ✔️ | ✔️ |
|
PipelineRun/ PipelineRuns |
管道的执行信息。 有关示例报表，请参阅 管道传递率趋势示例报告。 | ✔️ | ✔️ |
|
PipelineRunActivityResult/ PipelineRunActivityResults |
特定管道执行中的所有阶段、步骤、作业和任务的合并日志。 有关示例报表，请参阅 管道任务工期示例报表。 | ✔️ | ✔️ |
|
PipelineTask/ PipelineTasks |
管道中使用的任务的属性。 | ✔️ | ✔️ |
|
TaskAgentPoolSizeSnapshot/ TaskAgentPoolSizeSnapshots |
(复合) 支持了解池大小、管道作业和并发性。 代理池的历史图说明了如何使用此实体集。 | ✔️ | |
|
TaskAgentRequestSnapshot/ TaskAgentRequestSnapshots |
（复合）提供有关一段时间内代理请求模式和资源利用率的见解。 | ✔️ |
管道实体使用模式
不同的管道实体提供特定的报告方案：
-
管道概述报告：使用
Pipelines和PipelineRuns用于高级指标 -
性能分析：使用
PipelineRunActivityResults进行详细的计时分析 -
资源利用率：用于
TaskAgentPoolSizeSnapshot容量规划 -
失败分析：用于
PipelineJobs作业级成功/失败跟踪
测试实体类型和实体集
v3.0-preview 或 v4.0-preview Analytics 版本支持以下实体类型和实体集。 有关完整参考，请参阅 测试元数据参考。
EntityType/EntitySet |
说明 | v3.0-preview | v4.0-preview |
|---|---|---|---|
|
TestConfiguration/ TestConfigurations |
测试计划配置信息。 有关配置测试的详细信息，请参阅 测试不同的配置。 | ✔️ | ✔️ |
|
TestResult/ TestResults |
与 TestRun 关联的特定测试的单个执行结果。 | ✔️ | ✔️ |
|
TestResultsDaily/ TestResultsDaily |
TestResult 执行的每日快照聚合，按 Test（而不是 TestRun）分组。 有关示例报表，请参阅 测试摘要趋势示例报告。 | ✔️ | ✔️ |
|
TestRun/ TestRuns |
测试的执行信息在包含聚合 TestResult 数据的管道下运行。 | ✔️ | ✔️ |
|
测试/ 测试 |
测试用例的属性，例如测试名称和测试所有者。 有关定义测试用例的详细信息，请参阅 创建手动测试用例。 | ✔️ | ✔️ |
|
TestPoint/ TestPoints |
测试点的执行信息。 测试点是测试用例、测试套件、配置和测试人员的唯一组合。 有关示例报表，请参阅 进度状态示例报告。 | ✔️ | ✔️ |
|
TestPointHistorySnapshot/ TestPointHistorySnapshots |
（复合）一段时间内测试点的历史执行数据。 有关示例报表，请参阅 手动测试执行趋势示例报告。 | ✔️ | ✔️ |
|
TestSuite/ TestSuites |
测试套件信息。 有关定义测试套件的详细信息，请参阅 创建测试计划和测试套件。 | ✔️ | ✔️ |
测试实体报告场景
测试实体支持各种报告需求：
-
测试执行跟踪：使用
TestResults和TestRuns获取详细的执行数据 -
测试规划指标：使用
TestPoints和TestSuites规划覆盖范围 -
趋势分析：使用
TestResultsDaily和TestPointHistorySnapshots进行历史趋势分析 -
配置覆盖范围：使用
TestConfigurations进行多平台测试分析
使用 Analytics 数据模型的最佳做法
性能优化
- 选择正确的实体：使用当前状态实体来进行状态报告，使用快照实体来分析趋势。
- 提前筛选：在实体级别应用筛选器，而不是在数据检索后应用筛选器
- 限制数据范围：使用日期筛选器限制历史数据查询
- 使用适当的聚合：尽可能利用内置聚合函数
查询设计模式
当前状态查询
/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State
历史趋势查询
/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK
关系导航
/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)
要避免的常见陷阱
-
对当前状态使用修订实体：如果
WorkItems已足够，不要使用WorkItemRevisions - 过度扩展关系：仅展开必要的导航属性
- 缺少筛选器：始终筛选大型实体集以提高性能
-
忽略复合实体：使用复合实体，例如
WorkItemSnapshot等用于趋势分析
版本注意事项
不同的 API 版本提供不同的功能：
- v1.0：基本工作跟踪实体
- v2.0：添加了进程和增强的筛选功能
- v3.0-preview：添加了管道和测试实体
- v4.0-preview：增强的复合实体和其他管道指标
根据报告要求和需要访问的实体选择适当的版本。