Язык запросов 2.0 в API

Используйте язык запросов 2.0, чтобы задать условия поиска задач в параметре query2. MLJ (Mongo-like JSON) — формат JSON для описания фильтра QL2.

В отличие от параметра query, в query2 передается не строка из интерфейса Трекера, а JSON-объект.

Параметр query2 поддерживается в методе Найти задачи в версиях API v2 и v3. Рекомендуем использовать v3.

Формат запроса

Общий вид запроса с параметром query2:

POST /v3/issues/_search
Host: api.tracker.yandex.net
Content-Type: application/json
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "query2": {
    "<ключ_поля>": {
      "<оператор_отношения>": "<значение_или_функция>"
    }
  }
}

Значение query2 — выражение MLJ. Оно строится из трех видов конструкций:

• условие по полю — сравнивает поле задачи с заданным или вычисляемым значением;
• логическая группа — объединяет несколько условий с помощью логического оператора;
• макрос — задает условие по связанному объекту или включает условия сохраненного фильтра.

В синтаксисе MLJ все служебные слова начинаются с $: логические операторы, операторы отношения, макросы и функции. Ключи полей и значения, заданные напрямую, не начинаются с $.

Условие по полю

В условии укажите идентификатор поля задачи, оператор отношения и значение. Для системного или глобального поля используйте ключ. Например, assignee — ключ поля «Исполнитель». Отображаемое название поля вместо ключа использовать нельзя. Доступные ключи перечислены на странице Поля задач.

Для локального поля очереди укажите идентификатор поля для API (apiId). Как узнать идентификатор локального поля

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

Например, этот запрос найдет задачи, назначенные текущему пользователю:

{
  "query2": {
    "assignee": {
      "$eq": {
        "$me": []
      }
    }
  }
}

Операторы отношения

Оператор отношения сравнивает значение поля с заданным или вычисляемым значением.

Функции

Функция начинается с символа $ и передается как объект. Аргументы функции указываются в массиве. Функции без аргументов принимают пустой массив []. Значение $period передается строкой.

Логическая группа и операторы

Логический оператор объединяет несколько условий. На верхнем уровне его можно не указывать: в этом случае используется $and.

Например, запрос найдет задачи, назначенные текущему пользователю, или задачи с приоритетом blocker либо critical:

{
  "query2": {
    "$or": [
      {
        "assignee": {
          "$eq": {
            "$me": []
          }
        }
      },
      {
        "priority": {
          "$in": ["blocker", "critical"]
        }
      }
    ]
  }
}

Логические операторы связывают условия и группы. Их можно вкладывать друг в друга. Поддерживаются следующие операторы:

Макросы

Макросы объединения задают условия по связанным с задачей объектам определенного типа, например по комментариям или связям. Они меняют контекст вложенного фильтра. Внутри макроса укажите поля связанного объекта. Значения этих полей можно задавать функциями. Задача попадает в результаты поиска, если хотя бы один объект соответствует вложенному фильтру.

Например, этот запрос найдет задачи с комментарием текущего пользователя:

{
  "query2": {
    "$comments": {
      "comment.author": {
        "$eq": {
          "$me": []
        }
      }
    }
  }
}

В запросах можно использовать следующие макросы:

Макрос $include отличается от остальных: он не меняет контекст на связанный объект, а включает в запрос условия сохраненного фильтра. Укажите идентификатор фильтра в поле include.id.

Например, этот запрос ищет задачи, которые соответствуют сохраненному фильтру с идентификатором 123:

{
  "query2": {
    "$include": {
      "include.id": {
        "$eq": 123
      }
    }
  }
}