Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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.
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 ...
- Nom de la référence :
- 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,
@Meindique 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.
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
Interroger les liens entre éléments de travail
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-ForwardSystem.LinkTypes.RelatedSystem.LinkTypes.Dependency-PredecessorSystem.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.
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)
Exemple de requête de lien direct
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.
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 :
- Le format Modèle de date et de modèle d’heure provient de vos préférences utilisateur, de l’heure et des paramètres régionaux
- Modèle spécifié par UTC, qui suit ce modèle (avec Z ajouté à la date-heure).
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
ASOFdes 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
INrecherches illimitéesLIKEou 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) etWAS EVER/EVERdes 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 :
- Utilisez l’API REST Query By Wiql pour récupérer les ID d’élément de travail correspondant à votre WIQL.
- 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.")