Фильтрация, сортировка, пагинация

filter, order, limit и offset — четыре параметра, которые управляют любой выборкой в JSON API 1.2. Разберём операторы фильтра, сортировку, пагинацию и приёмы полной выгрузки.

Параметр filter

Фильтрация задаётся параметром filter. Условия пишутся как поле оператор значение, а несколько условий разделяются точкой с запятой:

GET /entity/customerorder?filter=applicable=true;sum>100000

Несколько условий по одному полю объединяются логическим ИЛИ, условия по разным полям — логическим И. Для фильтра по ссылке в значении указывают полный href объекта:

GET /entity/customerorder?filter=agent=https://api.moysklad.ru/api/remap/1.2/entity/counterparty/{id}

Значение фильтра должно быть URL-кодировано — особенно если в нём есть пробелы, кириллица или символы &. Многие клиентские библиотеки делают это автоматически, но при ручной сборке строки запроса про кодирование легко забыть и получить неверную выборку или ошибку 400. Фильтровать можно как по системным полям (name, code, updated, sum), так и по дополнительным полям — для этого в качестве имени поля указывают ссылку на метаданные атрибута.

Операторы фильтра

JSON API поддерживает набор операторов сравнения и вхождения:

Сортировка order

Порядок выдачи задаётся параметром order. Направление указывается через запятую после имени поля:

GET /entity/product?order=name,asc
GET /entity/customerorder?order=moment,desc

Можно сортировать по нескольким полям, разделяя их точкой с запятой:

GET /entity/customerorder?order=applicable,desc;moment,asc

• asc — по возрастанию (значение по умолчанию, если направление опущено);
• desc — по убыванию.

Сортировать можно по большинству системных полей: name, moment, updated, sum. Не все поля сортируемы — по вложенным ссылкам и вычисляемым значениям порядок может не поддерживаться, и тогда API вернёт ошибку. Для инкрементальной синхронизации особенно полезна сортировка по updated,asc: она позволяет забирать только те объекты, что изменились после последнего успешного обмена, комбинируя order с фильтром filter=updated>=....

Пагинация limit и offset

Выборка страницами управляется двумя параметрами:

GET /entity/product?limit=100&offset=200 вернёт третью сотню товаров. Общее число объектов лежит в meta.size ответа — по нему считают количество страниц.

Быстрый поиск search

Помимо точного filter, есть контекстный поиск по параметру search. Он ищет подстроку сразу по нескольким текстовым полям объекта — имени, коду, артикулу, описанию:

GET /entity/assortment?search=кофе

Отличия от filter:

• search — нечёткий поиск по многим полям, удобен для строки поиска в интерфейсе;
• filter — точные условия по конкретным полям, удобен для программной выборки.

Параметры можно комбинировать: сначала сузить filter, затем искать по search внутри результата. При таком совмещении сначала применяются точные условия фильтра, а поиск работает уже по отобранному подмножеству — это заметно ускоряет запрос на больших коллекциях. В отличие от filter, у search нет операторов: он всегда ищет вхождение переданной строки без учёта регистра.

Полная выгрузка списка

Чтобы выгрузить всю коллекцию, листают страницы, пока не переберут все объекты. Алгоритм:

1. Запросить первую страницу с limit=1000&offset=0.
2. Прочитать meta.size — общее количество.
3. Увеличивать offset на 1000, пока не заберёте все объекты.
4. Соблюдать паузы, чтобы не упереться в лимиты запросов.

Итог

Выборкой в JSON API 1.2 управляют четыре параметра: filter с богатым набором операторов, order для сортировки, limit и offset для пагинации, плюс контекстный search. Максимум страницы — 1000 объектов, а полная выгрузка строится листанием по offset с фиксированным порядком.

Эти приёмы — основа надёжного обмена: правильные фильтры снижают объём данных и нагрузку на API. Мы проектируем такие выгрузки как часть интеграций и highload-проектов на 1С-Битрикс, где важны и скорость, и устойчивость к лимитам. Если синхронизация упирается в объёмы, поможем оптимизировать её.