Requêtes dans l’étendue du projet et de l’organisation

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

À l’aide d’Analytics pour Azure DevOps, vous pouvez construire des requêtes qui sont étendues à un projet ou à une organisation ou à une collection. Vous pouvez exécuter ces requêtes directement dans votre navigateur ou dans Power BI.

Les requêtes d’étendue de projet permettent de répondre à des questions sur un projet unique, tandis que les requêtes délimitées par l’organisation et les regroupements vous permettent de répondre à des questions qui dépassent les limites du projet. Les requêtes délimitées par l’organisation et le regroupement nécessitent des autorisations utilisateur plus larges ou des restrictions d’étendue minutieuses pour s’assurer que votre requête n’est pas bloquée en raison d’un manque d’autorisations.

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.

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.

Important

Si vous n’avez pas accès à tous les projets d’une organisation, il est recommandé d’appliquer un filtre de projet à toutes vos requêtes. Lorsque vous extrayez des données dans des outils clients tels que Power BI ou Excel, l’utilisation de la syntaxe du chemin du projet est la meilleure façon de vous assurer que toutes vos données sont limitées par le projet donné. Nous vous recommandons d’utiliser des requêtes délimitées à l’organisation ou de collection uniquement lorsque vous devez créer un rapport sur deux projets ou plus.

Requêtes délimitées à un projet

Vous construisez une requête en entrant l’URL OData dans un navigateur web pris en charge.

L’URL de base d’une requête OData au niveau du projet est comme indiqué dans la syntaxe suivante.

Cloud (Azure DevOps Services)

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

Dans les exemples fournis, remplacez et {ProjectName} remplacez {OrganizationName} vos noms de votre organisation et de votre projet que vous souhaitez interroger.

Local (Azure DevOps Server

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/

Dans les exemples fournis, effectuez les remplacements suivants :

• analytics.dev.azure.com avec {ServerName}:{Port}/tfs/
• {CollectionName} avec le nom de votre collection de projets (par défaut est DefaultCollection)
• {ProjectName} avec le nom du projet que vous souhaitez interroger.

Remarque

Les autres exemples fournis dans cet article sont basés sur une URL Azure DevOps Services. Vous devrez remplacer l’URL de votre serveur Azure DevOps pour obtenir les exemples.

Retourner un nombre d’éléments de travail

Par exemple, la requête délimitée par le projet suivante retourne le nombre d’éléments de travail pour un projet spécifique.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

Par exemple, une requête du projet Fabrikam Fiber retourne un nombre d’éléments de travail de 7126. Les éléments de travail supprimés ne sont pas inclus dans le nombre.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

Retourner des chemins d’accès à la zone de projet

De même, la chaîne de requête suivante retourne les zones d’un projet spécifique :

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

Il équivaut au filtre suivant sur une requête délimitée par l’organisation :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

Par exemple, une requête du projet Fabrikam Fiber retourne toutes les propriétés définies pour un chemin d’accès à la zone, car aucun opérateur n’est $select appliqué dans la requête.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

L’exemple suivant montre les données retournées pour un chemin d’accès à la zone unique.

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

Utilisation de l’option $expand

Lorsque vous utilisez une requête délimitée par un projet avec une $expand option, vous n’êtes pas obligé de fournir d’autres filtres.

Par exemple, le filtre dans l’étendue du projet suivant :

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

est filtré automatiquement pour appliquer la sécurité :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

Requêtes délimitées à l’organisation

L’URL de base pour les requêtes au niveau de l’organisation est comme indiqué :

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

Lorsque vous utilisez une requête délimitée par l’organisation avec une $expand option, vous devez fournir un autre filtre.

Par exemple, la requête d’étendue de l’organisation suivante, qui utilise un $expand pour récupérer les enfants de tous les éléments de travail.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

Il nécessite un autre filtre pour vérifier que les enfants sont limités au projet spécifié :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Retourner le parent de tous les éléments de travail

La requête suivante, qui utilise une $expand option pour récupérer le parent de tous les éléments de travail.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

Il nécessite un autre filtre pour vérifier que le parent est limité au projet spécifié :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

Sans l’autre filtre, la requête échoue si le parent d’un élément de travail fait référence à des éléments de travail dans un projet auquel vous n’avez pas accès en lecture.

Restrictions de sécurité au niveau du projet

Analytics a quelques restrictions supplémentaires sur la syntaxe de requête liée à la sécurité au niveau du projet.

Les any filtres ou all les filtres s’appliquent à l’entité de base sur un $expand. Pour les filtres basés sur un projet, nous ignorons explicitement le filtre lors de l’utilisation d’un $expand:

Par exemple, dans la requête qui suit :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Est interprété comme suit :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

et échouera si vous n’avez pas accès à tous les projets.

Pour contourner la restriction, vous devez ajouter une expression supplémentaire dans les $filteréléments suivants :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

L’utilisation $level est prise en charge uniquement si vous avez accès à tous les projets de la collection ou lors de l’utilisation d’une requête délimitée par un projet :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

Analytics ne prend pas en charge les références inter-niveaux pour les projets à l’aide de la $it clause. Par exemple, la requête suivante fait référence à l’alias de ProjectName $it l’élément de travail racine, qui n’est pas pris en charge :

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

Étape suivante

Interroger des données d’agrégation

Articles connexes

• Instructions relatives aux requêtes