分析 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 定義可用來做為導覽屬性的實體屬性。

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

導覽屬性

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

具有集合類型的 ， 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 。 實體最多可以是一個實體集的成員。 實體集提供資料模型的主要進入點，並代表實體集合和相關聯的導覽屬性系結和批註。

下列語法表示 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 取得的資料
• 流量分析查詢工作追蹤資料
• Azure Boards的實體和屬性參考

相關資源

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