Construire des requêtes OData pour Analytics dans Azure DevOps

Article
03/20/2024

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

Accès : être membre d’un projet avec au moins un accès de base .
Autorisations : par défaut, les membres du projet ont l’autorisation d’interroger Analytics et de créer des vues.
Pour plus d’informations sur les autres prérequis concernant l’activation du service et des fonctionnalités et les activités de suivi des données générales, consultez Autorisations et conditions préalables 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.

Cloud (Azure DevOps Services)
Local (Azure DevOps Server

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

Pour interroger les métadonnées d’un serveur local, entrez la syntaxe d’URL, comme indiqué ci-dessous dans un navigateur web. Remplacez {ServerName}, {CollectionName} et {ProjectName} par vos noms locaux. Pour retourner toutes les métadonnées de la collection, ne spécifiez pas le nom du projet.

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

Remarque

Voici un exemple pour le serveur nommé fabrikam-devops et hébergé DefaultCollection sur Azure DevOps Server 2022 :

https://fabrikam-devops/DefaultCollection/_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.

Cloud (Azure DevOps Services)
Local (Azure DevOps Server

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

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

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

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

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

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.

Cloud (Azure DevOps Services)
Local (Azure DevOps Server

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"
   }
 ]
}

Voici un exemple qui interroge l’ensemble Projects d’entités pour retourner les noms de tous les projets définis sur DefaultCollection sur le serveur fabrikam,

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

L’exemple retourne trois noms de projet.

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

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`, , `expand,` `compute` `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 `$select`objet ,`$filter`ou `$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`, , , `$search`et .`$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=true`pour 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

Partager via

Construire des requêtes OData pour Analytics dans Azure DevOps

Prérequis

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

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

Composants d’URL pour interroger des entités

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

Options de requête

Appliquer la pagination côté serveur

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

Construire des requêtes OData pour Analytics dans Azure DevOps

Prérequis

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

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

Entités associées et propriétés de navigation

Composants d’URL pour interroger des entités

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

Options de requête

Appliquer la pagination côté serveur

Étapes suivantes

Articles connexes

Commentaires

Ressources supplémentaires