Définir des requêtes de base à l’aide d’OData Analytics

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

À l’aide d’Analytics pour Azure DevOps, vous pouvez construire des requêtes de base et filtrées pour retourner des données intéressantes. Vous pouvez exécuter ces requêtes directement dans votre navigateur ou dans Power BI.

Cet article génère des informations fournies dans les requêtes OData de construction pour l’analytique et les métadonnées pour Azure Boards Analytics. En outre, les requêtes de cet article se concentrent sur la récupération des jeux d’entités de suivi des travaux, mais les principes s’appliquent à l’interrogation d’autres jeux d’entités.

Dans cet article, vous allez apprendre à définir des requêtes qui retournent les données suivantes :

  • Nombre d’éléments (aucune autre donnée)
  • Nombre d’éléments et de données
  • Propriétés définies pour les chemins d’itération ou zones
  • Colonnes ou champs sélectionnés
  • Données filtrées
  • Retourner des données pour les champs Identity, Area Path et Itération Path
  • Filtrer par une propriété de navigation
  • Interroger une plage de dates
  • Instructions de développement d’imbrication
  • Trier les résultats, option orderby

Remarque

Le service Analytics est automatiquement activé et pris en charge en production pour tous les services Azure DevOps. L’intégration de Power BI et l’accès au flux OData du service Analytics sont généralement disponibles. 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 version d’évaluation est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API OData.

Remarque

Le service Analytics est automatiquement installé et pris en charge en production pour toutes les nouvelles collections de projets pour Azure DevOps Server 2020 et versions ultérieures. L’intégration de Power BI et l’accès au flux OData du service Analytics sont généralement disponibles. Nous vous encourageons à l’utiliser et à nous faire part de vos commentaires. Si vous avez effectué une mise à niveau à partir d’Azure DevOps Server 2019, vous pouvez installer le service Analytics pendant la mise à niveau.

Les données disponibles dépendent de la version. La dernière version prise en charge est v2.0, et la dernière version d’évaluation est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API OData.

Remarque

Le service Analytics est en préversion pour Azure DevOps Server 2019. Vous pouvez l’activer ou l’installer pour une collection de projets. L’intégration de Power BI et l’accès au flux OData du service Analytics sont en préversion. 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 version d’évaluation est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API 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.

Remarque

Dans cet article, l’URL de requête OData est définie pour Azure DevOps Services. Pour construire une requête similaire pour un serveur local, consultez les instructions fournies dans les requêtes OData de construction pour Analytics. Nous vous encourageons à ajuster les requêtes fournies pour votre organisation et votre projet afin de vous familiariser avec l’interrogation d’OData à l’aide de votre navigateur.

Retourner un nombre d’éléments (aucune autre donnée)

Pour en savoir plus sur le nombre d’éléments ou d’entités définis dans une organisation ou un projet, spécifiez $apply=aggregate($count as Count) l’option de requête. Par exemple, les requêtes suivantes retournent le nombre de projets, d’éléments de travail, de chemins d’accès de zone et d’utilisateurs définis pour une organisation.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

Conseil

Les requêtes inter-projets échouent lorsque l’utilisateur exécutant la requête n’a pas accès à tous les projets. En savoir plus sur les exigences dans les requêtes Project et l’étendue de l’organisation.

Nombre de projets

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

Nombre d’éléments de travail

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

Nombre de zones

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

Nombre d’utilisateurs

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

Retourner un nombre d’éléments et de données

Pour renvoyer le nombre d’éléments, ainsi que les données sélectionnées pour les éléments, spécifiez l’option $count=true de requête. Par exemple, les requêtes suivantes retournent un nombre d’éléments de travail, de chemins d’accès de zone et d’utilisateurs définis pour un projet, ainsi que les propriétés spécifiées. Pour connaître les propriétés valides, consultez la référence des métadonnées pour la date, le projet et les métadonnées utilisateur d’Azure Boards Analytics.

