Partager via


Référence syntaxique du langage WIQL

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

Vous pouvez utiliser la syntaxe WIQL pour définir une requête en tant que lien hypertexte ou lors de l’utilisation de l’API REST (Work Item Query Language).

WIQL prend en charge toutes les fonctions disponibles via l’Éditeur de requête du portail web et quelques autres. Vous pouvez spécifier les champs à renvoyer et à regrouper logiquement des clauses de requête. Vous pouvez également utiliser une ASOF clause pour filtrer en fonction des affectations à partir d’une date précédente.

Important

La syntaxe WIQL est utilisée pour exécuter l’API REST Query By Wiql. L’API retourne uniquement les ID d’élément de travail, quels que soient les champs que vous incluez dans l’instruction SELECT . Pour obtenir des informations complètes, (1) obtenez les ID de WIQL, puis (2) obtenez les éléments de travail via Obtenir une liste d’éléments de travail par ID et pour des champs spécifiques.

Prérequis

Catégorie Exigences
autorisations Afficher les éléments de travail ou Afficher les éléments de travail dans ce nœud autorisation définie sur Autoriser. Ces autorisations sont généralement accordées aux membres des groupes Lecteurs et Contributeurs pour chaque projet d’équipe. Pour plus d’informations, consultez Autorisations et groupes.

Vue d’ensemble du langage de requête

WIQL comporte cinq parties, comme indiqué dans l’extrait de syntaxe suivant et décrit dans le tableau. La syntaxe WIQL ne respecte pas la casse.

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2025'

Conseil

En installant l’extension De la Place de marché de l’éditeur Wiql, vous pouvez construire des requêtes à l’aide de l’éditeur de requête et afficher la syntaxe WIQL. Vous pouvez ensuite copier et modifier la syntaxe WIQL et exécuter la requête à l’aide du hub Wiql Playground ajouté à Boards.

Clause Exemple/description
SELECT Identifie les champs à retourner pour chaque élément de travail. Vous pouvez spécifier le nom convivial ou le nom de référence. Utilisez des crochets ([]) si le nom contient des espaces ou des points.
FROM Indique si vous souhaitez que la requête recherche des éléments de travail ou des liens entre des éléments de travail.
- Permet FROM WorkItems de retourner des éléments de travail.
- Permet FROM workItemLinks de retourner des liens entre les éléments de travail. Pour plus d’informations, consultez Requêtes pour obtenir des liens entre les éléments de travail.
WHERE Spécifie les critères de filtre de la requête. Pour plus d’informations, consultez les conditions de filtre (WHERE).
ORDER BY Spécifie l’ordre de tri des éléments de travail retournés. Vous pouvez spécifier Croissant (Asc) ou Décroissant (Desc) pour un ou plusieurs champs. Par exemple : ORDER BY [State] Asc, [Changed Date] Desc
ASOF Spécifie une requête historique en indiquant une date pour laquelle le filtre doit être appliqué. Par exemple, cette requête retourne tous les récits utilisateur définis comme actifs le 11 février 2025. Spécifiez la date en fonction des instructions fournies dans Modèle de date et d’heure.
ASOF '02-11-2025'

Notes

Les requêtes WIQL effectuées sur Azure Boards ne doivent pas dépasser 32 K caractères. Le système ne vous permet pas de créer ou d’exécuter des requêtes qui dépassent cette longueur.

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.

Guillemets (guillemets simples ou doubles sont pris en charge) DateTime littéraux utilisés dans les comparaisons. Ils doivent être au format .NET DateTime de l’ordinateur client local exécutant la requête. Sauf si un fuseau horaire est spécifié, DateTime les littéraux se trouvent dans le fuseau horaire de l’ordinateur local.

WHERE 
   AND [System.ChangedDate] >= '01-18-2025 GMT'
   AND ([Closed Date] < '01-09-2025 GMT'
   OR [Resolved Date] >= '01-18-2025 14:30:01')  

Lorsque l’heure est omise dans un DateTime littéral et que le dayPrecision paramètre est égal à false, l’heure est supposée être égale à zéro (minuit). Le paramètre par défaut du dayPrecision paramètre est false.

