Метаданные OData аналитики

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Понимание метаданных, связанных с моделью сущности для аналитики, является необходимым условием для программного запроса модели данных для аналитики. Метаданные OData — это машинное описание модели сущности, предназначенной для включения потребления клиентов.

Примечание.

"Open Data Protocol (OData) — это протокол доступа к данным, основанный на основных протоколах, таких как HTTP и часто принятые методологии, такие как REST для Интернета. Существуют различные виды библиотек и инструментов, которые можно использовать для использования служб OData". - Руководство по OData Organization Basic.

Из этой статьи вы узнаете о следующем.

• Запрос метаданных в определенном проекте
• Запрос метаданных в организации
• Определение ключей, свойств и свойств навигации, связанных с сущностью
• Определение возможностей конечной точки OData аналитики

Подробные описания для всех элементов OData см. в модели OData. Сведения о запросе метаданных см. в разделе "Создание запросов OData для аналитики".

Примечание.

Служба Аналитики автоматически включается и поддерживается в рабочей среде для всех Служб Azure DevOps Services. Интеграция Power BI и доступ к веб-каналу OData службы Аналитики общедоступны. Мы рекомендуем вам использовать его и дать нам отзыв. Доступные данные зависят от версий. Последняя поддерживаемая версия: v2.0последняя предварительная версия v4.0-preview. Дополнительные сведения см. в разделе "Управление версиями API OData".

Наборы сущностей и типы сущностей

Сущности — это основные типы удостоверений в модели данных. Наборы сущностей — это именованные коллекции сущностей. Например, это набор сущностей, 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>

Свойства навигации

Запросы к отдельной сущности полезны. В конечном итоге вы, вероятно, хотите отфильтровать или развернуть сведения о другой сущности. Для этого необходимо понять, как использовать навигационные свойства модели сущности.

Тип 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 и находятся EntitySets внутри именованного EntityContainer Container.WorkItemRevisions Сущность может быть членом не более одного набора сущностей. Наборы сущностей предоставляют основные точки входа в модель данных и представляют коллекцию сущностей и связанных привязок свойств навигации и заметок.

Следующий синтаксис указывает 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>

Возможности

Возможности определяют набор функций, понятных конечной точкой 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>

Статистические схемы

Примечания агрегирования определяют набор преобразований, понятных конечной точкой 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>

Следующие шаги

Модель данных для аналитики

Связанные статьи

• Модель данных для аналитики
• Запросы в области организации и проекта.
• Данные, доступные из Аналитики
• Запрос данных отслеживания работы с помощью Аналитики
• Справочник по сущностям и свойствам для Azure Boards

Связанные ресурсы

• Расширение Wiql to OData Marketplace
• Руководство по OData Organization Basic
• OData версии 4.0. Часть 3. Язык определения общей схемы (CSDL) плюс Errata 03, оболочка модели сущности