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 版本控制。

先決條件

類別	要求
存取層級	- 專案成員。 - 至少 基本 存取權。
許可權	根據預設，項目成員具有查詢分析及建立檢視的許可權。 如需有關服務與功能啟用和一般數據追蹤活動之其他必要條件的詳細資訊，請參閱 存取 Analytics的許可權和必要條件。

實體集和實體類型

實體是數據模型中的核心身分識別類型。 實體集是實體的具名集合。 例如，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 功能）

實體集合

實體是數據模型中的核心身分識別類型。 實體集是實體的具名集合。 例如，WorkItems和 WorkItemRevisions 位於EntitySets具名 EntityContainer的 內Container。 實體最多可以是一個實體集的成員。 實體集提供進入數據模型的主要入口，並代表一組實體以及相關的導航屬性綁定和註釋。

下列語法表示 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，實體模型包裝器