Vous pouvez également spécifier le format ISO 8601, qui est valide quel que soit les paramètres régionaux. ISO 8601 représente la date et l’heure en commençant par l’année, suivie du mois, du jour, de l’heure, des minutes, des secondes et des millisecondes. Par exemple, 2025-12-10 15:00:00.000 représente le 10 décembre 2025 à 13 h à l’heure locale. Voici un exemple d’utilisation du format ISO 8601 :

WHERE 
   AND [System.ChangedDate] >= '2025-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2025-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2025-01-18T00:00:00.0000000')  

Champs personnalisés

Vous pouvez ajouter un champ personnalisé à une clause de requête. Avec WIQL, vous devez spécifier le nom de référence pour le champ personnalisé. Pour les projets qui utilisent un modèle de processus hérité, les champs personnalisés sont généralement étiquetés avec Custom. des éléments ajoutés à leur nom et des espaces supprimés. Par exemple :

Nom convivial Nom de la référence
Approver Custom.Approver
Request Type Custom.RequestType
Scope Estimate Custom.CustomEstimate

Pour les projets qui utilisent le modèle de processus XML local, le nom de référence est défini par les définitions de type d’élément de travail XML.

Pour plus d’informations, veuillez consulter la rubrique Champs et attributs d’élément de travail.

Spécifier des clauses de filtre (WHERE)

La clause WHERE spécifie les critères de filtre. La requête retourne uniquement les éléments de travail qui répondent aux critères spécifiés. Par exemple, l’exemple de clause WHERE suivant retourne des récits utilisateur actifs et qui vous sont affectés.

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

Vous pouvez contrôler l’ordre dans lequel les opérateurs logiques sont évalués en les plaçant entre parenthèses pour regrouper les critères de filtre. Par exemple, pour retourner des éléments de travail qui sont affectés à vous ou que vous avez fermés, utilisez l’exemple suivant.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

Conditions de filtre

Chaque condition de filtre est composée de trois parties, chacune devant être conforme aux règles suivantes :

  • Champ : vous pouvez spécifier le nom de référence ou le nom convivial. Les exemples suivants sont une syntaxe WIQL valide :
    • Nom de la référence : SELECT [System.AssignedTo] ...
    • Nom convivial avec des espaces : SELECT [Assigned To] ...
    • Les noms sans espaces ne nécessitent pas de crochets : SELECT ID, Title ...
  • Opérateur : des valeurs valides sont spécifiées dans la section Opérateurs, plus loin dans cet article.
  • Valeur du champ : vous pouvez spécifier l’une des trois valeurs suivantes en fonction du champ spécifié.
    • Une valeur littérale doit correspondre au type de données de la valeur de champ.
    • Variable ou macro qui indique une certaine valeur. Par exemple, @Me indique la personne qui exécute la requête. Pour plus d’informations, consultez Macros et variables.
    • Nom d’un autre champ. Par exemple, vous pouvez utiliser [Assigned to] = [Changed by] pour rechercher des éléments de travail assignés à la personne qui a modifié l’élément de travail en dernier.

Pour obtenir une description et les noms de référence de tous les champs définis par le système, consultez Index des champs d’élément de travail.

Opérateurs

Les requêtes utilisent des expressions logiques pour qualifier les jeux de résultats. Ces expressions logiques forment une ou plusieurs opérations jointes.

Voici quelques opérations de requête simples :

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

Le tableau suivant récapitule tous les opérateurs pris en charge pour différents types de champs. Pour plus d’informations sur chaque type de champ, consultez Champs et attributs d’élément de travail.

Les =opérateurs , <>><>=et <= les opérateurs fonctionnent comme prévu. Par exemple, System.ID > 100 les requêtes pour tous les éléments de travail dont ID la valeur est supérieure à 100. System.ChangedDate > '01-01-25 12:00:00' requêtes pour tous les éléments de travail modifiés après midi du 1er janvier 2025.

Au-delà de ces opérateurs de base, il existe certains comportements et opérateurs spécifiques à certains types de champs.

Notes

Les opérateurs disponibles dépendent de votre plateforme et de votre version. Pour plus d’informations, consultez Référence rapide de requête.

Type Field Opérateurs pris en charge
Boolean = , <> , =[Field] , <>[Field]
DateTime = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Double GUID Integer = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Identity = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
PlainText Contains Words, Not Contains Words, Is Empty, Is Not Empty
String = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
TreePath =, <>, In, Not In, Under, Not Under

Regroupements logiques

