Справочные материалы по синтаксису языка запросов рабочих элементов (WIQL)

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

Синтаксис WIQL можно использовать для определения запроса в виде гиперссылки или при использовании языка запросов рабочих элементов (REST API).

Синтаксис WIQL поддерживает все функции, доступные через веб-портал Редактор запросов плюс несколько других. Можно указать поля для возврата и указания логической группировки предложений запросов. Кроме того, можно использовать ASOF предложение для фильтрации на основе назначений на основе предыдущей даты.

Необходимые компоненты

Запрос возвращает только те рабочие элементы, для которых есть рабочие элементы представления или просмотр рабочих элементов в этом узле. Как правило, эти разрешения предоставляются членам групп читателей и участников для каждого командного проекта. Дополнительные сведения см. в разделе "Разрешения и группы".

Обзор языка запросов

Язык запросов рабочих элементов содержит пять частей, показанных в следующем фрагменте синтаксиса и описанном в следующей таблице. Синтаксис WIQL не учитывает регистр.

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-2020'

Шаблон даты и времени

Шаблон даты и времени, который вы вводите для полей DateTime , должен совпадать с выбранным профилем. Чтобы просмотреть или изменить выбранный вариант, см. раздел "Настройка параметров пользователя".

Поддерживаются литералы DateTime (одиночные или двойные кавычки), используемые в сравнениях. Они должны находиться в формате .NET DateTime локального клиентского компьютера, на котором выполняется запрос. Если часовой пояс не указан, литералы DateTime находятся в часовом поясе локального компьютера.

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

Если время опущено в литерале DateTime и параметр dayPrecision равно false, то время, как предполагается, равно нулю (полуночи). Значение по умолчанию для параметра dayPrecision равно false.

Кроме того, можно указать формат ISO 8601, который является допустимым независимо от языкового стандарта. ISO 8601 представляет дату и время, начиная с года, за которым следует месяц, день, час, минуты, секунды и миллисекунда. Например, 2021-12-10 15:00:00.000 представляет 10 декабря 2021 года в 3 вечера в местное время. Ниже приведен пример использования формата ISO 8601.

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

Пользовательские поля

Указание предложений фильтра (WHERE)

Предложение WHERE задает критерии фильтра. Запрос возвращает только рабочие элементы, удовлетворяющие указанным критериям. Например, в следующем примере WHERE предложения возвращаются истории пользователей, активные и назначенные вам.

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

Вы можете управлять порядком, в котором вычисляются логические операторы, заключив их в скобки, чтобы сгруппировать критерии фильтра. Например, чтобы вернуть рабочие элементы, назначенные вам или закрытые, измените фильтр запроса на соответствие следующему примеру.

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

Условия фильтра

Каждое условие фильтра состоит из трех частей, каждая из которых должна соответствовать следующим правилам:

• Поле: можно указать имя ссылки или понятное имя. Ниже приведены допустимые синтаксисы WIQL:
  • Имя ссылки: SELECT [System.AssignedTo] ...
  • Понятное имя с пробелами: SELECT [Assigned To] ...
  • Имена без пробелов не требуют квадратных квадратных скобок: SELECT ID, Title ...
• Оператор: допустимые значения указываются в разделе "Операторы" далее в этой статье.
• Значение поля: можно указать одно из следующих трех значений в зависимости от указанного поля.
  • Литеральное значение должно соответствовать типу данных значения поля.
  • *переменная или макрос, указывающая определенное значение. Например, @Me указывает, кто выполняет запрос. Дополнительные сведения см. в разделе "Макросы и переменные " далее в этой статье.
  • Имя другого поля. Например, можно использовать [Assigned to] = [Changed by] для поиска рабочих элементов, назначенных пользователю, который изменил рабочий элемент в последнее время.

Описание и ссылочные имена всех системных полей см. в разделе "Индекс поля рабочего элемента".

Операторы

Запросы используют логические выражения для определения результирующих наборов. Эти логические выражения формируются одним или несколькими операциями, которые связаны.

