Champs, opérateurs et macros de requête

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

Conseil

C’est votre première requête ? Commencez par définir une requête pour des étapes procédurales ou une référence rapide de requête pour obtenir des exemples.

Utilisez ce guide de référence pour rechercher des types de données de champ, des opérateurs de requête, des macros et des variables lors de la génération de requêtes dans le Éditeur de requête. Tous les opérateurs et macros sont pris en charge dans Azure Boards ; certains s’appliquent uniquement aux versions spécifiques Azure DevOps Server.

Pour obtenir des exemples rapides et des tâches d’éditeur, consultez Référence rapide desrequêtes et Gérer et organiser les requêtes.

Prérequis

Catégorie Exigences
Appartenance au projet Vous devez être ajouté en tant que membre du projet.
Niveaux d’accès - Pour afficher et exécuter des requêtes partagées : vous devez être membre Project.
- Pour ajouter et enregistrer une requête partagée : vous devez disposer d’au moins un accès de base.
Permissions Vérifiez que l’autorisation Contribuer est définie sur Autoriser pour le dossier dans lequel vous souhaitez ajouter une requête. Votre organisation peut avoir besoin de configurer manuellement le groupe Contributeurs pour accorder cette autorisation.

Note

Vous avez besoin d’un niveau d’accès suffisant et de l’autorisation Contribuer pour enregistrer des requêtes partagées. L’accès de base n’est pas suffisant.

Catégorie Exigences
Appartenance au projet Vous devez être ajouté en tant que membre du projet.
Niveaux d’accès - Pour afficher et exécuter des requêtes partagées : vous devez être membre Project.
- Pour ajouter et enregistrer une requête partagée : vous devez disposer d’au moins un accès de base.
Permissions Vérifiez que l’autorisation Contribuer est définie sur Autoriser pour le dossier dans lequel vous souhaitez ajouter une requête. Votre organisation peut avoir besoin de configurer manuellement le groupe Contributeurs pour accorder cette autorisation.

Note

Vous avez besoin d’un niveau d’accès suffisant et de l’autorisation Contribuer pour enregistrer des requêtes partagées. L’accès de base n’est pas suffisant.

Types de données et valeurs de champ de requête

Spécifiez une valeur qui correspond au type de données d’un champ. Le tableau suivant répertorie les types de données pris en charge :

Note

Pour Azure Boards (cloud), le type de données correspond au champ affiché dans la page Process > Champs. Pour les déploiements locaux, le type de données correspond à l’attribut d’une typeFIELD définition. Pour plus d’informations, consultez les champs d’élément de travail et les attributs de champ .

Type de données Description
Booléen Stocke une valeur True/False.
DateHeure ou Date/Heure Utilisez une variable de date (par exemple, @Today ou @Today-1) ou une date explicite comme 01/01/2025. Entrez des dates dans le modèle défini dans votre profil. Pour obtenir des exemples de requête, consultez Query by date or @CurrentIteration. Pour les requêtes WIQL, vous pouvez également spécifier des dates au format UTC. Consultez la syntaxe du langage de requête d’élément de travail (WIQL).
Double ou décimal Stocke un nombre réel, tel que 0.2 ou 3.5. Pour obtenir des exemples, consultez Requête par champs numériques .
GUID Stocke une chaîne d’identificateur unique.
Historique Champ mis en forme personnalisé utilisé pour les informations historiques (champ Historique ). Lorsque la recherche en texte intégral est disponible, ce champ est indexé pour les requêtes de recherche en texte intégral. Consultez l’historique et l’audit.
HTML Stocke le texte mis en forme, tel que Description ou Étapes de reproduction. Lorsque la recherche en texte intégral est disponible, ces champs sont indexés. Pour interroger des champs de texte enrichi, consultez Interroger par titre, ID et champs de texte enrichi.
Identité Stocke une chaîne de texte courte qui identifie une identité utilisateur.
Integer Stocke un entier 32 bits signé, tel que 0, 1, 2 ou 34.
Champ Texte brut ou Texte (plusieurs lignes) Stocke les valeurs de texte longues, telles que les informations de démarrage de l’application. Ces champs indexent la recherche en texte intégral lorsqu’ils sont pris en charge. Consultez Requête par titres, ID et champs de texte enrichi.
picklistDouble Champ personnalisé qui contient une liste de sélection de valeurs décimales.
picklistInteger Champ personnalisé qui contient une liste de choix de valeurs entières.
liste de sélection Champ personnalisé qui contient une liste de sélection de valeurs de texte court (255 caractères ou moins).
Champ Chaîne ou Texte (une seule ligne) Stocke le texte court jusqu’à 255 caractères Unicode. Les équipes utilisent souvent ces champs pour les listes de sélection ou les menus déroulants.
TreePath Représente une structure arborescente, comme le chemin de zone ou le chemin d’itération. Choisissez une valeur de nœud valide. Vous pouvez filtrer selon les critères d’égalité, d’inégalité, « Inférieur à » ou « Non inférieur à ». Utilisez les opérateurs In et Not In pour spécifier plusieurs valeurs. Définissez des structures d’arborescence pour un projet ( chemins d’accès de zone et chemins d’itération ) et sélectionnez les nœuds à associer à des équipes. Pour obtenir des exemples de requête, consultez Requête par zone ou chemin d’itération et Requête par date ou itération actuelle.

