Métadonnées OData Analytics

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

La compréhension des métadonnées associées au modèle d’entité pour Analytics est une condition préalable à l’interrogation programmatique du modèle de données pour Analytics. Les métadonnées OData sont une description lisible par machine du modèle d’entité conçue pour permettre la consommation du client.

Notes

« Le protocole OData (Open Data Protocol) est un protocole d’accès aux données basé sur des protocoles de base comme HTTP et des méthodologies couramment acceptées comme REST pour le web. Il existe différents types de bibliothèques et d’outils peuvent être utilisés pour utiliser les services OData. - Didacticiel de base de l’organisation OData.

Cet article porte sur les points suivants :

• Interroger les métadonnées sur un projet spécifique
• Interroger les métadonnées sur un organization
• Identifier les clés, les propriétés et les propriétés de navigation associées à une entité
• Identifier les fonctionnalités du point de terminaison OData Analytics

Pour obtenir des descriptions détaillées de tous les éléments OData, consultez Modèle OData. Pour plus d’informations sur l’interrogation des métadonnées, consultez Construire des requêtes OData pour Analytics.

Notes

Le service Analytics est automatiquement activé et pris en charge en production pour tous les Azure DevOps Services. L’intégration power BI et l’accès au flux OData du service Analytics sont en disponibilité générale. Nous vous encourageons à l’utiliser et à nous faire part de vos commentaires. Les données disponibles dépendent de la version. La dernière version prise en charge est v2.0, et la dernière préversion est v4.0-preview. Pour plus d’informations, consultez Gestion des versions de l’API OData.

Jeux d’entités et types d’entités

Les entités sont les principaux types d’identité dans un modèle de données. Les jeux d’entités sont des collections nommées d’entités. Par exemple, Projects est un jeu d’entités contenant des Project entités. Une entité peut être membre d’au plus un ensemble d’entités.

EntitySets et EntityTypes définissez chacune des entités dans le modèle Analytics, y compris les propriétés et les relations. Les types d’entités définissent les propriétés et les relations nommées d’une entité. Les types d’entités peuvent dériver par héritage unique d’autres types d’entités. La clé d’un type d’entité est formée à partir d’un sous-ensemble de ses propriétés primitives.

L’exemple suivant montre les métadonnées associées au type d’entité 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

Keys définissez les propriétés d’entité disponibles pour une utilisation en tant que propriété de navigation.

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

Propriétés

Ensemble de propriétés d’entité disponibles pour la requête. Les annotations représentent d’autres détails sur une propriété donnée.

Toute propriété d’Analytics qui doit être visible par les utilisateurs finaux est annotée avec un 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 est une autre annotation courante utilisée pour définir l’identificateur système d’une propriété spécifique.

<Property Name="State" Type="Edm.String">
   <Annotation String="State" Term="Display.DisplayName"/>
   <Annotation String="System.State" Term="Ref.ReferenceName"/>
</Property>

Propriétés de navigation

L’interrogation d’une entité individuelle est utile. Finalement, vous voudrez probablement filtrer ou développer les détails d’une autre entité. Pour ce faire, vous devez comprendre comment utiliser les propriétés de navigation du modèle d’entité.

avec NavigationaProperty un type de collection représente une relation plusieurs-à-plusieurs dans le modèle.

<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>

ReferentialConstraints lier des propriétés de navigation à une clé spécifique d’une entité, représentant une relation plusieurs-à-un dans le modèle.

<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <ReferentialConstraint ReferencedProperty="ProjectSK" Property="ProjectSK"/>
</NavigationProperty>

Conteneurs (fonctionnalités OData)

EntitySets

Les entités sont les principaux types d’identité dans un modèle de données. Les jeux d’entités sont des collections nommées d’entités. Par exemple, WorkItems et WorkItemRevisions se trouvent EntitySets dans le EntityContainer nommé Container. Une entité peut être membre d’au plus un ensemble d’entités. Les jeux d’entités fournissent les points d’entrée principaux dans le modèle de données et représentent une collection d’entités et de liaisons de propriétés de navigation associées et d’annotations.

La syntaxe suivante indique le modèle de données du jeu d’entités Projects . Pour obtenir une description de chaque jeu d’entités, consultez Modèle de données pour Analytics.

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

Fonctionnalités

Les fonctionnalités définissent l’ensemble de fonctions comprises par le point de terminaison OData Analytics.

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

Agrégations

Les annotations d’agrégation définissent l’ensemble des transformations comprises par le point de terminaison OData Analytics.

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

Étapes suivantes

Modèle de données pour Analytics

Articles connexes

• Modèle de données pour Analytics
• Requêtes étendues à l’organisation et au projet.
• Données disponibles à partir d’Analytics
• Interroger les données de suivi du travail à l’aide d’Analytics
• Informations de référence sur les entités et les propriétés pour Azure Boards

Ressources associées

• Extension Wiql to OData Marketplace
• Didacticiel de base sur l’organisation OData
• OData version 4.0. Partie 3 : Langage CSDL (Common Schema Definition Language) plus Errata 03, Wrapper de modèle d’entité