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

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

Utilisez des requêtes OData Analytics pour récupérer des données de suivi du travail à partir d’Azure DevOps dans votre navigateur ou dans des outils clients tels qu’Excel et Power BI. Cet article traite du comptage des éléments, la sélection de champs spécifiques avec $select, le filtrage avec $filter, l’expansion des propriétés de navigation avec $expand, l’interrogation des plages de dates et le tri avec $orderby.

Les exemples se concentrent sur les ensembles d’entités de suivi de travail Azure Boards, mais les mêmes principes s’appliquent à d’autres ensembles d’entités. Pour plus d’informations, consultez Construire des requêtes OData pour l’analytique et les métadonnées pour Azure Boards Analytics.

Prérequis

Obtenir un nombre d’éléments

Pour retourner uniquement un nombre sans d’autres données, ajoutez $apply=aggregate($count as Count) à n’importe quelle URL d’ensemble d’entités. Par exemple, les requêtes suivantes comptent les projets, les éléments de travail, les chemins d’accès aux zones et les utilisateurs au sein d’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)

La Projects requête pour l’organisation fabrikam retourne :

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Obtenir le nombre d’éléments et leurs données

Pour retourner un nombre en même temps que les données, ajoutez $count=true à une requête qui inclut une $select clause. Les requêtes suivantes retournent un nombre plus les propriétés sélectionnées pour les éléments de travail, les chemins d’accès aux zones et les utilisateurs d’un projet :

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

Pour connaître les noms de propriétés valides, consultez les informations de référence sur les métadonnées pour Azure Boards Analytics et les informations de référence sur les métadonnées pour la date de calendrier, le projet et l'utilisateur.

Par exemple, la requête suivante retourne le nombre et les noms d’utilisateur dans le projet Fabrikam Fiber :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

La réponse inclut le nombre total dans @odata.count et les enregistrements correspondants dans value:

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Sélectionner des propriétés ou des champs spécifiques

Ajoutez une $select clause pour renvoyer uniquement les propriétés dont vous avez besoin. Les noms de propriétés respectent la sensibilité à la casse, ne peuvent pas contenir d’espaces et correspondent aux noms des champs des éléments de travail. Par exemple, $select=WorkItemId,WorkItemType,Title,State retourne ces quatre champs.

Pour les recherches de noms de propriété, y compris les champs personnalisés, consultez la référence des métadonnées pour Azure Boards.

La requête suivante retourne l’ID, le type, le titre et l’état des trois principaux éléments de travail dans le projet Fabrikam Fiber :

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

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Filtrer les données

Ajoutez une $filter clause pour renvoyer uniquement les éléments qui correspondent à des critères spécifiques. Utilisez des opérateurs de comparaison tels que eq, , negt, gelt, et lecombinez des conditions avec and et or. Par exemple, la requête suivante retourne des fonctionnalités en cours :

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

Combiner plusieurs conditions de filtre

Utilisez des parenthèses pour regrouper or des conditions au sein d’un filtre plus large and . La requête suivante renvoie des histoires utilisateur, des bogues et un type personnalisé dans des états spécifiques :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

Vous pouvez également utiliser des fonctions de chaîne comme contains, startswithet endswith dans les expressions de filtre. Pour plus d’informations, consultez Fonctions prises en charge.

Propriétés chemin d’accès de zone de requête ou chemin d’itération

Certaines requêtes nécessitent la clé de substitution (AreaSK ou IterationSK) plutôt que la chaîne de chemin d’accès. Utilisez les ensembles d’entités Zones ou Itérations pour rechercher la clé d’un chemin spécifique.

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

La requête suivante retourne le AreaSK chemin d’accès à la Fabrikam Fiber\Production Planning\Web zone. Pour obtenir d’autres propriétés disponibles, consultez Zones.

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

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Retourner "IterationSK" pour un chemin d'itération spécifique

La requête suivante retourne le IterationSK pour le chemin d’itération Fabrikam Fiber\Release 1\Sprint 3. Pour d’autres propriétés disponibles, consultez 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

Filtrer par propriétés de navigation

Les propriétés de navigation telles que Iteration, Areaet AssignedTo représentent les relations avec d’autres entités. Pour filtrer sur un champ à partir d’une entité associée, utilisez le chemin d’accès complet au format NavigationProperty/Field. Par exemple, Iteration/IterationPath référence le IterationPath champ via la propriété de Iteration navigation :

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

La requête suivante retourne les cinq premiers éléments de travail dans une itération spécifique, à l’aide du chemin de navigation complet :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Étendre les données à partir d'entités connexes

Le filtrage par une propriété de navigation n’inclut pas ses données dans la réponse. Pour retourner des champs d’une entité associée, utilisez $expand. Sans $expand, vous ne pouvez pas accéder aux champs de propriété de navigation via $select.

La requête suivante retourne un élément 480 de travail avec tous les champs de l’entité développée Iteration :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Aucun $select n'est appliqué à l'expansion Iteration, la réponse inclut chaque champ Iteration.

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Utiliser la clause select dans les instructions expand

Pour limiter les champs retournés à partir d’une entité développée, ajoutez une $select clause à l’intérieur de $expand, en utilisant la syntaxe $expand=Entity($select=Field1,Field2). La requête suivante étend Iteration, mais retourne uniquement IterationName et IterationPath.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

Le tableau suivant présente $expand avec $select exemples pour les types de propriétés de navigation courants :

Pour développer plusieurs propriétés de navigation dans une seule requête, utilisez une liste délimitée par des virgules :

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

Utiliser des déclarations de développement imbriquées

Pour développer une propriété de navigation au sein d'une entité déjà développée, imbriquez un $expand à l'intérieur d'un autre. La requête suivante développe Iteration, puis développe Project au sein de Iteration pour indiquer le projet auquel appartient l’itération :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Pour combiner l’extension imbriquée avec $select, utilisez un point-virgule (;) pour séparer $select de $expand à l’intérieur des parenthèses. Sans point-virgule, la requête retourne une erreur. La requête suivante retourne uniquement IterationName et IterationPath à partir de Iteration, plus l’imbrication Project:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Interroger une plage de dates

L’exemple de requête suivant retourne des éléments de travail dont la date de modification est supérieure ou égale au 1er janvier 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

L’exemple de requête suivant retourne des éléments de travail dont la dernière date modifiée s’est produite pendant la semaine du 31 octobre au 7 novembre 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Trier les résultats

Ajouter $orderby pour trier les résultats par une ou plusieurs propriétés. Les résultats trient par défaut dans l’ordre croissant ; ajout desc pour décroissant. Séparez plusieurs champs de tri avec des virgules.

Étape suivante

Contenu connexe

• Construire des requêtes OData pour Analytics
• Agréger des données à l’aide d’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
• OData v4.0 Partie 2 : Conventions d’URL plus Errata 02