Vous pouvez utiliser les termes AND et OR dans le sens booléen classique pour évaluer deux clauses. Vous pouvez utiliser les termes AND EVER et OR EVER lors de la spécification d’un opérateur WAS EVER. Vous pouvez regrouper des expressions logiques et les regrouper en fonction des besoins. Les exemples suivants illustrent.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

Vous pouvez négation des opérateurs et des opérateurs containsunderà l’aide innotde . Vous ne pouvez pas inverser l’opérateur ever. L’exemple suivant interroge tous les éléments de travail qui ne sont pas affectés sous la sous-arborescence de Fabrikam Fiber\Account Management.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

Exemple de requête, Was Ever Assigned To

L’exemple d’Éditeur de requête suivant recherche tous les éléments de travail qui ont été attribués à Jamal Hartnett.

Capture d’écran de l’Éditeur de requête, requête de liste plate, tous les éléments attribués.

La syntaxe WIQL correspondante est la suivante :

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

Macros ou variables

Le tableau suivant répertorie les macros ou variables que vous pouvez utiliser dans une requête WIQL.

Macro Utilisation
@Me Utilisez cette variable pour rechercher automatiquement l'alias de l'utilisateur actuel dans un champ qui contient des alias d'utilisateur. Par exemple, vous pouvez rechercher des éléments de travail que vous avez ouverts si vous définissez la Field colonne Activated Bysur , la Operator colonne =sur et la colonne Valuesur @Me .
@CurrentIteration Utilisez cette variable pour filtrer automatiquement les éléments de travail affectés au sprint actuel pour l’équipe sélectionnée en fonction du contexte d’équipe sélectionné.
@Project Utilisez cette variable pour rechercher des éléments de travail dans le projet actuel. Par exemple, vous pouvez trouver tous les éléments de travail dans le projet actuel si vous définissez la Field colonne Team Projectsur , la Operator colonne =sur et la Value colonne @Projectsur .
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear
Utilisez ces macros pour filtrer DateTime les champs en fonction du début du jour, de la semaine, du mois, de l’année ou d’un décalage à l’une de ces valeurs. Par exemple, vous pouvez trouver tous les éléments créés au cours des trois derniers mois si vous définissez la Field colonne Created Datesur , la Operator colonne >=sur et la Value colonne @StartOfMonth - 3sur .
@Today Utilisez cette variable pour rechercher des éléments de travail en rapport avec la date actuelle ou une date antérieure. Vous pouvez également modifier la @Today variable en soustrayant des jours. Par exemple, vous pouvez trouver tous les éléments activés dans la semaine dernière si vous définissez la Field colonne Activated Datesur , la Operator colonne >=sur et la Value colonne sur @Today - 7.
[Any] Utilisez cette variable pour rechercher des éléments de travail en rapport avec n'importe quelle valeur définie pour un champ particulier.

Macro @me

La macro @me remplace le nom du compte intégré Windows de l’utilisateur qui exécute la requête. L’exemple suivant montre comment utiliser la macro et l’instruction statique équivalente. La macro est destinée à être utilisée avec des champs d’identité comme Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

Macro @today

Vous pouvez utiliser la macro avec n’importe @today quel DateTime champ. Cette macro remplace minuit de la date actuelle sur l’ordinateur local qui exécute la requête. Vous pouvez également spécifier @today+x ou @today-y avec des décalages entiers pour x jours après @today et y jours avant @today, respectivement. Une requête qui utilise la @today macro peut retourner différents jeux de résultats en fonction du fuseau horaire dans lequel elle s’exécute.

Les exemples suivants supposent qu’aujourd’hui est le 3/1/2025.

WHERE  
   [System.CreatedDate] = @today

Équivaut à :

WHERE  
   [System.CreatedDate] = '01-03-2025'

And

WHERE  
   [System.CreatedDate] > @today-2

Équivaut à :

WHERE  
   [System.CreatedDate] > '01-01-2025'

Macros @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear

Vous pouvez utiliser les @StartOf... macros avec n’importe quel DateTime champ. Cette macro remplace minuit du jour actuel, début de la semaine, début du mois ou début de l’année sur l’ordinateur local qui exécute la requête.

