分析 OData 元数据

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

了解与 Analytics 实体模型关联的元数据是以编程方式查询 Analytics 数据模型的先决条件。 OData 元数据是实体模型的计算机可读说明，旨在启用客户端使用。

注意

“开放数据协议 (OData) 是基于核心协议（如 HTTP）和常用方法（如 REST 网页版）构建的数据访问协议。 可以使用各种库和工具来使用 OData 服务。” - OData 组织基本教程。

在本文中，你将学习如何：

• 查询特定项目的元数据
• 查询组织的元数据
• 标识与实体关联的键、属性和导航属性
• 确定 Analytics OData 终结点的功能

有关所有 OData 元素的详细说明，请参阅 OData 模型。 有关查询元数据的信息，请参阅 为 Analytics 构造 OData 查询。

注意

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

实体集和实体类型

实体是数据模型中的核心标识类型。 实体集是实体的命名集合。 例如， Projects 是包含 Project 实体的实体集。 一个实体最多可以是一个实体集的成员。

EntitySets 和 EntityTypes 定义分析模型中的每个实体，包括属性和关系。 实体类型定义实体的命名属性和关系。 实体类型可以通过从其他实体类型的单个继承派生。 实体类型的键由其基元属性的子集构成。

以下示例显示与实体类型关联的 Project 元数据。

<EntityType Name="Project">
  <Key>
    <PropertyRef Name="ProjectSK"/>
  </Key>
  <Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="ProjectId" Type="Edm.Guid" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Id"/>
  </Property>
  <Property Name="ProjectName" Type="Edm.String" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Name"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="ProjectVisibility" Type="Microsoft.VisualStudio.Services.Analytics.Model.ProjectVisibility">
    <Annotation Term="Display.DisplayName" String="Project Visibility"/>
  </Property>
  <NavigationProperty Name="Areas" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Area)"/>
  <NavigationProperty Name="Iterations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Iteration)"/>
  <NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
</EntityType>

键

Keys 定义可用作导航属性的实体属性。

<Key>
   <PropertyRef Name="ProjectSK"/>
</Key>

属性

可用于查询的实体属性集。 批注表示有关给定属性的其他详细信息。

应对最终用户可见的 Analytics 的任何属性都使用 DisplayName进行批注。

<Property Name="ProjectSK" Nullable="false" Type="Edm.Guid"/>
<Property Name="ProjectId" Nullable="false" Type="Edm.Guid">
   <Annotation String="Project Id" Term="Display.DisplayName"/>
</Property>
<Property Name="ProjectName" Nullable="false" Type="Edm.String">
   <Annotation String="Project Name" Term="Display.DisplayName"/>
</Property>

ReferenceName 是另一个通用注释，用于定义特定属性的系统标识符。

<Property Name="State" Type="Edm.String">
   <Annotation String="State" Term="Display.DisplayName"/>
   <Annotation String="System.State" Term="Ref.ReferenceName"/>
</Property>

导航属性

查询单个实体很有用。 最终，你可能想要筛选或展开另一个实体的详细信息。 为此，需要了解如何使用实体模型的 导航属性 。

NavigationaProperty具有集合类型的 表示模型中的多对多关系。

<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>

ReferentialConstraints 将导航属性绑定到实体的特定键，表示模型中的多对一关系。

<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <ReferentialConstraint ReferencedProperty="ProjectSK" Property="ProjectSK"/>
</NavigationProperty>

容器 (OData 功能)

EntitySets

实体是数据模型中的核心标识类型。 实体集是实体的命名集合。 例如， WorkItems 和 WorkItemRevisions 位于EntitySets名为 Container的 EntityContainer 中。 一个实体最多可以是一个实体集的成员。 实体集提供数据模型中的主要入口点，并表示实体和关联的 Navigational 属性绑定和注释的集合。

以下语法指示 Projects 实体集数据模型。 有关每个实体集的说明，请参阅 用于分析的数据模型。

<EntitySet Name="Projects" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.Project">
  <NavigationPropertyBinding Path="Areas" Target="Areas"/>
  <NavigationPropertyBinding Path="Iterations" Target="Iterations"/>
  <NavigationPropertyBinding Path="Teams" Target="Teams"/>
  <Annotation Term="Org.OData.Display.V1.DisplayName" String="Projects"/>
</EntitySet>

功能

功能定义 Analytics OData 终结点理解的 函数 集。

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
   <Collection>
      <String>contains</String>
      <String>endswith</String>
      <String>startswith</String>
      <String>length</String>
      <String>indexof</String>
      <String>substring</String>
      <String>tolower</String>
      <String>toupper</String>
      <String>trim</String>
      <String>concat</String>
      <String>year</String>
      <String>month</String>
      <String>day</String>
      <String>hour</String>
      <String>minute</String>
      <String>second</String>
      <String>fractionalseconds</String>
      <String>round</String>
      <String>floor</String>
      <String>ceiling</String>
      <String>date</String>
      <String>time</String>
      <String>isof</String>
      <String>cast</String>
   </Collection>
</Annotation>

聚合

聚合注释定义 Analytics OData 终结点理解的 转换 集。

<Annotation Term="Org.OData.Aggregation.V1.ApplySupported">
   <Record>
      <PropertyValue Property="Transformations">
         <Collection>
            <String>aggregate</String>
            <String>filter</String>
            <String>groupby</String>
            <String>compute</String>
            <String>expand</String>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="CustomAggregationMethods ">
         <Collection>
           <String>ax.ApproxCountDistinct</String>
           <String>ax.StandardDeviation</String>
           <String>ax.StandardDeviationP</String>
           <String>ax.Variance</String>
           <String>ax.VarianceP</String>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType" Bool="true"/>
<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType">
   <Record>
      <PropertyValue Property="Supported" Bool="true"/>
      <PropertyValue Property="ContinueOnErrorSupported" Bool="false"/>
      <PropertyValue Property="ReferencesInRequestBodiesSupported" Bool="false"/>
      <PropertyValue Property="ReferencesAcrossChangeSetsSupported" Bool="false"/>
      <PropertyValue Property="EtagReferencesSupported" Bool="false"/>
   </Record>
</Annotation>

后续步骤

Analytics 数据模型

相关文章

• Analytics 数据模型
• 组织和项目范围的查询。
• 可以通过 Analytics 获取的数据
• 使用 Analytics 查询工作跟踪数据
• Azure Boards的实体和属性参考

相关资源

• Wiql 到 OData 市场扩展
• OData 组织基本教程
• OData 版本 4.0。 第 3 部分：通用架构定义语言 (CSDL) 加上勘误表 03，实体模型包装器