Modèle de données pour Analytics

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

Le modèle de données Analytics pour Azure DevOps se compose d’ensembles d’entités, dont les membres (entités) contiennent des propriétés que vous pouvez filtrer, agréger et résumer. En outre, ils contiennent des propriétés de navigation qui associent des entités à l’autre, fournissant l’accès à d’autres propriétés pour la sélection, le filtrage et le regroupement.

Présentation du modèle de données Analytics

Le service Analytics offre une approche structurée pour accéder aux données Azure DevOps via des points de terminaison OData. Ce modèle de données vous permet de :

• Interroger les données de suivi du travail : Accéder aux éléments de travail, aux zones, aux itérations et aux métadonnées associées
• Analyser les informations du pipeline : Interroger des données de pipeline de génération et de mise en production
• Rapport sur les résultats des tests : Accéder aux données d’exécution et de planification des tests
• Créer des rapports personnalisés : Créer des rapports Power BI et d’autres solutions d’analytique

Espaces de noms de schéma

Le modèle de données Analytics opère sur deux espaces de noms de schéma.

• Microsoft.VisualStudio.Services.Analytics.Model
• Microsoft.VisualStudio.Services.Analytics

Ces espaces de noms organisent les entités et définissent leur structure, ce qui garantit des modèles d’accès aux données cohérents entre différentes fonctionnalités Azure DevOps.

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

Les types d’entités sont nommés types structurés avec une clé. Ils définissent les propriétés et relations nommées de chaque entité. La clé d'un EntityType est formée à partir d'un sous-ensemble des propriétés primitives—par exemple, WorkItemId, PipelineId, ReleasePipelineId—et d'autres propriétés du type d'entité.

Les jeux d’entités sont des collections nommées d’entités. Par exemple, WorkItems il s’agit d’un jeu d’entités contenant des WorkItem entités. La clé d’une entité identifie de façon unique l’entité au sein d’un jeu d’entités. Si plusieurs jeux d’entités utilisent le même type d’entité, la même combinaison de valeurs de clé peut apparaître dans plusieurs ensembles d’entités et identifie différentes entités, une par jeu d’entités où cette combinaison de clés s’affiche. Chacune de ces entités a un ID d’entité différent. Les jeux d’entités fournissent des points d’entrée dans le modèle de données.

Les jeux d’entités sont décrits dans les métadonnées OData et varient selon le projet. Vous pouvez explorer la liste complète des jeux d’entités, des types d’entités et des propriétés en demandant les métadonnées OData pour votre projet. Pour en savoir plus, consultez Créer des requêtes OData pour Analytics.

Entités composées

Les entités composites prennent en charge des scénarios spécifiques. Le système les compose à partir d’entités plus simples, nécessite souvent davantage de ressources informatiques pour générer et peut retourner des jeux de résultats plus volumineux. Pour obtenir les meilleures performances et éviter une limitation inutile, veillez à interroger l’entité appropriée pour votre scénario.

Par exemple, WorkItemSnapshot combine et WorkItemRevisionsDates telle que chaque date a une révision pour chaque élément de travail. Cette représentation prend en charge les requêtes OData qui se concentrent sur les données de tendance pour un ensemble filtré d’éléments de travail. Toutefois, vous ne devez pas utiliser cette entité composite pour interroger l’état actuel des éléments de travail. Au lieu de cela, vous devez utiliser l’ensemble d’entités WorkItems pour générer une requête s'exécutant plus rapidement.

De même, certaines entités peuvent contenir toutes les valeurs historiques, tandis que d’autres peuvent contenir uniquement des valeurs actuelles. WorkItemRevisions contient l’historique des éléments de travail, que vous ne devez pas utiliser dans les scénarios où les valeurs actuelles sont intéressantes.

Relations

Pour générer des résultats de requête plus complexes, vous pouvez combiner des entités à l’aide de relations. Vous pouvez utiliser des relations pour développer, filtrer ou synthétiser des données.

