Construire des requêtes OData pour Analytics dans Azure DevOps

  • Article

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

L’analytique, la plateforme de création de rapports pour Azure DevOps, peut répondre à des questions quantitatives sur l’état passé ou actuel de vos projets. Analytics prend en charge les requêtes OData de ses métadonnées et de ses données de jeu d’entités. En faisant l’exercice de requêtes simples à partir de votre navigateur web, vous pouvez vous familiariser avec le modèle de données et le processus de requête.

Dans cet article, vous allez découvrir les éléments suivants :

  • Comment construire une requête OData Analytics pour le cloud ou local
  • Comment interroger des métadonnées Analytics
  • Comment interroger Analytics OData pour un jeu d’entités
  • Quelles options de requête sont prises en charge et la séquence recommandée
  • Lorsque la pagination côté serveur est appliquée

Vous pouvez interroger Analytics à partir de n’importe quel navigateur web pris en charge. Pour d’autres outils que vous pouvez utiliser pour interroger Analytics, consultez outils de requête Analytics.

Remarque

OData, un protocole au niveau de l’application pour interagir avec les données via des interfaces RESTful (où REST=Representational State Transfer), prend en charge la description des modèles de données, ainsi que la modification et l’interrogation de données en fonction de ces modèles. Le modèle de données d’entité (EDM) ou les métadonnées décrit les informations disponibles à partir d’Analytics, notamment les entités, les types d’entités, les propriétés, les relations et les énumérations que vous utilisez pour interroger les données pour générer des rapports. Pour obtenir une vue d’ensemble d’OData, consultez Bienvenue dans OData.

Prérequis

  • Pour afficher les données Analytics et interroger le service, vous devez être membre d’un projet avec un accès de base ou supérieur. Par défaut, tous les membres du projet sont autorisés à interroger Analytics et à définir des vues Analytics.
  • Pour en savoir plus sur les autres prérequis concernant l’activation des services et des fonctionnalités et les activités générales de suivi des données, consultez Autorisations et prérequis pour accéder à Analytics.

Composants d’URL pour interroger les métadonnées

Analytics expose le modèle d’entité à l’URL des métadonnées, formé en ajoutant $metadata à l’URL racine du service. Analytics fournit des racines de service pour un projet ou une organisation entière dans Azure DevOps.

Vous pouvez rechercher l’un des éléments de données suivants en interrogeant les métadonnées.

  • Types d’entités et jeux d’entités
  • Propriétés et propriétés de navigation
  • Clés de substitution
  • Listes énumérées
  • EntitySet
  • conteneurs
  • Fonctions de filtre (Org.OData.Capabilities.V1.FilterFunctions)
  • Agrégations prises en charge (Org.OData.Aggregation.V1.ApplySupported)
  • Prise en charge par lots (Org.OData.Capabilities.V1.BatchSupportType)

L’URL que vous utilisez varie selon que vous interrogez des données pour Azure DevOps Services (cloud) ou un serveur Azure DevOps local.

Pour interroger les métadonnées d’une organisation ou d’un projet hébergé dans le cloud, entrez la syntaxe d’URL, comme indiqué ci-dessous dans un navigateur web. Remplacez et {ProjectName} utilisez {OrganizationName} le nom de votre organisation et le nom du projet que vous souhaitez interroger. Pour retourner toutes les métadonnées de l’organisation, ne spécifiez pas le nom du projet.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Remarque

La dernière version d’Analytics OData est v4.0-preview. Vous pouvez utiliser cette version pour toutes les requêtes sur le service hébergé. Pour plus d’informations sur les versions d’Analytics et les données disponibles, consultez Le modèle de données pour Analytics.

Voici un exemple pour l’organisation fabrikam hébergée sur Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Interpréter la réponse aux métadonnées

Analytics retourne un fichier XML du modèle de données. Utilisez votre fonction de recherche de navigateur pour rechercher des informations spécifiques à l’entité d’intérêt.

Conseil

Selon le navigateur que vous utilisez, ce fichier peut ou non être mis en forme de manière lisible. S’il n’est pas mis en forme, vous pouvez trouver un formateur XML en ligne gratuit via une recherche de navigateur web.

Les deux schémas principaux définis dans les métadonnées Analytics sont Microsoft.VisualStudio.Services.Analytics.Model, qui définit les types d’entités et les types énumérés et leurs membres, et le Default schéma, qui définit les conteneurs d’entités et les jeux d’entités et les jeux d’entités pris en charge, le filtre OData, la transformation et les fonctions d’agrégation personnalisée. Pour plus d’informations, consultez métadonnées OData Analytics.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Tous les types d’entités sont associés aux propriétés et aux propriétés de navigation. Vous pouvez filtrer vos requêtes d’ensembles d’entités à l’aide de ces deux types de propriétés. Celles-ci sont répertoriées dans les métadonnées sous la EntityType forme a Property ou NavigationalProperty. Vous utilisez des entités associées pour spécifier des filtres supplémentaires, tels que des chemins d’itération, des chemins d’accès de zone ou Teams.

L’extrait de code suivant fournit une vue partielle des métadonnées de l’entité WorkItem . Les propriétés correspondent à un champ d’élément de travail ainsi qu’à des données spécifiques capturées par Analytics, telles que LeadTimeDays et CycleTimeDays. Les propriétés de navigation correspondent à d’autres jeux d’entités ou à des données Analytics spécifiques capturées pour le type d’entité, telles que Revisions, , LinksChildren, et Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Composants d’URL pour interroger des entités

