Выбор подходящего метода

Обзор

SDK предоставляет пять примитивов для работы с REST API Bitrix24, все доступны через b24.actions.v{2,3}.<primitive>.make(options). Они выглядят похоже, но имеют очень разные характеристики стоимости. Выбор неподходящего — самая частая причина медленных приложений и тикетов «почему мой дашборд забивает очередь?». Эта страница поможет принять решение за 30 секунд.

Выбор определяется тремя осями:

1. Один вызов или много? Один REST-метод или несколько сразу.
2. Ограничено или нет? Известно ли заранее, что результатов ≤ 50, или их может быть 50 000?
3. Всё сразу или потоком? Нужны все записи в памяти для агрегации или обрабатывать по мере поступления?

Матрица решений

Затем выберите версию API: предпочтительно v3 для любых методов, доступных в v3 (лучшая фильтрация, большие страницы, оптимизация на сервере), и v2 для всего остального. v2-версия Call.make() в SDK выводит предупреждение, когда вы вызываете v3-доступный метод в v2 — это сигнал к миграции.

Компромиссы по методам

Call.make()

Используйте, когда нужна ровно одна запись или одна серверная операция (update, add, delete).

Избегайте, когда обнаруживаете, что оборачиваете его в for-цикл с await — это сигнал переключиться на Batch или BatchByChunk. Цикл из N вызовов Call.make() — это N round-trip'ов; Batch сворачивает до 50 в один. BatchByChunk сворачивает любое число в ceil(N / 50) round-trip'ов.

CallList.make()

Используйте, когда результирующий набор достаточно мал, чтобы держать в памяти, и вы будете делать с ним что-то сквозное (сортировка, группировка, агрегация, дедупликация, передача в библиотеку графиков).

Избегайте, когда нужен лишь небольшой срез — передайте select и filter, чтобы сузить результат, вместо того чтобы получать всё. Метод всегда забирает все страницы, соответствующие вашему фильтру; «дай мне топ-10» без фильтра — расточительство.

FetchList.make()

Используйте, когда результат неограничен (или может быть), и вы можете обрабатывать записи по мере поступления: стримить их в CSV, отправлять в очередь, писать в базу, передавать через WebSocket.

Избегайте, когда нужна агрегация по всем записям, требующая полного набора в памяти — CallList проще. Генератор отдаёт чанки по 50 (v2) или options.limit до 1000 (v3); ваш downstream-код должен обработать каждый чанк до следующего запроса, поэтому тяжёлая синхронная работа между чанками замедляет общий проход.

Batch.make()

Используйте, когда одно действие пользователя зависит от данных нескольких разных методов. Типичный пример — плитка дашборда, которой нужны профиль пользователя, число открытых сделок и закреплённые задачи — три разных метода, один round-trip.

Избегайте, когда один и тот же метод повторяется 50+ раз. Именно для этого нужен BatchByChunk, а Batch отклонит всё, что больше 50 команд. Также избегайте, когда нужны именованные ключи результата и > 50 вызовов — BatchByChunk намеренно принимает только массив кортежей / массив объектов (именованные команды ломаются на границах чанков).

BatchByChunk.make()

Используйте, когда у вас произвольное число команд одной формы — массовые миграции, массовые create / update / delete, экспорт per-id-деталей для тысяч связанных записей.

Избегайте, когда у вас всего несколько вызовов — Batch проще и даёт именованные результаты. Также избегайте, когда нужно транзакционное поведение — BatchByChunk не атомарен. Если чанк 7 из 30 упал, чанки 1-6 уже применены; чанки 8-30 могут выполниться или нет в зависимости от isHaltOnError.

Лимиты — кратко

Частые антипаттерны

• b24.callMethod() / b24.callBatch() / b24.callListMethod() / b24.fetchListMethod() / b24.callBatchByChunk(). Устаревшие шорткаты в AbstractB24. Они ещё работают, но выводят предупреждение при каждом вызове и будут удалены в v2.0.0. Мигрируйте на соответствующий b24.actions.v{2,3}.<primitive>.make({…}) — см. руководство по миграции v0 → v1 для пошагового соответствия.
• for (const id of ids) await b24.actions.v2.call.make(...). N ID = N round-trip'ов. Используйте actions.v2.batch.make, если ids.length ≤ 50, иначе actions.v2.batchByChunk.make.
• actions.v2.callList.make → actions.v2.callList.make → actions.v2.callList.make для связанных сущностей. Это причина большинства медленных дашбордов. Получите родительский список один раз (actions.v2.callList.make или actions.v2.fetchList.make), затем загрузите связанные записи через один actions.v2.batch.make на каждый чанк из 50 ID.
• Свой order в actions.v{2,3}.callList.make / actions.v{2,3}.fetchList.make. Курсорной пагинации нужен order: { idKey: 'ASC' }. Любой пользовательский order отбрасывается с runtime-предупреждением (см. Ограничения). Вместо этого используйте filter, чтобы сузить срез.
• actions.v{2,3}.batch.make с именованными командами на > 50 элементах. Либо разбейте вручную на несколько вызовов batch.make, либо переключитесь на actions.v{2,3}.batchByChunk.make и используйте упорядоченные результаты.
• Смешивание методов v2 и v3 в одном вызове actions.v3.batch.make. BatchV3 предварительно валидирует список вызовов и бросает SdkError с кодом JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3, если какой-то метод не поддерживается в v3. Разделите батч по версиям API или используйте actions.v2.batch.make.

См. также

• Рецепт: экспорт сделок в CSV — FetchList для потокового экспорта.
• Рецепт: массовое обновление сделок — BatchByChunk для массовой мутации.
• Коды ошибок и обработка — SdkError, AjaxError, коды на стороне REST.
• Система ограничений — выбор пресета restrictionParams для выбранного метода.