Ces macros acceptent une chaîne de modificateur dont le format est (+/-)nn(y|M|w|d|h|m). Comme pour la macro @Today, vous pouvez spécifier des décalages entiers (plus ou moins). Si le qualificateur d’unité de temps est omis, elle utilise par défaut la période naturelle de la fonction. Par exemple, @StartOfWeek("+1") est identique à @StartOfWeek("+1w"). Si le signe plus/moins (+/-) est omis, plus est supposé.

Cette syntaxe vous permet d’imbriquer des modificateurs et de décaler votre requête deux fois. Par exemple, la clause Closed Date >= @StartOfYear - 1 filtre les éléments de travail fermés depuis l’année dernière. Lorsque vous la modifiez Closed Date >= @StartOfYear('+3M') - 1, elle exclut les éléments de travail fermés au cours des trois premiers mois de l’année dernière. La syntaxe WIQL suivante illustre :

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

Les exemples suivants supposent qu’aujourd’hui est le 4/5/2025.

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

Équivaut à :

WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2025'

And

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

Équivaut à :

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2025'

Macros personnalisées

WIQL prend également en charge les macros personnalisées arbitraires. Toute chaîne préfixée par un @ est traitée comme un macro personnalisé et est substituée. La valeur de remplacement de la macro personnalisée est récupérée à partir du paramètre de contexte de la méthode de requête dans le modèle d’objet. La méthode suivante est l’API utilisée pour les macros :

public WorkItemCollection Query(string wiql, IDictionary context)

Le paramètre de contexte contient des paires clé-valeur pour les macros. Par exemple, si le contexte contient une paire clé-valeur de (project, MyProject), puis @project est remplacé par MyProject dans le WIQL. Ce remplacement est la façon dont le générateur de requêtes d’élément de travail gère la @project macro dans Visual Studio.

Spécifier des requêtes historiques (ASOF)

Vous pouvez utiliser une clause ASOF dans une requête pour filtrer les éléments de travail qui répondent aux conditions de filtre spécifiées, car ils ont été définis à une date et une heure spécifiques.

Notes

Vous ne pouvez pas créer de requêtes ASOF dans le concepteur de requêtes de Visual Studio. Si vous créez un fichier de requête (.wiq) qui inclut une ASOF clause, puis chargez-le dans Visual Studio, la ASOF clause est ignorée.

Supposons qu’un élément de travail a été classé sous une Iteration Path étiquette Fabrikam Fiber\Release 1 de « Jamal Hartnett » avant le 5/05/2025. Toutefois, l’élément de travail a récemment été attribué à « Raisa Pokrovskaya » et déplacé vers un nouveau chemin d’itération de Version 2. L’exemple de requête suivant retourne les éléments de travail assignés à Jamal Hartnett parce que la requête est basée sur l’état des éléments de travail à une date et heure passées.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2025 00:00:00.0000000'

Notes

Si aucune heure n’est spécifiée, WIQL utilise minuit. Si aucun fuseau horaire n’est spécifié, WIQL utilise le fuseau horaire de l’ordinateur client local.

Définir l’ordre de tri (ORDER BY)

Vous pouvez utiliser la clause ORDER BY pour trier les résultats d’une requête sur un ou plusieurs champs dans l’ordre croissant ou décroissant.

Notes

Les préférences de tri du serveur SQL sur la couche données déterminent l’ordre de tri par défaut. Toutefois, vous pouvez utiliser les paramètres asc ou desc pour choisir un ordre de tri explicite.

L’exemple suivant trie d’abord Priority les éléments de travail par ordre croissant (par défaut), puis Created Date par ordre décroissant (DESC).

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

Pour retourner des liens entre les éléments de travail, spécifiez FROM WorkItemLinks. Les conditions de filtre dans la WHERE clause peuvent s’appliquer aux liens ou à tout élément de travail qui est la source ou la cible d’un lien. L’exemple suivant retourne les liens entre Product Backlog Items et leurs éléments enfants actifs.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
MODE (Recursive)

Le tableau suivant récapitule les différences entre les requêtes d’élément de travail et les requêtes pour les liens entre les éléments de travail.

