Analytics OData 元數據

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

瞭解與分析實體模型相關聯的元數據，是以程式設計方式查詢 分析數據模型的必要條件。 OData 元數據是實體模型的計算機可讀取描述，其設計目的是要啟用用戶端耗用量。

注意

「開放式數據通訊協定 （OData） 是以 HTTP 等核心通訊協定為基礎的數據存取通訊協定，以及 Web 的 REST 等常用方法所建置的數據存取通訊協定。 有各種不同的連結庫和工具可用來取用 OData 服務。」 - OData 組織基本教學課程。

在本文章中，您將了解如何：

• 查詢特定專案上的元數據
• 查詢組織上的元數據
• 識別與實體相關聯的索引鍵、屬性和導覽屬性
• 識別 Analytics OData 端點的功能

如需所有 OData 元素的詳細描述，請參閱 OData 模型。 如需查詢元數據的資訊，請參閱 建構適用於分析的 OData 查詢。

注意

所有 Azure DevOps Services 的生產環境中都會自動啟用及支援 Analytics 服務。 Power BI 整合 及存取 Analytics Service 的 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 定義可用於做為導覽屬性的 Entity 屬性。

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

屬性

一組可供查詢的實體屬性。 批注代表特定屬性的其他詳細數據。

用戶應該看到的任何分析屬性都會以 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>

導覽屬性

查詢個別實體很有用。 最後，您可能會想要篩選或展開另一個實體的詳細數據。 若要這樣做，您必須瞭解如何使用 實體模型的導覽屬性 。

NavigationProperty具有集合型別的 ，表示模型中的多對多關聯性。

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

Capabilities

功能會定義 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 取得的數據
• 使用分析查詢工作追蹤數據
• Azure Boards 的實體和屬性參考

相關資源

• Wiql 至 OData Marketplace 擴充功能
• OData 組織基本教學課程
• OData 4.0 版。 第 3 部分：通用架構定義語言 （CSDL） 加上 Errata 03，實體模型包裝函式