Ниже перечислены некоторые простые операции запроса.

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

В таблице ниже перечислены все поддерживаемые операторы для различных типов полей. Дополнительные сведения о каждом типе поля см. в полях и атрибутах рабочих элементов.

Операторы =, <>, >, <, >=, and <= работают должным образом. Например, System.ID > 100 запросы для всех рабочих элементов с идентификатором, превышающим 100. System.ChangedDate > '01-01-19 12:00:00' Запросы для всех рабочих элементов изменились после полудня 1 января 2019 г.

Помимо этих базовых операторов, существуют некоторые поведения и операторы, относящиеся к определенным типам полей.

Логические группировки

Термины AND и OR в типичном логическом смысле можно использовать для оценки двух предложений. Термины AND EVER можно использовать и OR EVER при указании WAS EVER оператора. При необходимости можно группировать логические выражения и дополнительно объединять их. Примеры приведены ниже.

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>'
        )
    )

Вы можете отменить contains, under, операторы с in помощью not. Вы не можете отменить ever оператор. В приведенном ниже примере запросы для всех рабочих элементов, которые не назначены поддереву Fabrikam Fiber\Account Management.

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

Пример запроса, которому когда-либо назначено

Следующий Редактор запросов пример находит все рабочие элементы, которые когда-либо были назначены Джамалу Хартнетту.

И вот соответствующий синтаксис WIQL.

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>'

Макросы или переменные

В следующей таблице перечислены макросы или переменные, которые можно использовать в запросе WIQL.

@meМакрос

Макрос @me заменяет имя встроенной учетной записи Windows пользователя, выполняющего запрос. В приведенном ниже примере показано, как использовать макрос и эквивалентную статическую инструкцию. Макрос предназначен для использования с полями удостоверений, такими как Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

@todayМакрос

Макрос можно использовать с любым полем @today DateTime. Этот макрос заменяет полночь текущей даты на локальном компьютере, на котором выполняется запрос. Вы также можете указать @today+x или @today-y использовать целочисленные смещения в течение x дней после @today и y до @today, соответственно. Запрос, использующий @today макрос, может возвращать различные результирующие наборы в зависимости от часового пояса, в котором он выполняется.

В приведенных ниже примерах предполагается, что сегодня — 1.3.19.

WHERE  
   [System.CreatedDate] = @today

Эквивалентен:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Эквивалентен:

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

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

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

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

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

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

Пользовательские макросы

WIQL также поддерживает произвольные пользовательские макросы. Любой строковый префикс, префиксируемый элементом, @ обрабатывается как настраиваемый макрос и заменяется. Значение замены настраиваемого макроса извлекается из параметра контекста метода запроса в объектной модели. Следующий метод — это API, используемый для макросов:

public WorkItemCollection Query(string wiql, IDictionary context)

Параметр контекста содержит пары "ключ-значение" для макросов. Например, если контекст содержит пару "ключ-значение" (project, MyProject), то @project заменяется MyProject в WIQL. Эта замена заключается в том, как построитель запросов рабочих элементов обрабатывает макрос @project в Visual Studio.

Указание исторических запросов (ASOF)

Предложение в запросе можно использовать ASOF для фильтрации рабочих элементов, удовлетворяющих указанным условиям фильтра, так как они были определены по определенной дате и времени.

Предположим, что рабочий элемент был классифицирован по пути Fabrikam Fiber\Release 1 итерации и назначен Джамал Хартнетт до 5/05/2022. Тем не менее, рабочий элемент недавно был назначен Раиза Покрывской и переехал в новый путь итерации выпуска 2. В следующем примере запроса возвращаются рабочие элементы, назначенные Jamal Hartnett, так как запрос основан на состоянии рабочих элементов по состоянию на последние дату и время.

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-2022 00:00:00.0000000'

Установка порядка сортировки (ORDER BY)

Предложение можно использовать ORDER BY для сортировки результатов запроса по одному или нескольким полям по возрастанию или убыванию.