Clause Éléments de travail Liens entre les éléments de travail
FROM FROM WorkItems FROM WorkItemLinks
WHERE [FieldName] = Value Spécifiez un ou plusieurs des éléments suivants :
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'
MODE Non applicable Spécifiez l'une des valeurs suivantes :
- MODE (MustContain): (Valeur par défaut) Retourne uniquement WorkItemLinkInfo les enregistrements où les critères source, cible et lien sont tous satisfaits.
- MODE (MayContain): retourne WorkItemLinkInfo des enregistrements pour tous les éléments de travail qui répondent aux critères source et de lien, même si aucun élément de travail lié ne satisfait aux critères cibles.
- MODE (DoesNotContain): retourne WorkItemLinkInfo des enregistrements pour tous les éléments de travail qui répondent à la source, uniquement si aucun élément de travail lié ne satisfait aux critères de lien et de cible.
- MODE (Recursive): Utiliser pour les requêtes d’arborescence ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Le type de lien doit être Arborescence et la direction Direct. Retourne WorkItemLinkInfo des enregistrements pour tous les éléments de travail qui répondent à la source, de manière récursive pour la cible. ORDER BY et ASOF ne sont pas compatibles avec les requêtes d’arborescence.
RETURNS WorkItemQueryResult WorkItemLink

Vous pouvez spécifier l’un des noms de type de lien système suivants.

Vous pouvez spécifier l’un des noms de types de liens système suivants ou un type de lien personnalisé défini avec le processus XML local.

  • System.LinkTypes.Hierarchy-Forward
  • System.LinkTypes.Related
  • System.LinkTypes.Dependency-Predecessor
  • System.LinkTypes.Dependency-Successor
  • Microsoft.VSTS.Common.Affects-Forward (processus CMMI)

Pour plus d’informations, consultez Référence sur le type de lien.

Exemple de requête de type Arborescence

Notes

ORDER BY et ASOF ne sont pas compatibles avec les requêtes d’arborescence. N’incluez pas ces clauses dans les requêtes d’arborescence.

La requête suivante retourne tous les types d’éléments de travail définis dans le projet actuel. L’Éditeur de requête affiche la requête, comme illustré dans l’image suivante.

Capture d’écran de l’Éditeur de requête, requête d’arborescence, tous les éléments de travail et états.

La syntaxe WIQL équivalente est la suivante :

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

L’exemple suivant retourne tous les types d’éléments de travail définis dans le projet actuel. L’Éditeur de requête affiche la requête, comme illustré dans l’image suivante.

Capture d’écran de l’Éditeur de requête, requête de lien direct, tous les éléments de travail et états.

La syntaxe WIQL équivalente est la suivante :

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

Autres exemples de requêtes

L’exemple de requête WIQL classique suivant utilise des noms de référence pour les champs. La requête sélectionne les éléments de travail (aucun type d’élément de travail spécifié) avec un Priority=1. La requête retourne le ID jeu de retours Title sous forme de colonnes. Les résultats sont triés ID par ordre croissant.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Modèle date/heure

Vous spécifiez le modèle date-heure selon l’un des deux modèles suivants :

AND [System.ChangedDate] >= '1/1/2025 00:00:00Z'

Exemples de clauses

Les exemples d’instructions suivants montrent des clauses de qualification spécifiques.

