Bonnes pratiques d’analyse

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

Analytics est la plateforme de création de rapports pour Azure DevOps, qui vous permet d’obtenir des insights à partir de vos données et de prendre des décisions pilotées par les données. L’analytique est optimisée pour l’accès en lecture rapide et les agrégations basées sur le serveur, et fournit différents outils pour visualiser et analyser vos données. Dans cet article, nous partageons certaines bonnes pratiques pour l’utilisation d’Analytics dans Azure DevOps.

• Si vous êtes développeur d’extensions, veillez à consulter les instructions de requête OData Analytics.

Familiarisez-vous avec les métadonnées Analytics

Interrogez les métadonnées Analytics pour connaître les types d’entités, les jeux d’entités, les propriétés et les listes énumérées. Pour plus d’informations, consultez Interroger le service Analytics, les métadonnées OData Analytics et les entités et propriétés de référence pour Azure Boards.

Structurez votre requête pour retourner les données dont vous avez besoin

Pour interroger le jeu de données minimal dont vous avez besoin pour créer votre rapport, procédez comme suit :

• Choisissez l’ensemble d’entités qui prend en charge le rapport que vous souhaitez créer
• Spécifier des parties de requête dans l’ordre dans lequel elles sont exécutées
• Limiter les colonnes que vous demandez dans votre requête
• Créer des requêtes en préversion
• Limiter les requêtes aux projets auquel vous avez accès

Choisir l’ensemble d’entités pour prendre en charge votre rapport

Bien qu'il existe plusieurs éléments EntitySets pris en charge dans le modèle de données Analytics, seuls quelques éléments sont utilisés pour générer des rapports. EntitySets utilisés pour générer des rapports se répartissent en trois catégories :

• Actif : contient des informations sur la configuration actuelle du EntityTypes contenu dans le EntitySet.
• Instantané : entités composites qui combinent des données historiques et liées à la date. Les entités d’instantané sont conçues pour faciliter l'élaboration de rapports de synthèse.
• Révision : contient des informations historiques. Par exemple, WorkItemRevision conserve des données sur l’historique des éléments de travail.

Voici une référence rapide pour les "EntityTypes" à spécifier afin de soutenir les rapports. Pour obtenir une description de chacun de ces EntityTypes, consultez le modèle de données pour Analytics.

Spécifier des parties de requête dans l’ordre dans lequel elles sont exécutées

L’ordre recommandé pour les différentes parties de requête consiste à les spécifier dans l’ordre suivant, qui est l’ordre dans lequel ils sont évalués. Pour obtenir une description de chaque partie de requête, consultez Options de requête du service Analytics.

1. $apply
2. $filter
3. $orderby
4. $expand
5. $select
6. $skip
7. $top

Toutes les requêtes doivent contenir une clause $apply ou $select, sinon vous risquez de recevoir un message d’avertissement.

Limiter les colonnes que vous demandez dans votre requête

Vous spécifiez des colonnes de données à retourner à l’aide de la $select clause. Avec la personnalisation, les éléments de travail peuvent avoir de nombreux champs associés. Plus une requête référence de propriétés ou de champs, plus il est coûteux de la traiter. Considérez le rapport que vous souhaitez générer et vérifiez que vous demandez uniquement les champs dont vous avez besoin.

Par exemple, pour renvoyer les champs ID, Type d’élément de travail, Titre et État d’un ensemble filtré d’éléments de travail, spécifiez la clause suivante $select : $select=WorkItemId, WorkItemType, Title, State.

Pour rechercher la liste des propriétés et leurs noms de champs correspondants, consultez entités et références de propriétés pour Azure Boards.

Créer des requêtes en préversion

Les requêtes en préversion sont des requêtes qui retournent un enregistrement unique ou un petit sous-ensemble d’enregistrements. En créant une requête en préversion, vous pouvez affiner votre requête pour vous assurer que vous demandez les données dont vous avez besoin. En commençant par une requête minimale, vous pouvez créer votre requête pour vous assurer que vous spécifiez les enregistrements souhaités et les données de colonne dont vous avez besoin.

En utilisant le apply=aggregate($count as Count)fichier , vous pouvez identifier le nombre d’enregistrements que vous demandez. Par exemple, la syntaxe suivante interroge le nombre d’éléments de travail pour le projet Fabrikam Fibre .

https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $apply=aggregate($count as Count)

La réponse retourne un total de 1415 éléments de travail.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam Fbier/_odata/v4.0-preview/$metadata#WorkItems(Count)",
   "value": [
  {
     "@odata.id": null,
   "Count": 1415
  }
  ]
}

Limiter les requêtes aux projets auquel vous avez accès

Les requêtes d’étendue de projet retournent des informations sur un projet unique, tandis que les requêtes d’étendue de l’organisation sont conçues pour renvoyer des informations qui dépassent les limites du projet. Les requêtes délimitées à l’organisation nécessitent des autorisations utilisateur plus larges ou des restrictions d’étendue minutieuses pour s’assurer que votre requête n’est pas bloquée en raison d’un manque d’autorisations de projet.

Si vous avez accès à un ou plusieurs projets, mais pas tous les projets, et que vous envoyez une requête délimitée à l’organisation, vous recevez un message d’erreur.

"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."

Pour plus d’informations, consultez les requêtes applicables aux projets et aux organisations.

Passer en revue les messages d’avertissement et d’erreur

Analytics examine chaque requête qu’elle reçoit pour les violations de ses règles. Il retourne des messages d’avertissement lorsqu’il détecte une violation. Nous vous recommandons de passer en revue ces messages pour corriger ou améliorer la structure de requête.

Contenu connexe

• Qu’est-ce que le service Analytics ?
• Construire des requêtes OData pour Analytics
• Métadonnées OData d’analyse
• Instructions relatives aux requêtes OData Analytics