Construire des requêtes OData pour Analytics dans Azure DevOps

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

Analytics expose les données de projet Azure DevOps via un point de terminaison OData que vous pouvez interroger à partir de n’importe quel navigateur web ou outil client pris en charge . Ce tutoriel vous guide tout au long de la structure d’URL de requête ( métadonnées, jeux d’entités et options de requête) pour commencer à générer vos propres requêtes. Pour obtenir une comparaison des outils de requête, consultez Outils de requête Analytics.

Dans ce tutoriel, vous allez apprendre à :

Prérequis

Interroger les métadonnées

Pour récupérer le modèle d’entité OData, ajoutez $metadata l’URL racine du service Analytics. Les métadonnées décrivent les éléments de données que vous pouvez utiliser dans les requêtes, notamment :

• Types d’entités, jeux d’entités et conteneurs
• Propriétés et propriétés de navigation
• Clés de substitution et listes énumérées
• Fonctions de filtre prises en charge (Org.OData.Capabilities.V1.FilterFunctions)
• Agrégations prises en charge (Org.OData.Aggregation.V1.ApplySupported)
• Type de support Batch (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/DefaultCollection/_odata/v4.0-preview/$metadata  

Interpréter la réponse aux métadonnées

Le point de terminaison de métadonnées retourne un document XML qui contient deux schémas principaux :

• Microsoft.VisualStudio.Services.Analytics.Model — définit les types d’entités, les types énumérés et leurs membres.
• Default : définit des conteneurs d’entités, des jeux d’entités et des fonctions de filtre, de transformation et d’agrégation OData prises en charge.

L’exemple suivant montre la structure de haut niveau :

<?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 les métadonnées OData Analytics.

Propriétés générales et propriétés de navigation

Les métadonnées de chaque type d’entité répertorient deux types de membres que vous pouvez utiliser dans les requêtes :

• Propriétés (Property) : correspond aux champs d’élément de travail et aux données spécifiques à Analytics, telles que LeadTimeDays et CycleTimeDays. Utilisez les propriétés dans $select, $filter et $orderby clauses.
• Propriétés de navigation (NavigationProperty) : lien vers des jeux d’entités connexes tels que Revisions, , LinksChildren, Parent, et .Teams Utilisez les propriétés de navigation pour filtrer par des entités associées telles que des chemins d’itération, des chemins de zone ou des équipes, et dans les clauses $expand.

L’extrait de code suivant montre une vue partielle des métadonnées d’entité WorkItem :

<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="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>
...
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<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="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
   <ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
</NavigationProperty>
...

Pour obtenir des détails complets sur les propriétés et les relations pour chaque zone de service, consultez :

• Date du calendrier, référence des métadonnées du projet et de l’utilisateur.
• Référence des 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 générer des rapports, interrogez un jeu d’entités tel que WorkItems, WorkItemSnapshotou PipelineRuns. Pour obtenir la liste complète des entités prises en charge, consultez les métadonnées OData Analytics.

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 : répertorier des projets avec $select

L’exemple suivant utilise $select pour renvoyer uniquement la ProjectName propriété du jeu d’entités Projects . 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

Ajoutez des options de requête à l’URL pour mettre en forme la réponse. Spécifiez-les dans l’ordre indiqué ici.

Comprendre la pagination côté serveur

Lorsqu’une requête retourne plus de 10 000 enregistrements, Analytics pages automatiquement les résultats. La réponse inclut une @odata.nextLink URL qui pointe vers la page suivante. Les outils clients tels que Power BI Desktop et Excel suivent automatiquement ces liens.

L’exemple suivant montre une réponse paginée :

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

Si vous interrogez depuis le code, suivez chaque @odata.nextLink jusqu'à ce que la réponse n'en contienne plus un.

É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