Pour interroger des données Analytics et générer des rapports, vous interrogez généralement un jeu d’entités. Pour obtenir une vue d’ensemble des entités prises en charge, consultez les métadonnées OData Analytics.

L’URL suivante permet d’interroger un élément spécifique EntitySet, tel que WorkItems, WorkItemSnapshotet PipelineRuns.

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Voici un exemple pour l’organisation fabrikam qui retourne le nombre d’éléments de travail définis pour le projet Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

L’exemple retourne 1399 éléments de travail.

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

Remarque

Si vous n’incluez pas de $select clause, $apply vous recevrez un avertissement, tel qu’il "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." équivaut à effectuer une instruction select sur l’ensemble d’entités et à retourner tout, toutes les colonnes et toutes les lignes. Si vous avez un grand nombre d’enregistrements, cela peut prendre plusieurs secondes. Si vous avez plus de 10 000 éléments de travail, la pagination pilotée par le serveur est appliquée.

Pour éviter d’entrer dans des limites d’utilisation, incluez toujours une ou $apply une $select clause.

Pour obtenir des informations sur la propriété et les relations des métadonnées d’entité, consultez les articles suivants :

Exemple : Interroger un jeu d’entités spécifique

Pour interroger un jeu d’entités spécifique, tel que WorkItems, Areasou Projects, ajoutez le nom du jeu d’entités : /WorkItems, /Areasou /Projects. Pour obtenir la liste complète des jeux d’entités, consultez Le modèle de données pour Analytics.

Par exemple, vous pouvez obtenir la liste des projets définis pour votre organisation en interrogeant /Projects et en sélectionnant pour renvoyer la ProjectName propriété. Pour l’organisation fabrikam, l’URL est indiquée ci-dessous.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics retourne les noms de projet de ces projets définis pour l’organisation fabrikam .

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Options de requête

Une option de requête est un ensemble de paramètres de chaîne de requête appliqués à une ressource qui peut aider à contrôler la quantité de données retournées pour la ressource dans l’URL.

Les options de requête doivent être spécifiées dans l’ordre indiqué dans le tableau suivant.

Option de requête Notes
$apply Ensemble de transformations que vous pouvez appliquer à une requête, par exemple : filter, groupby, aggregate, , computeexpand,concat
Pour obtenir des exemples, consultez agréger des données de suivi de travail à l’aide d’Analytics.
$compute Fonction OData prise en charge que vous pouvez spécifier pour définir des propriétés calculées qui peuvent être utilisées dans un $selectobjet ,$filterou $orderby une expression.
$filter Permet de filtrer la liste des ressources retournées. L’expression spécifiée avec $filter est évaluée pour chaque ressource de la collection, et seuls les éléments où l’expression prend la valeur true sont inclus dans la réponse. Les ressources pour lesquelles l’expression prend la valeur false ou null, ou les propriétés de référence qui ne sont pas disponibles en raison d’autorisations, sont omises de la réponse.
Pour obtenir des exemples, consultez Interroger des données de suivi du travail à l’aide d’Analytics .
$orderby Permet de spécifier la séquence dans laquelle les enregistrements doivent être retournés.
Pour obtenir des exemples, consultez Interroger des données de suivi du travail à l’aide d’Analytics.
$top/$skip Permet de limiter le nombre d’enregistrements retournés.
Pour obtenir des exemples, consultez les requêtes Project et l’étendue de l’organisation.
$select/$expand Permet $select de spécifier les colonnes dont vous avez besoin pour générer votre rapport. Permet $expand d’imbriquer d’autres options de requête. Chacun expandItem d’eux est évalué par rapport à l’entité contenant la propriété de navigation ou de flux en cours d’expansion.

Liste séparée par des points-virgules des options de requête, placée entre parenthèses, au nom de la propriété de navigation. Les options de requête système autorisées sont $filter, , $select$orderby, $skip$count$top, , , $searchet .$expand
Pour obtenir des exemples, consultez Interroger des données de suivi du travail à l’aide d’Analytics.
$skiptoken Permet d’ignorer un nombre spécifié d’enregistrements.
$count ou $count=true Entrez $count pour renvoyer uniquement le nombre d’enregistrements. Entrez $count=truepour retourner le nombre d’enregistrements et les données interrogées.
Pour obtenir des exemples, consultez agréger des données de suivi de travail à l’aide d’Analytics.

Conseil

Évitez de mélanger $apply et $filter de clauses dans une seule requête. Pour filtrer votre requête, vous avez deux options : (1) utiliser une $filter clause ou (2) utiliser une $apply=filter() clause de combinaison. Chacune de ces options fonctionne parfaitement sur elle-même, mais la combinaison de ces options peut entraîner des résultats inattendus.

Appliquer la pagination côté serveur

L’analytique force la pagination lorsque les résultats de la requête dépassent 1 000 enregistrements. Dans ce cas, vous obtiendrez la première page de données et le lien à suivre pour obtenir la page suivante. Le lien (@odata.nextLink) se trouve à la fin de la sortie JSON. Elle ressemblera à une requête d’origine suivie ou $skip$skiptoken. Par exemple :

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Remarque

Lors de l’extraction de données dans des outils clients tels que Power BI Desktop ou Excel, les outils suivent automatiquement le lien suivant et chargent tous les enregistrements requis.

Étapes suivantes

Construire des requêtes de base à l’aide d’OData Analytics