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
- 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.
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 AreaSK
IterationSK
chemin 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\Internet Area 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
, startswith
endswith
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 des virgules.
$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 mots 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
Articles connexes
- Construire des requêtes OData pour Analytics
- Informations de référence sur les métadonnées pour Azure Boards Analytics
- Meilleures pratiques à utiliser lors de l’interrogation d’Analytics
- Fonctionnalités OData prises en charge
- Spécification OData v4.0
- OData v4.0 Partie 2 : Conventions d’URL plus Errata 02