Как проверить фильтр Jira Cloud на известных задачах через REST

Подготовьте две версии фильтра

Вы хотите сузить выборку интеграции до задач с меткой triage. Перед заменой сохранённого запроса проверьте, какие известные задачи останутся в выборке. Для этого в REST API v3 Jira Cloud есть операция Check issues against JQL. Она принимает несколько запросов и список числовых идентификаторов задач. Для Data Center проверьте доступные операции в справочнике установленной версии.

Понадобятся доступный тестовый проект PILOT, учётная запись с правами интеграции и три учебные задачи. Сохраните исходный JQL и подпишите оба варианта в протоколе. Зафиксируйте, какую задачу новый фильтр должен оставить, какую исключить по метке и какую исключить по проекту.

Соберите контрольные идентификаторы

Возьмите задачу с меткой triage в PILOT, задачу без этой метки в PILOT и задачу с меткой triage в другом учебном проекте. Проверьте, что все три доступны выбранной учётной записи. Если внешняя задача скрыта правами, её отсутствие в результате не позволит подтвердить, что условие project сработало.

Откройте каждую задачу через Get issue и возьмите верхнеуровневое поле id. Для запроса проверки передайте его как целое число. Ключ вида PILOT-1 подходит для открытия карточки, а в issueIds нужны числовые ID. Значения ниже условные, замените их своими.

Отправьте запрос на проверку

В настроенном клиенте Jira Cloud отправьте POST на /rest/api/3/jql/match с типом содержимого application/json. Используйте авторизацию и адрес, предусмотренные для вашего клиента. Документация указывает максимум 10 JQL-выражений и 50 ID задач на вызов. В нашем случае достаточно одного запроса с тремя задачами и двумя версиями JQL.

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

{
  "issueIds": [10101, 10102, 10103],
  "jqls": [
    "project = PILOT",
    "project = PILOT AND labels = triage"
  ]
}

Прочитайте результат для каждого JQL

При HTTP 200 проверьте массив matches. Его элементы возвращаются в порядке запросов. Посмотрите errors для каждого элемента, затем сравните matchedIssues с ожидаемыми ID. Один успешный HTTP-ответ может содержать ошибку конкретного выражения, поэтому принимать настройку только по коду ответа рано.

Если учебные данные соответствуют плану, первый элемент должен содержать ID 10101 и 10102, второй — только 10101. Порядок ID внутри результата для этой проверки не важен. Для контроля обработки ошибок можно отдельным вызовом передать заведомо незавершённое выражение project = и посмотреть, как клиент показывает отказ. Не сохраняйте этот вариант в рабочем фильтре.

Для передачи проверки коллеге запишите рядом с каждым выражением ожидаемые и полученные ключи. Если в ответе есть ошибки, оставьте результат этого выражения неопределённым до исправления и повторного запроса. Так в протоколе будет видно, какие исключения подтверждены и какие проверки нужно повторить после правки.

Разберите пустой результат и права

Если задача пропала из обоих результатов, проверьте её доступность через Get issue под той же учётной записью. Операция учитывает право просмотра проекта и ограничения на просмотр задач. Если задача входит в старый результат и отсутствует в новом, сравните её фактическую метку с условием запроса. При HTTP 400 проверьте форму JSON, типы ID и размеры массивов.

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

Внесите изменение с возможностью возврата

Сохраните предыдущий запрос в журнале изменений рядом с именем фильтра и списком его потребителей. После согласования замените JQL, затем повторите тот же контроль и проверьте работу потребителя. Если состав изменился сверх ожидаемого, верните сохранённый JQL и перепроверьте прежнюю выборку.

Если фильтр управляет действиями автоматизации, отдельно проверьте её журнал. Возврат JQL восстанавливает отбор для последующих запусков. Уже выполненные действия требуют отдельного разбора. Ожидаемые результаты в этом примере описаны для учебных задач. В реальной Jira запросы не запускались.