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

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

Vous pouvez utiliser Analytics pour Azure DevOps pour construire des requêtes OData pour retourner des données qui vous intéressent. Vous pouvez exécuter ces requêtes dans votre navigateur ou dans des logiciels clients comme Excel ou Power BI.

Cet article se concentre sur les requêtes permettant de récupérer des jeux d’entités de suivi de travail Azure Boards, mais les principes s’appliquent à l’interrogation d’autres jeux 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.

Ce tutoriel vous montre comment :

Prérequis

Obtenir un nombre d’éléments

Pour renvoyer uniquement un nombre d’éléments ou d’entités définis dans une organisation ou un projet sans inclure d’autres informations, appliquez l’option $apply=aggregate($count as Count) de requête. 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’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)

Les requêtes précédentes retournent des résultats comme l’exemple suivant pour les projets de l’organisation fabrikam :

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

Obtenir le nombre d’éléments et leurs 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 dans une select instruction. 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 des 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.

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

Par exemple, la requête suivante demande le nombre et les noms d’utilisateur des utilisateurs dans le projet Fabrikam Fibre :

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

La requête retourne un nombre d’utilisateurs 5 avec leurs noms d’utilisateur.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@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

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 $select=WorkItemId,WorkItemType,Title,State clause à votre requête.

La $select clause spécifie les noms de propriétés qui correspondent aux champs nommés. Les noms de propriétés dans les requêtes OData nécessitent une attention particulière à l’espacement et à la casse. Bien que les noms d’affichage de propriété tels que l’ID d’élément de travail puissent contenir des espaces, les noms de propriétés formels ne peuvent pas contenir d’espaces.

Pour plus d’informations sur les noms de propriétés et les étiquettes, consultez la référence des métadonnées pour Azure Boards. Pour comprendre comment les propriétés de champ personnalisées sont étiquetées, consultez Propriétés personnalisées.

L’exemple de requête suivant demande les ID d’élément de travail, les titres et les états 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

Analytics retourne les données suivantes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "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

Pour filtrer un jeu d’entités pour retourner des éléments spécifiques, ajoutez une $filter clause qui spécifie les critères que les éléments doivent respecter. La clause de filtre suivante retourne uniquement les types d’éléments de travail Feature qui sont dans l’état En cours.

/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

L’exemple de requête suivant spécifie de renvoyer l’ID de l’élément de travail, le type d’élément de travail, le titre et l’état uniquement des éléments de travail de fonctionnalité qui sont dans l’état 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'

Spécifier plusieurs clauses de filtre

Vous pouvez utiliser and et or spécifier plusieurs filtres dans une seule $select clause. Par exemple, la requête suivante spécifie plusieurs champs à partir d’éléments de travail de types User Story, Bug ou Custom type Backlog Work qui se trouvent dans les états Nouveau, Validé ou Actif . Utilisez des parenthèses pour regrouper les clauses de filtre en fonction des besoins.

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')

La requête retourne des données comme les résultats suivants :

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

Vous pouvez également appliquer différentes fonctions telles que contains, startswithet endswith dans $select des clauses. Consultez les fonctions prises en charge.

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

Pour rechercher les propriétés AreaSK, IterationSK ou d’autres d’un chemin d’accès de zone spécifique ou d’un chemin d’itération, utilisez les requêtes ci-dessous.

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

La requête suivante demande la propriété AreaSK définie pour le chemin de la zone Fabrikam Fiber\Production Planning\Web. Pour afficher d’autres propriétés définies pour l’ensemble d’entités Areas , 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

La requête retourne les données suivantes.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

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

La requête suivante retourne la IterationSK propriété définie pour le chemin d’itération Fabrikam Fiber\3Week Sprints\Sprint 3 . Pour afficher d’autres propriétés définies pour l’ensemble d’entités Itérations , 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 représentent des relations entre les types d’entités. Lorsque vous spécifiez une propriété de navigation dans le cadre de vos critères de filtre, vous devez spécifier le chemin complet de la propriété de navigation. Par exemple, la clause suivante filtre les éléments de travail en fonction d’un chemin d’itération spécifié pour la propriété de Iteration navigation.

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

Iteration est la propriété de navigation et IterationPath est le champ d’intérêt. Iteration/IterationPath est le chemin complet de la IterationPath propriété.

L’exemple de requête suivant demande des données des cinq premiers éléments de travail dans le chemin d'itération Fabrikam Fiber\3Week Sprints\Sprint 3 en spécifiant le chemin d’accès complet pour Iteration/IterationPath.

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

L’exemple de requête précédent ne retourne Iteration pas de données, car Iteration il s’agit d’une entité associée. Les propriétés de navigation telles que Identity, Areaet Iteration ne sont pas directement accessibles à l’aide $select d’instructions. Vous devez utiliser les instructions $expand pour retourner des données provenant d'entités connexes.

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

L’exemple de requête suivant demande des informations associées à l’ID 480 d’élément de travail, y compris les données étendues 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

La requête retourne les données suivantes, qui incluent tous les champs de la propriété développée Iteration .

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,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",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "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",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

Utiliser la clause select dans les instructions expand

Si une propriété développée retourne plus de données que vous ne le souhaitez, ajoutez une instruction pour la propriété $select.

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

Par exemple, l’exemple de requête suivant sélectionne uniquement les données IterationName et les données IterationPath de la propriété Iteration développée.

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)

La requête 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,Iteration(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 montre comment utiliser $expand et $select clauses pour sélectionner plusieurs champs dans les propriétés de navigation. Par exemple, vous utilisez $expand=AssignedTo($select=UserName) pour renvoyer la propriété Attribué à du champ Nom d’utilisateur dans la propriété de navigation Identity.

Vous pouvez spécifier plusieurs propriétés à développer dans une clause unique $expand à l’aide d’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

Vous pouvez utiliser des instructions OData $expand imbriquées. Par exemple, la requête suivante utilise des instructions imbriquées $expand pour afficher le projet dans lequel se trouve une 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)

La requête 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,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",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "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",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Vous pouvez ajouter $select des déclarations, par exemple pour renvoyer uniquement les IterationName et IterationPath à partir de 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($select=IterationName,IterationPath;$expand=Project)

Cette requête 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,Iteration(IterationName,IterationPath,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": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Les résultats montrent uniquement IterationName et IterationPath depuis Iteration, et Project en tant qu’objet imbriqué dans les résultats de Iteration.

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&ChangedDate le 2025-11-07Z

Trier les résultats

Spécifiez l’option $orderby pour trier vos résultats ou spécifiez la séquence dans laquelle retourner les résultats. Vous pouvez trier dans l’ordre croissant ou décroissant à l’aide de mots clés asc ou desc. Le tableau suivant montre quelques exemples.

Étape suivante

Contenu connexe

• 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