Certaines propriétés de navigation entraînent une entité unique, tandis que d’autres entraînent une collection d’entités. Le diagramme suivant montre les entités sélectionnées et leurs propriétés de navigation. Pour plus de clarté, certaines entités et relations composites ont été omises.

Présentation des relations d’entité

Le modèle de données Analytics utilise plusieurs types de relations :

• Un-à-plusieurs : une entité parente unique est liée à plusieurs entités enfants (par exemple, une Zone à plusieurs WorkItems)
• Plusieurs à un : plusieurs entités sont liées à une entité parente unique (par exemple, de nombreux WorkItems à une seule zone)
• Un-à-un : une seule entité se rapporte exactement à une autre entité
• Many-to-many : plusieurs entités sont liées à plusieurs autres entités (par exemple, WorkItems à Tags)

Clés de relation

Les relations d’entité sont également représentées en tant que clés étrangères afin que les outils externes puissent joindre des entités. Ces propriétés ont le suffixe « SK » et sont des types de données entiers ou GUID. Les propriétés de date ont des propriétés de clé de date entière correspondantes au format suivant : AAAAMMDD.

Types d’entités et jeux d’entités de suivi du travail

Les types d’entités et les jeux d’entités suivants sont pris en charge avec les versions d’API indiquées. Pour obtenir une référence complète, consultez informations de référence sur les métadonnées de suivi des travaux pour Azure Boards Analytics.

Entités clés de suivi de travail pour l'élaboration de rapports

Lors de la génération de rapports, tenez compte de ces jeux d’entités principaux :

• Rapports d’état actuels : Utiliser WorkItems pour l’état actuel de l’élément de travail
• Rapports de tendances historiques : Utilisation WorkItemSnapshot pour l’analyse des tendances au fil du temps
• Suivi détaillé des modifications : Utilisation WorkItemRevisions pour l’historique complet
• Rapports spécifiques au tableau : utiliser WorkItemBoardSnapshot pour l’analyse de tableau Kanban

Meilleures pratiques pour l’utilisation du modèle de données Analytics

Optimisation des performances

1. Choisissez l’entité appropriée : utiliser les entités d’état actuelles (WorkItems) pour les rapports d’état et les entités d’instantané pour les tendances
2. Filtrer tôt : Appliquer des filtres au niveau de l’entité plutôt qu’après la récupération des données
3. Limiter les plages de données : utiliser des filtres de date pour restreindre les requêtes de données historiques
4. Utiliser les agrégations appropriées : tirer parti des fonctions d’agrégation intégrées lorsque cela est possible

Modèles de conception de requête

Les requêtes d'état actuelles

/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State

Requêtes de tendance historique

/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK

Navigation des relations

/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)

Pièges courants à éviter

• Utilisation d’entités de révision pour l’état actuel : n’utilisez WorkItemRevisions pas quand WorkItems cela suffit
• Relations trop étendues : développez uniquement les propriétés de navigation nécessaires
• Filtres manquants : filtrez toujours des jeux d’entités volumineux pour améliorer les performances
• Ignorer les entités composites : utiliser des entités composites comme WorkItemSnapshot pour l’analyse des tendances

Considérations relatives à la version

Différentes versions d’API offrent différentes fonctionnalités :

• v1.0 : Entités de suivi de travail de base
• v2.0 : Ajout de fonctionnalités de filtrage et de processus améliorés
• v3.0-preview : Ajout d’entités de pipeline et de test
• v4.0-preview : entités composites améliorées et métriques de pipeline supplémentaires

Choisissez la version appropriée en fonction de vos exigences de création de rapports et des entités auxquelles vous devez accéder.

Articles connexes

• Instructions relatives aux requêtes OData Analytics
• Analytique WIT
• Données agrégées
• Exploration des métadonnées OData Analytics
• Limites du suivi du travail, des processus et des projets
• Conception du jeu de données des vues d’analyse
• Construire des requêtes OData pour Analytics
• Sécurité et autorisations d’analyse