Construire des requêtes OData pour Analytics dans Azure DevOps

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

L’analytique, la plateforme de création de rapports 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. Vous pouvez en savoir plus sur le modèle de données et le processus de requête en exécutant des requêtes simples à partir de votre navigateur web.

Cet article explique comment :

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.

Prérequis

Interroger les métadonnées

Analytics expose le modèle d’entité OData à l’URL de métadonnées formée en ajoutant $metadata à l’URL racine du service. Analytics fournit des racines de service pour des projets Azure DevOps ou des collections entières.

Vous pouvez interroger les métadonnées pour rechercher l’un des éléments de données suivants :

• 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
• Ensembles d’entités
• conteneurs
• Fonctions de filtre, avec Org.OData.Capabilities.V1.FilterFunctions
• Agrégations prises en charge, avec Org.OData.Aggregation.V1.ApplySupported
• Type de prise en charge par lots, avec Org.OData.Capabilities.V1.BatchSupportType

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata 

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata  

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata 

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 pour votre entité d’intérêt.

Les métadonnées d’analyse définissent les schémas principaux suivants.

• Microsoft.VisualStudio.Services.Analytics.Model définit les types d’entités et les types énumérés et leurs membres.
• Le Default schéma définit les conteneurs d’entités, les jeux d’entités, ainsi que les fonctions OData prises en charge, la transformation et les fonctions d’agrégation personnalisées.

<?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>

Pour plus d’informations, consultez métadonnées OData Analytics.

Obtenir les entités associées et les propriétés de navigation

Tous les types d’entités ont des propriétés et des propriétés de navigation que vous pouvez utiliser pour filtrer vos requêtes. Ces propriétés sont répertoriées dans les métadonnées sous Property ou NavigationProperty sous chacune d’elles EntityType. Vous pouvez utiliser des entités associées pour spécifier d’autres filtres, tels que des chemins d’itération, des chemins d’accès de zone ou des équipes.

L’extrait de code suivant montre une vue partielle des métadonnées de l’entité WorkItem . Les propriétés correspondent aux champs d’élément de travail et aux 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 et aux données Analytics spécifiques capturées pour le type d’entité, telles que Revisions, Links, Children 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"/>
...

Pour obtenir des informations sur la propriété et les relations des métadonnées d’entité, consultez les articles suivants :

• Date du calendrier, référence des métadonnées du projet et de l’utilisateur
• Informations de référence sur les métadonnées pour Azure Boards
• Informations de référence sur les métadonnées pour Azure Pipelines
• Informations de référence sur les métadonnées pour les plans de test

Jeux d'entités à interroger

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.

Utilisez la syntaxe d’URL suivante pour interroger un élément spécifique EntitySet, tel que WorkItems, WorkItemSnapshotou PipelineRuns. Remplacez <EntitySet> par l’entité que vous souhaitez rechercher et <QueryOptions> par les options de requête, comme décrit dans Utiliser les options de requête.

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

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

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

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

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 de l’entité définie à la requête. Pour obtenir la liste complète des jeux d’entités, consultez Le modèle de données pour Analytics.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

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

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

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

Utiliser les options de requête

Les options de requête sont des paramètres de chaîne de requête qui permettent de contrôler la quantité de données retournées pour une ressource. Spécifiez les options de requête dans l’ordre indiqué dans le tableau suivant.

Comprendre la pagination côté serveur

L’analytique force la pagination lorsque les résultats de la requête dépassent 10 000 enregistrements. Dans ce cas, vous obtenez la première page de données et un lien à suivre pour obtenir la page suivante. Les outils clients tels que Power BI Desktop ou Excel suivent automatiquement @odata.nextLink et chargent tous les enregistrements requis quand on extrait des données.

Vous trouverez le @odata.nextLink lien à la fin de la sortie JSON. Le lien ressemble à la requête d’origine suivie par $skip ou $skiptoken. Par exemple :

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

Étape suivante

Contenu connexe

• Qu’est-ce que Analytics ?
• Instructions relatives aux requêtes OData Analytics
• Autorisations et conditions préalables pour accéder à Analytics dans Azure DevOps