分享方式:


分析 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 版本設定

注意

Azure DevOps Server 2020 版和更新版本的所有新專案集合都會在生產環境中自動安裝並支援 Analytics 服務。 Power BI 整合 和存取 Analytics Service 的 OData 摘要 已正式推出。 我們鼓勵您使用它,並提供意見反應給我們。 如果您從 Azure DevOps Server 2019 升級,您可以在升級期間安裝 Analytics 服務。

可用的資料與版本相依。 最新支援的版本為 v2.0 ,而最新的預覽版本為 v4.0-preview 。 如需詳細資訊,請參閱 OData API 版本設定

注意

分析服務目前為 2019 Azure DevOps Server預覽版。 您可以為專案集合 啟用或安裝它Power BI 整合 並存取 Analytics Service 的 OData 摘要 處於預覽狀態。 我們鼓勵您使用它,並提供意見反應給我們。

可用的資料與版本相依。 最新支援的版本為 v2.0 ,而最新的預覽版本為 v4.0-preview 。 如需詳細資訊,請參閱 OData API 版本設定

實體集和實體類型

實體是資料模型中的核心識別類型。 實體集是實體的具名集合。 例如, Projects 是包含 Project 實體的實體集。 實體最多可以是一個實體集的成員。

EntitySetsEntityTypes 定義分析模型中的每個實體,包括屬性和關聯性。 實體類型會定義實體的具名屬性和關聯性。 實體類型可能衍生自其他實體類型的單一繼承。 實體類型的索引鍵是由其基本屬性的子集所組成。

下列範例顯示與 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

實體是資料模型中的核心識別類型。 實體集是實體的具名集合。 例如, WorkItemsWorkItemRevisions 位於 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>

下一步