Conseil

Si vous ne spécifiez pas les propriétés à retourner, Analytics retourne toutes les propriétés définies pour le type d’entité spécifié.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

Propriétés zones ou itérations

Pour rechercher le AreaSKIterationSKchemin d’accès ou d’itération d’un chemin d’accès de zone ou d’itération, utilisez les requêtes suivantes.

Renvoyer la ZoneSK pour un chemin d’accès à une zone spécifique

La requête suivante spécifie de renvoyer la AreaSK propriété définie pour fabrikam Fiber\Service Delivery\InternetArea Path. Pour spécifier d’autres propriétés définies pour l’ensemble Areas d’entités, consultez la référence des métadonnées pour Azure Boards Analytics, Areas.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK

La requête retourne les données suivantes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

Retourner itérationSK pour un chemin d’itération spécifique

La requête suivante spécifie de retourner la IterationSK propriété définie pour le chemin d’itération Fabrikam Fiber\Release 1\Sprint 3. Pour spécifier d’autres propriétés définies pour l’ensemble Iterations d’entités, consultez la référence des métadonnées pour Azure Boards Analytics, itérations.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

La requête retourne les données suivantes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

Retourner des propriétés ou des champs spécifiques

Pour retourner des propriétés spécifiques ou des champs d’élément de travail, ajoutez une $select clause qui spécifie les noms de propriétés.

Par exemple, pour renvoyer l’ID de l’élément de travail, le type d’élément de travail, le titre et l’état des éléments de travail, ajoutez la clause suivante à votre requête. Cette clause spécifie les propriétés qui correspondent aux champs nommés.

Remarque

Les noms de propriété ne contiennent aucun espace. Votre requête échoue si vous ajoutez des espaces. Les requêtes OData nécessitent une attention particulière à l’espacement et à la casse. Pour comprendre comment les propriétés de champ personnalisées sont étiquetées, consultez la référence des métadonnées pour Azure Boards, propriétés personnalisées.

Ici, nous spécifions pour retourner les trois premiers éléments de travail.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

Analytics retourne les données suivantes.

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

.

Filtrer vos données

Pour filtrer un jeu d’entités pour retourner des éléments sélectionnés, spécifiez une $filter clause qui spécifie les critères que les éléments doivent respecter. À partir de la dernière requête, nous ajoutons ici une clause de filtre pour renvoyer uniquement les types d’éléments de travail de fonctionnalité qui sont dans l’état En cours .

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State

Analytics retourne les données suivantes.

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

Spécifier plusieurs clauses de filtre

Vous pouvez utiliser AND et OR spécifier plusieurs clauses de filtre.

Par exemple, la requête suivante spécifie de retourner des éléments de travail de type User Story, Bug et Backlog Work (un type d’élément de travail personnalisé) qui se trouvent dans les états Nouveau, Validé ou Actif . Utilisez des parenthèses pour regrouper les clauses de filtre en fonction des besoins.

En outre, vous pouvez appliquer différentes fonctions telles que contains, startswithendswith et bien plus encore. Consultez les fonctionnalités et clauses OData prises en charge, fonctions prises en charge.

Retourner des données pour les champs Identity, Area Path et Itération Path

Les propriétés select sont associées aux propriétés de navigation et ne sont pas directement accessibles à l’aide de l’instruction $select . Vous devez utiliser une $expand instruction pour retourner les données d’intérêt. Ces propriétés sont souvent associées à plusieurs propriétés de leur choix. Par exemple, avec les champs Identity, vous pouvez spécifier de renvoyer le nom d’utilisateur ou l’e-mail de l’utilisateur.

Le tableau suivant fournit des exemples de développement de plusieurs de ces propriétés.