Clause Example
AND
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND ([System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>OR [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>')
NOT
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
EVER
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
UNDER
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AreaPath] UNDER 'Agile1\Area 0'
ORDER BY
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ORDER BY [System.Id] [asc | desc]
ASOF (filtre temporel)
SELECT [System.Title]<br>FROM workitems<br>WHERE [System.IterationPath] = 'MyProject\Beta'<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ASOF '3/16/25 12:30'

Chaîne et PlainText

Littéraux de chaîne de guillemets (guillemets simples ou doubles sont pris en charge) dans une comparaison avec un String ou PlainText un champ. Les littéraux de chaîne prennent en charge tous les caractères Unicode.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Vous pouvez utiliser l’opérateur contains pour rechercher une sous-chaîne n’importe où dans la valeur du champ.

WHERE [System.Description] contains 'WIQL'

Zone et itération (TreePath)

Vous pouvez utiliser l’opérateur UNDER pour les champs et Area Path les Iteration Path champs. L’opérateur UNDER évalue si une valeur se trouve dans la sous-arborescence d’un nœud de classification spécifique. Par exemple, l’expression suivante prend la valeur true si l’objet Area Path était MyProject\Server\Administration, MyProject\Server\Administration\Feature 1ou MyProject\Server\Administration\Feature 2\SubFeature 5tout autre nœud dans la sous-arborescence.

WHERE [System.AreaPath] UNDER `MyProject\Server\Administration`

Modificateurs et opérateurs spéciaux

Vous pouvez utiliser certains modificateurs et opérateurs spéciaux dans une expression de requête.

Utilisez l’opérateur IN pour évaluer si une valeur de champ est égale à l’une des valeurs d’un ensemble. Cet opérateur est pris en charge pour les types de champs, et StringIntegerDouble les DateTimetypes de champs. L’exemple suivant et son équivalent sémantique illustrent cela.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

L’opérateur EVER est utilisé pour déterminer si une valeur de champ est égale ou jamais égale à une valeur particulière dans toutes les révisions passées des éléments de travail. Les Stringtypes , Integer, Doubleet DateTime de champ prennent en charge cet opérateur. Il existe d’autres syntaxes pour l’opérateur EVER. Par exemple, les extraits de code suivants interrogent si tous les éléments de travail ont été attribués à Jamal, Raisa ou Christie.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Utiliser Copilot pour écrire, corriger et optimiser WIQL

Vous pouvez utiliser un assistant IA (par exemple, GitHub Copilot ou d’autres copilotes) pour vous aider à créer, corriger ou optimiser des requêtes WIQL. Traitez Copilot comme une aide de productivité, et non une source faisant autorité, et examinez et testez toujours toute requête générée avant de l’exécuter sur des données de production.

Conseils et bonnes pratiques :

  • Fonctionnalités : Copilot peut traduire les exigences en langage brut en WIQL, corriger les erreurs de syntaxe (crochets sans correspondance, virgules manquantes, mots clés incorrects), convertir des listes SELECT entre noms conviviaux et références, générer ASOF des clauses ou des littéraux de date et suggérer des réécritures de clauses pour affiner ou élargir les jeux de résultats.
  • Valider : toujours validé WIQL généré dans l’Éditeur de requête ou un projet de test sécurisé. Vérifiez les macros (par exemple @Me, @Today) et les formats de date dépendant des paramètres régionaux avant l’utilisation.
  • Sécurité : ne collez jamais les secrets, les jetons d’accès ou les chaînes de connexion privées dans des invites. Supprimez ou réactez toutes les valeurs sensibles dans les exemples que vous alimentez vers Copilot.
  • Performances : Demandez à Copilot de réduire les charges utiles de résultat (renvoyer uniquement les champs nécessaires), d’ajouter des filtres WHERE appropriés et d’éviter une utilisation excessive de IN recherches illimitées LIKE ou non. N’oubliez pas la limite de caractères 32 K pour les requêtes WIQL.
  • Passez en revue les cas de périphérie : confirmez le comportement des requêtes historiques (ASOF), des requêtes d’arborescence/liaison (FROM workItemLinks) et WAS EVER/EVER des opérateurs qui analysent les révisions, ce qui peut être plus complexe et peut nécessiter un réglage manuel.

Exemple : générer WIQL à partir de l’anglais brut :

Invite : « Retourner l’ID et le titre des bogues actifs affectés @Me au projet « Fabrikam » et modifiés au cours des 30 derniers jours. Trier par ChangedDate desc. »

Copilot produit :

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

Automatiser les requêtes WIQL avec l’API REST et l’IA

Vous pouvez utiliser des assistants IA, comme Copilot, pour automatiser le processus d’API REST WIQL en deux étapes :

  1. Utilisez l’API REST Query By Wiql pour récupérer les ID d’élément de travail correspondant à votre WIQL.
  2. Utilisez l’API Obtenir des éléments de travail pour récupérer des détails complets pour ces ID.

L’IA peut vous aider à :

  • Générez WIQL à partir du langage brut, puis chaînez les deux appels d’API dans le code (par exemple, Python, PowerShell ou JavaScript).
  • Mettez en forme et récapitulez les résultats des tableaux de bord ou des rapports.

Conseil

Pour plus d’informations sur l’API REST, consultez Requête par Wiql (API REST).

Exemple : Automatiser WIQL avec Python et IA

Supposons que vous souhaitez répertorier les titres et les états de tous les bogues actifs dans un projet.

Invite à Copilot :
« Écrire du code Python qui utilise l’API REST Azure DevOps pour répertorier les titres et les états de tous les bogues actifs dans mon projet. Utilisez WIQL pour obtenir les ID, puis récupérez les détails de ces ID. »

Vous pouvez utiliser Copilot pour générer du code comme suit :

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")