В следующем примере рабочие элементы сначала сортируются по приоритету в порядке возрастания (по умолчанию), а затем по дате создания в порядке убывания (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

Запрос ссылок между рабочими элементами

Чтобы вернуть связи между рабочими элементами, укажите FROM WorkItemLinks. Условия фильтрации в WHERE предложении могут применяться к ссылкам или к любому рабочему элементу, который является источником или целевым объектом ссылки. Например, следующий запрос возвращает связи между элементами невыполненной работы продукта и их активными дочерними элементами.

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'
    )
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)

В следующей таблице перечислены различия между запросами рабочих элементов и запросами для связей между рабочими элементами.

• System.LinkTypes.Hierarchy-Forward
• System.LinkTypes.Related
• System.LinkTypes.Dependency-Predecessor
• System.LinkTypes.Dependency-Successor
• Microsoft.VSTS.Common.Affects-Forward (процесс CMMI)

Дополнительные сведения см. в справочнике по типу ссылок.

Пример запроса типа дерева

Следующий запрос возвращает все типы рабочих элементов, определенные в текущем проекте. Запрос, как показано в Редактор запросов, отображается, как показано на следующем рисунке.

Ниже показан эквивалентный синтаксис WIQL.

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)

Пример запроса direct-link

Следующий запрос возвращает все типы рабочих элементов, определенные в текущем проекте. Запрос, как показано в Редактор запросов, отображается, как показано на следующем рисунке.

Эквивалентный синтаксис WIQL, как показано ниже.

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)

Дополнительные примеры запросов

Следующий типичный пример запроса WIQL использует имена ссылок для полей. Запрос выбирает рабочие элементы (без указанного типа рабочего элемента) с приоритетом =1. Запрос возвращает идентификатор и заголовок возвращаемого набора в виде столбцов. Результаты отсортированы по идентификатору в порядке возрастания.

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

Шаблон даты и времени

Шаблон даты и времени указывается в соответствии с одним из двух шаблонов:

• Формат шаблона даты и времени поставляется из ваших предпочтений пользователя, времени и языкового стандарта
• Шаблон, указанный в формате UTC, который следует этому шаблону (с Z, добавленным к дате).

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

Примеры предложений

В следующих примерах инструкций показаны определенные предложения, соответствующие требованиям.

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

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'

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

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [System.Id] [asc | desc]

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>' 
ASOF '3/16/19 12:30'

Строка и обычный текст

Строковые литералы кавычки (однократные или двойные кавычки поддерживаются) в сравнении с строковым или обычным текстовым полем. Строковые литералы поддерживают все символы Юникода.

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

Можно использовать оператор contains для поиска подстроки в любом месте значения поля.

WHERE [System.Description] contains 'WIQL' 

Область и итерация (TreePath)

Оператор можно использовать UNDER для полей "Область" и "Путь итерации". Оператор UNDER оценивает, находится ли значение в поддереве определенного узла классификации. Например, приведенное ниже выражение будет иметь значение true, если путь к области был "MyProject\Server\Administration", "MyProject\Server\Administration\Feature 1", "MyProject\Server\Administration\Feature 2\SubFeature 5" или любой другой узел в поддереве.

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

Модификаторы и специальные операторы

В выражении запроса можно использовать некоторые модификаторы и специальные операторы.

IN Используйте оператор, чтобы оценить, равно ли значение поля любому из набора значений. Этот оператор поддерживается для типов полей String, Integer, Double и DateTime. См. следующий пример, а также его семантический эквивалент.

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>'
    )

Оператор EVER используется для оценки того, равно ли значение поля или когда-либо равно определенное значение во всех прошлых редакциях рабочих элементов. Типы полей String, Integer, Double и DateTime поддерживают этот оператор. Для оператора существуют альтернативные синтаксисы EVER . Например, фрагменты кода ниже запрашивают, были ли все рабочие элементы когда-либо назначены Джамалу, Поднятию или Кристи.

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>'
    )

Связанные статьи

• Поля запросов, операторы, значения и переменные
• Поля и атрибуты рабочих элементов
• Сведения об управляемых запросах
• Определение запроса