Обзор
Используйте BatchV2.make() для выполнения до 50 команд REST API в одном запросе. Это особенно полезно, когда нужно получить или обновить большие объёмы данных, минимизируя сетевые запросы и соблюдая ограничения REST API.
// Базовое использование
import { EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'
const response = await $b24.actions.v2.batch.make({
calls: [
['crm.item.get', { entityTypeId: EnumCrmEntityTypeId.contact, id: 1 }],
['crm.item.get', { entityTypeId: EnumCrmEntityTypeId.contact, id: 2 }]
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: 'unique-request-id'
}
})
Сигнатура метода
make<T = unknown>(
options: ActionBatchV2
): Promise<CallBatchResult<T>>
Параметры
Объект options содержит следующие свойства:
Форматы команд (options.calls)
1. Массив кортежей (BatchCommandsArrayUniversal)
// @check-ignore: partial snippet — calls array literal, not a valid statement
calls: [
['method1', params1],
['method2', params2],
// ...
]
2. Массив объектов (BatchCommandsObjectUniversal)
// @check-ignore: partial snippet — object array literal, not a valid statement
calls: [
{ method: 'method1', params: params1 },
{ method: 'method2', params: params2 },
// ...
]
3. Объект с именованными командами (BatchNamedCommandsUniversal)
calls: {
command1: { method: 'method1', params: params1 },
command2: ['method2', params2],
// ...
}
Опции пакетного запроса (options.options)
Возвращаемое значение
Promise<CallBatchResult<T>> — promise, разрешающийся в объект CallBatchResult<T>.
Структура результата зависит от формата входных данных:
- Для массива команд: массив результатов в том же порядке.
- Для именованных команд: объект с ключами, соответствующими именам команд.
Данные элемента результата
Каждый result отдельной команды возвращается ровно так, как его отдал REST API,
включая null, когда вызываемый метод действительно не возвращает данных
(например, im.chat.get, вызванный с ENTITY_TYPE, не соответствующим
никакому чату).
// @check-ignore: partial snippet — uses union result type and undeclared variables
const response = await $b24.actions.v2.batch.make<{ ID: number } | null>({
calls: {
chatGet: {
method: 'im.chat.get',
params: { ENTITY_TYPE: 'UNKNOWN', ENTITY_ID: 'UNKNOWN' }
}
},
options: { returnAjaxResult: true, requestId: 'chat-get' }
})
const chatGet = response.getData().chatGet
if (chatGet.getData()?.result === null) {
// метод вернул null — ни один чат не совпал
} else {
console.log(chatGet.getData()?.result.ID)
}
null приводился к {}, что ломало nullable-type-guards на
стороне вызова (см. issue #23).
При типизации generic для методов, которые могут вернуть null, объявляйте его как
T | null.Обработка ошибок
Всегда проверяйте результат через isSuccess и обрабатывайте ошибки:
// @check-ignore: top-level return in error-handling illustration
const response = await $b24.actions.v2.batch.make({
calls: [
{ method: 'crm.item.get', params: { entityTypeId: EnumCrmEntityTypeId.contact, id: 1 } },
{ method: 'crm.item.get', params: { entityTypeId: EnumCrmEntityTypeId.contact, id: 2 } }
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: 'unique-request-id'
}
})
if (!response.isSuccess) {
// Обработка ошибки
console.error(new Error(`Error: ${response.getErrorMessages().join('; ')}`))
return
}
// Работа с успешным результатом
const data = response.getData()
Проверка isSuccess покрывает два разных вида сбоя:
- Ошибки отдельных команд — конверт батча успешен, но отдельные команды упали. Проверяйте каждый
AjaxResultвgetData()или используйтеgetErrorsByKey(), чтобы узнать, какая команда упала. - Ошибки уровня конверта (soft) — весь батч падает до того, как вернётся хоть один результат команды, например при серверном коде валидации (
BITRIX_REST_V3_EXCEPTION_VALIDATION_*). Тогда внешнийResult—isSuccess === false, ошибка(и) вgetErrorMessages()/getErrors(), аgetData().resultпуст.
Одна проверка if (!response.isSuccess) обрабатывает оба случая.
Примеры
Получение нескольких компаний из CRM
Инициализация хранилища данных
Этот код автоматизирует создание и инициализацию хранилищ данных в Bitrix24 через REST API.
Он проверяет существование указанных хранилищ и, если их нет, создаёт их вместе с указанными свойствами, используя пакетные запросы для эффективности.
Удаление хранилища данных
Этот код удаляет несколько хранилищ данных в системе Bitrix24 через REST API.
Он последовательно отправляет delete-запросы для каждого хранилища данных, указанного в dataStorageMap, используя метод entity.delete.
Альтернативы и рекомендации
- Для последовательных запросов: используйте
Callдля одиночных вызовов. - Для работы со списками: используйте
CallListдля получения больших объёмов данных. - Для поэтапной обработки: используйте
FetchListдля обработки данных по мере поступления. - Для запуска большего числа команд (более 50): используйте
BatchByChunk, который автоматически разбивает команды на чанки по 50. - На стороне клиента (браузер): используйте встроенный объект
B24Frame.
FetchList
Возвращает AsyncGenerator, позволяющий обрабатывать данные из list-методов REST API Bitrix24 версии 2 по мере поступления, не загружая весь массив в память сразу. Особенно полезно при работе с очень большими объёмами данных.
BatchByChunk
Метод для выполнения пакетных запросов с автоматическим разбиением на чанки для любого числа команд. Автоматически делит большие наборы команд на батчи по 50 и выполняет их последовательно. Используйте только массивы кортежей или массивы объектов.