Requêtes au niveau du projet et de l'organisation

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

À 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.

Prérequis

Requêtes à l'échelle d'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.

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

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

Renvoie un nombre d’éléments de travail

Par exemple, la requête suivante à l'échelle du projet 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 Fibre retourne un nombre de 7 126 éléments de travail. 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

Projet de retour Chemins de l'espace

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 portant sur le projet Fabrikam Fiber retourne l’ensemble des propriétés définies pour un « Area Path », puisqu’aucun opérateur $select n’est appliqué à 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 suivant à l'échelle du projet :

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 portées sur 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 suivante portant sur l'organisation, 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}')

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

La requête suivante, qui utilise une option $expand 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 ce filtre supplémentaire, la requête échoue si le parent d'un élément de travail fait référence à des éléments de travail d'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 filtres any ou all 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 échoue si vous n’avez pas accès à tous les projets.

Pour contourner la restriction, vous devez ajouter une expression supplémentaire dans le $filter.

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 croisées pour les projets utilisant la clause $it. Par exemple, la requête suivante fait référence à l’élément de travail racine ProjectName en utilisant l’alias $it, ce 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

Contenu connexe

• Instructions relatives aux requêtes