Note

Les picklist... types s’appliquent uniquement aux champs personnalisés définis pour un processus hérité.

Modèle de date et d’heure

Le modèle de date et d’heure que vous entrez pour les champs DateTime doit correspondre à celui que vous sélectionnez dans votre profil. Pour afficher ou modifier votre sélection, consultez Définir les préférences utilisateur.

Capture d’écran montrant les options de liste déroulante Modèle de date dans le volet Heure et paramètres régionaux. Capture d’écran montrant les options de liste déroulante Modèle d’heure dans le volet Heure et paramètres régionaux.

Capture d’écran montrant le volet Heure et paramètres régionaux avec les champs Modèle de date et Modèle d’heure.

Opérateurs de requête

Utilisez des opérateurs pour définir la façon dont une valeur de clause doit être liée à la valeur de champ d’un élément de travail. Pour les types de données de champ, consultez référence de champ Élément de travail. Pour obtenir de l’aide sur la création de requêtes, consultez Définir une requête.

Opérateur de requête Lorsque l’opérateur retourne des éléments de travail correspondants Types de données applicables
= Correspond à la valeur de la clause. Number (Double/Decimal/GUID/Integer), String, DateTime, TreePath
<> Ne correspond pas à la valeur de la clause. Number, String, DateTime, TreePath
> Est supérieur à la valeur de la clause. Nombre, String, DateTime
< Est inférieur à la valeur de clause. Nombre, String, DateTime
>= Est supérieur ou égal à la valeur de la clause. Nombre, String, DateTime
<= Est inférieur ou égal à la valeur de la clause. Nombre, String, DateTime
=[Field] Correspond à la valeur d’un autre champ spécifié (doit être le même type de données). Nom d’un champ du même type de données (les champs booléens comparent l’égalité à d’autres champs).
<>[Champ] Ne correspond pas à la valeur dans un autre champ spécifié. Nom d’un champ du même type de données.
>[Champ] Est supérieur à la valeur d’un autre champ spécifié. Nom d’un champ du même type de données.
<[Champ] Est inférieur à la valeur d’un autre champ spécifié. Nom d’un champ du même type de données.
>=[Champ] Est supérieur ou égal à la valeur dans un autre champ spécifié. Nom d’un champ du même type de données.
<=[Champ] Est inférieur ou égal à la valeur dans un autre champ spécifié. Nom d’un champ du même type de données.
Contient Contient une correspondance de texte exacte ou partielle. Chaîne
Ne contient pas Ne contient pas de correspondance textuelle exacte ou partielle. Chaîne
Contient les mots Correspond à une expression ou à des mots exacts (prend en charge un caractère générique * en bout de chaîne). Limite : 100 caractères. Cet opérateur utilise l’indexation de texte intégral ; Consultez la section Texte intégral de cet article pour connaître les exigences de serveur et de classement. Champs de texte long indexés pour la recherche en texte intégral (PlainText, HTML, Historique et Titre).
Ne contient pas les mots Exclut les éléments qui contiennent l’expression ou les mots spécifiés. Limite : 100 caractères. Utilisez Contains Words dans les clauses associées pour inclure ou exclure des mots clés. Champs de texte indexés pour la recherche en texte intégral.
Dans Correspond à n'importe quelle valeur d'un ensemble délimité (utilisez le séparateur de liste régional de votre système d'exploitation, généralement une virgule). Number, String, DateTime, TreePath
Est vide Correspond aux éléments où un champ HTML ne contient aucun contenu (aucune valeur spécifiée). Pris en charge par Azure Boards et Azure DevOps Server. HTML
N’est pas vide Correspond aux éléments où un champ HTML contient du contenu. Pris en charge par Azure Boards et Azure DevOps Server. HTML
Pas dans Exclut les valeurs d’un jeu délimité (utilisez le séparateur de liste régional). Pris en charge par Azure Boards et Azure DevOps Server. Number, String, DateTime, TreePath
Dans le groupe Correspond aux valeurs membres d’un groupe nommé (équipe, groupe de sécurité ou catégorie). Par exemple, utilisez le groupe Contributeurs ou un groupe d’équipe nommé dans le modèle [Project Name]\Team Name. Consultez Requête par affectation ou modifications de flux de travail pour obtenir des exemples. Utilisez En groupe uniquement avec les champs de type chaîne ou le type d’élément de travail. Vous pouvez utiliser des groupes Microsoft Entra ID lorsque votre compte utilise des Microsoft Entra ID ou des groupes Active Directory en local. Chaîne (correspond au nom du groupe ou de l’équipe) ou au type d’élément de travail
N’est pas dans le groupe Exclut les membres d’un groupe nommé. Chaîne qui correspond à une catégorie de groupe d’utilisateurs ou de projet.
Pas sous Exclut les éléments égaux ou contenus sous le nœud d’arborescence spécifié. TreePath
Sous Correspond aux éléments égaux ou contenus sous le nœud d’arborescence spécifié. TreePath
Toujours Correspond à une valeur qu’un champ a connue à un moment précédent. (Éditeur de requête : champs de chaîne uniquement. La prise en charge de DateTime nécessite des requêtes WIQL directes.) String (Chaîne), DateTime (Date et heure)

Conseil

Vous pouvez construire des requêtes WIQL qui utilisent des opérateurs (par exemple Was Ever) sur d’autres types de données tels que le chemin d’itération. Consultez Liste des éléments de travail déplacés d'un sprint pour obtenir un exemple.

Exemples d’opérateurs courants

Voici des exemples de requêtes représentatifs qui utilisent différents opérateurs :

Query Returns
State = Active Éléments de travail avec l’état « Actif »
Priority <> Low Tous les éléments à l’exception de ceux dont la priorité est faible
Created Date >= @Today-7 Éléments de travail créés au cours des 7 derniers jours
Assigned To = @Me Éléments affectés à l’utilisateur actuel
Tags Contains "frontend" Éléments avec une balise contenant « frontend »
State In (Active, In Progress) Éléments dans l’un ou l’autre état
Area Path Under "Project\Web" Tous les éléments sous la zone Web, y compris les sous-zones
Assigned To In Group "[Project]\Developers" Éléments attribués à tout le monde dans le groupe Développeurs
Description Contains Words "urgent" Éléments dans lesquels la description contient le mot « urgent »

Recherches de texte intégral et de mots partiels

Utilisez Contains or Does Not Contains pour rechercher des correspondances exactes ou partielles sur des champs de texte long. Ces opérateurs utilisent l’index de requête. Utilisez Contient des mots ou ne contient pas de mots pour rechercher des expressions exactes ou utiliser un caractère générique de fin (*). Ces opérateurs nécessitent l’index de recherche en texte intégral.

Vous ne pouvez utiliser le caractère générique qu’à la fin d’un mot ou d’une expression partielle. Pour obtenir des exemples, consultez Exemple de requêtes d’élément de travail et Exécuter une requête d’éléments de travail à l’aide du champ Historique.

Note

Tous les déploiements ne prennent pas en charge la recherche en texte intégral. Par exemple, SQL Express et certaines configurations SQL cloud ne prennent pas en charge la recherche en texte intégral. Dans ces déploiements, seuls les opérateurs Contains et Ne contient pas sont visibles.

Azure DevOps Server indexe les champs de texte long (PlainText et HTML) et le champ Titre pour la recherche en texte intégral lorsque le SQL Server sous-jacent prend en charge l’indexation de texte intégral.

La recherche en texte intégral nécessite également un classement SQL avec un analyseur de mots inscrit pour la langue que vous utilisez. Si le classement de base de données de collection ne correspond pas à un langage pris en charge, les résultats peuvent ne pas correspondre aux attentes. Dans ces cas, utilisez Contient ou Ne contient pas à la place.

Pour plus d’informations, voir Requêtes de recherche en texte intégral et paramètres de classement.

Combinaison d’opérateurs

Les requêtes utilisent la logique AND pour combiner plusieurs clauses. Chaque clause supplémentaire filtre les résultats plus loin. Par exemple:

  • State = Active AND Priority = High retourne les éléments de travail qui sont tous deux actifs ET ont une priorité élevée.
  • State = Active AND State <> Closed retourne des éléments actifs à l’exclusion de ceux marqués comme fermés.
  • Assigned To = @Me AND State <> Done renvoie les éléments qui vous sont attribués et qui ne sont pas terminés.

Vous pouvez utiliser des parenthèses pour regrouper des conditions pour les requêtes complexes dans la syntaxe WIQL directe :

  • (State = Active OR State = In Progress) AND Priority = High retourne des éléments à priorité élevée dans les états actifs ou en cours.

Pour plus d’exemples et des détails de syntaxe WIQL, consultez Syntaxe pour le langage de requête d’élément de travail (WIQL).

Résolution des problèmes et erreurs courantes

Problème Cause probable Solution
La macro ne retourne aucun résultat @CurrentIteration fonctionne uniquement dans le portail web ; Les API REST et l’interface CLI peuvent retourner des résultats vides Utilisez plutôt des dates directes dans des scripts ou des API. Pour obtenir des alternatives, consultez Requête par date ou itération actuelle.
@TeamAreas requête retourne des résultats inattendus La macro fonctionne uniquement avec le champ Chemin d’accès à la zone ; l’utiliser avec d’autres champs n’a aucun effet Vérifiez que vous filtrez sur le Chemin d’accès à la zone. Utilisez d’autres champs de chemin d’arborescence (chemin d’itération) avec l’opérateur Sous à la place.
Erreur de l’opérateur « Contient des mots » La requête dépasse la limite de 100 caractères ou utilise un positionnement générique non valide Réduisez le texte de la requête à moins de 100 caractères. Utilisez un caractère générique uniquement à la fin du terme (par exemple, feature*), pas au début.
La requête In Group a échoué Le format du nom du groupe est incorrect ou le groupe n’existe pas Utilisez le format exact : Assigned To In Group "[Project]\\Team Name" pour les équipes. Vérifiez le nom du groupe dans les paramètres du projet.
« A déjà été opérateur » ne fonctionne pas avec des dates L'Éditeur de requête ne prend pas en charge Was Ever sur les champs DateTime Utilisez la syntaxe WIQL directe au lieu de l’éditeur de requête visuelle. Si vous souhaitez obtenir plus d’informations, consultez Syntaxe du langage WIQL.
La requête de champ booléen ne retourne aucun résultat La valeur est sensible à la casse dans les requêtes WIQL Utilisez le cas exact : CustomBoolField = True ou CustomBoolField = False (capital T/F dans WIQL).

Interroger des macros et des variables

Utilisez les macros suivantes pour filtrer dynamiquement les requêtes.

Note

Les macros suivantes sont uniquement prises en charge à partir du portail web : @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity et @TeamAreas. Les requêtes qui contiennent ces macros ne fonctionnent pas lorsqu'elles sont ouvertes dans Visual Studio/Team Explorer, Microsoft Excel ou Microsoft Project.

Macro Description
[N’importe lequel/laquelle] Utiliser avec le type d’élément de travail ou l’état pour effectuer une recherche dans tous les types ou états. Par exemple, Work Item Type=[Any] supprime le filtrage basé sur le type.
@Itérationactuelle Utilisez le chemin d’itération pour filtrer les éléments de travail dans le sprint actuel en fonction du contexte d’équipe actuel. Consultez Requête par date ou itération actuelle pour obtenir des exemples. @CurrentIteration fonctionne uniquement lors de l’exécution à partir du portail web (pas dans les API REST ni dans certaines opérations de copie/clone).
@CurrentIteration +/- n Utiliser avec le chemin d’itération pour inclure des sprints par rapport à l’itération actuelle (par exemple, @CurrentIteration-1 ou @CurrentIteration+2). Pris en charge dans le portail web pour Azure Boards et Azure DevOps Server.
@Abonnés Utilisez l’ID et l’opérateur In pour répertorier les éléments de travail que vous suivez dans le projet. Référez-vous à Suivre un élément de travail ou une pull request. Cette macro fonctionne uniquement à partir du portail web.
@Moi Utilisez les champs d’identité pour filtrer les éléments liés à votre compte (par exemple). Created By=@Me Consultez la section Requête par assignation, workflow ou changements de tableau.
@MonActivitéRécente Utilisez avec ID et In pour lister les éléments de travail que vous avez consultés ou mis à jour ces derniers ~30 jours. Consultez l'onglet Mon activité sur la page Éléments de travail pour obtenir la même liste.
@Projet Utiliser avec Team Project pour filtrer les éléments de travail dans le projet actuel (par exemple, Team Project=@Project). Consultez Requête entre les projets.
@MentionsRécentes Utilisez avec l’ID et In pour répertorier les éléments de travail dans lesquels vous êtes mentionné dans les discussions. Consultez l'onglet Mentionné de la page Éléments de travail.
@ActivitéRécenteDuProjet Utilisez l’ID et In pour répertorier les éléments de travail récemment mis à jour dans le projet. La macro retourne jusqu’à 5 000 éléments ; la fenêtre réelle dépend de l’activité du projet.
@DébutDeLaJournée Utiliser avec les champs DateTime pour filtrer par rapport à aujourd’hui (par exemple, Closed Date>=@StartOfDay-7).
@DébutDuMois Utiliser avec les champs DateTime pour filtrer par rapport au début du mois (par exemple, Created Date>=@StartOfMonth-3).
@DébutDeLaSemaine Utiliser avec les champs DateTime pour filtrer par rapport au début de la semaine (par exemple, Changed Date>=@StartOfWeek-2).
@DébutDeL’année Utilisez les champs DateTime pour filtrer par rapport au début de l’année (par exemple). Target Date>=@StartOfYear
@ZonesÉquipes Utilisez uniquement avec Area Path et l’opérateur = pour rechercher les éléments affectés aux chemins d’accès de zone d’une équipe (par exemple). Area Path=@TeamAreas [Fabrikam Fiber]\Web Pris en charge dans le portail web pour Azure Boards et Azure DevOps Server.
@Aujourd’hui Utiliser avec les champs DateTime pour filtrer par rapport à aujourd’hui (par exemple, Created Date>=@Today-7). Consultez Requête par date ou itération actuelle.

Exemples de macros courantes

Voici des exemples de requêtes représentatifs qui utilisent des macros pour rendre les requêtes dynamiques :

Query Retours (portail web)
Iteration Path = @CurrentIteration Éléments de travail dans le sprint actuel
Iteration Path = @CurrentIteration-1 Éléments de travail dans le sprint précédent
Assigned To = @Me Éléments affectés à l’utilisateur actuel
Created Date >= @Today-30 Éléments créés au cours des 30 derniers jours
State = Active AND Area Path = @TeamAreas [Project]\MyTeam Éléments actifs dans la zone de votre équipe
Work Item Type = [Any] Tous les types d’éléments de travail (supprime le filtrage de type)
Assigned To In Group @Follows Éléments attribués aux personnes que vous suivez

Note

Les macros telles que @CurrentIteration, @Me, @Followset @TeamAreas fonctionnent uniquement dans le portail web. Pour les API REST, l’interface CLI et Power BI, utilisez plutôt des dates directes et des ID utilisateur. Pour obtenir des alternatives, consultez Requête par date ou itération actuelle.

Contenu connexe

API REST

Pour interagir par programmation avec des requêtes, consultez l’une de ces ressources d’API REST :

  • Last updated on