Champs de type Propriété référencée Exemples de clauses à inclure
Date/Heure DateSK $expand=CreatedDate($select=Date) ou
$expand=CreatedDate($select=WeekStartingDate)
Identité UserSK $expand=AssignedTo($select=UserName) ou
$expand=AssignedTo($select=UserEmail)
Zone AreaSK $expand=Area($select=AreaName) ou
$expand=Area($select=AreaPath)
Itération IterationSK $expand=Iteration($select=IterationName) ou
$expand=Iteration($select=IterationPath) ou
$expand=Iteration($select=StartDate)
Project ProjectSK $expand=Project($select=ProjectName)
Team TeamSK $expand=Teams($select=TeamName)

Pour spécifier plusieurs propriétés qui doivent être développées, vous les spécifiez dans une clause de développement unique dans une liste délimitée par un comman.

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Filtrer par une propriété de navigation

Lorsque vous spécifiez une propriété de navigation dans le cadre de vos critères de filtre, vous devez la spécifier dans le format requis.

Par exemple, la clause suivante spécifie de filtrer les éléments de travail en fonction de l’itération 1 définie pour le projet.

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Dans cet exemple, Iteration correspond au nom de la propriété de navigation et IterationPath correspond au chemin complet de l’itération. Pour utiliser une autre entité comme filtre, placez la propriété de navigation suivie d’une barre oblique suivie du nom du champ à filtrer.

Voici la requête OData complète :

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Voici un autre exemple qui demande les cinq premiers éléments de travail sous fabrikam Fibre\Service Delivery\Voice Area Path sont retournés.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

Conseil

Vous ne pouvez pas utiliser la propriété de navigation directement dans une $select instruction. Au lieu de cela, vous devez utiliser $expand.

L’exemple de filtrage précédent pour le chemin d’itération ne retourne pas le chemin d’itération, car il est contenu dans une entité associée. Pour retourner des données dans une entité associée, ajoutez une $expand instruction :

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

Voici un exemple qui retourne les informations affectées à l’ID d’élément de travail 480.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

Comme vous pouvez le voir, le chemin d’itération est développé dans le résultat et toutes les données d’itération sont retournées. Il s’agit probablement de plus de données que vous le souhaitez.

Pour retourner moins de données, ajoutez également une $select instruction à l’itération :

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

Elle retourne ensuite les données suivantes.

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

Interroger une plage de dates

L’exemple suivant retourne des éléments de travail dont la date modifiée est supérieure à celle du 1er janvier 2021.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

L’exemple suivant retourne des éléments de travail dont la date modifiée se produit pendant la semaine du 26 avril au 30 avril 2021.

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

Instructions de développement d’imbrication

Dans OData, vous pouvez imbriquer $expand des instructions. Par exemple, vous pouvez écrire l’instruction de requête précédente pour afficher le projet dont l’itération fait partie :

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

Elle retourne le code JSON suivant :

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Vous pouvez également combiner et $select utiliser $expand des instructions. Par exemple, vous pouvez modifier la requête précédente pour renvoyer uniquement le nom de l’itération et le chemin d’itération :

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

Elle retourne le code JSON suivant :

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Notez que le résultat ici affiche uniquement itérationId et ItérationPath et que le projet est un objet imbriqué dans le résultat JSON. Un autre élément clé à noter est l’URL elle-même. Lorsque vous utilisez une instruction et une $select$expand clause, vous devez utiliser un point-virgule (;) avant le $expand. Tout autre élément entraîne une erreur.

Trier les résultats, orderby option

Spécifiez l’option $orderby permettant de trier vos résultats ou spécifiez la séquence dans laquelle les résultats sont retournés. Vous pouvez trier dans l’ordre croissant ou décroissant à l’aide de mot clé s asc ou desc, respectivement. Certains exemples sont présentés

Trier par Clause à inclure
ID d'élément de travail /WorkItems?$orderby=WorkItemId
ID d’élément de travail décroissant /WorkItems?$orderby=WorkItemId desc
Type d’élément de travail et état /WorkItems?$orderby=WorkItemType,State

Étapes suivantes