BatchByChunkV3.make

Обзор

Используйте BatchByChunkV3.make() для выполнения большого числа запросов REST API с автоматическим пакетированием.

Метод возвращает Promise с объектом Result<T[]>, содержащим объединённые результаты всех успешных команд.

Это особенно полезно для:

• Массового создания или обновления записей
• Экспорта больших объёмов данных через пакетные запросы
• Выполнения сложных операций, требующих множества разных API-вызовов

// @check-ignore: full example — BatchCommands Array.from tuple inference and fields not in TypeCallParams

// Базовое использование
import { B24Hook, EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'

// Создаём 150 задач (будут разделены на 3 чанка по 50 задач каждый)
const commands = Array.from({ length: 150 }, (_, i) => [
  'tasks.task.get',
  { id: i + 1, select: ['id', 'title'] }
])

const response = await $b24.actions.v3.batchByChunk.make({
  calls: commands,
  options: {
    isHaltOnError: true,
    requestId: 'unique-request-id'
  }
})

Сигнатура метода

make<T = unknown>(
  options: ActionBatchByChunkV3
): Promise<Result<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 },
  // ...
]

Опции пакетного запроса (options.options)

Возвращаемое значение

Promise<CallBatchResult<T>> — promise, разрешающийся в объект Result<T[]>.

Важные особенности:

• Только успешные результаты: в массив попадают только успешно выполненные команды.
• Объединённый массив: результаты из всех чанков объединяются в единый массив.
• Порядок сохраняется: результаты сохраняются в том же порядке, что и исходные команды.

Обработка ошибок

Метод разбивает все команды на чанки и начинает выполнять их по очереди через Batch.

Если при вызове Batch возникает ошибка, она сохраняется в Result, и цикл продолжает выполняться.

Параметр isHaltOnError влияет на поведение метода callBatch:

При isHaltOnError = false команды выполняются, даже если некоторые завершились с ошибкой. При isHaltOnError = true (по умолчанию) выполнение пакета прекращается, если в какой-либо команде возникает ошибка.

Всегда проверяйте результат через isSuccess и обрабатывайте ошибки:

// @check-ignore: top-level return in error-handling illustration

const calls = Array.from({ length: 150 }, (_, i) => [
  'tasks.task.get',
  { id: i + 1 }
])
const response = await $b24.actions.v3.batchByChunk.make({
  calls,
  options: {
    isHaltOnError: true,
    requestId: 'unique-request-id'
  }
})

if (!response.isSuccess) {
  // Обработка ошибки
  console.error(new Error(`Error: ${response.getErrorMessages().join('; ')}`))
  return
}

// Работа с успешным результатом
const data = response.getData()

Примеры

Массовое создание задач

// @check-ignore: full example — BatchCommands Array.from tuple inference and fields not in TypeCallParams

import { AjaxError, B24Hook, LoggerFactory } from '@bitrix24/b24jssdk'

type TaskItem = {
  id: number
  title: string
}

const devMode = !!(typeof import.meta !== 'undefined' && (import.meta.dev || import.meta.env?.DEV))
const $logger = LoggerFactory.createForBrowser('Example:batchByChunkTask', devMode)
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

async function addMultipleItems(needAdd: number, requestId: string): Promise<number[]> {
  const calls = Array.from({ length: needAdd }, (_, i) => [
    'tasks.task.add',
    {
      fields: {
        title: `Automatic task #${i + 1}`,
        creatorId: 1,
        responsibleId: 1
      }
    }
  ])

  const response = await $b24.actions.v3.batchByChunk.make<{ item: TaskItem }>({
    calls,
    options: {
      isHaltOnError: true,
      requestId
    }
  })

  if (!response.isSuccess) {
    throw new Error(`Problem: ${response.getErrorMessages().join('; ')}`)
  }

  const resultData = response.getData() ?? []
  const results: number[] = resultData.map(chunkRow => chunkRow.item.id)

  return results
}

// Использование
const requestId = 'batch/tasks.task.add'
try {
  const needAdd = 120
  const items = await addMultipleItems(needAdd, requestId)
  
  $logger.info(`Retrieved ${items.length} items`, {
    expected: needAdd,
    retrieved: items.length,
    items
  })
} catch (error) {
  if (error instanceof AjaxError) {
    $logger.critical(error.message, { requestId, code: error.code })
  } else {
    $logger.alert('Problem', { requestId, error })
  }
}

Альтернативы и рекомендации

• Для последовательных запросов: используйте Call для одиночных вызовов.
• Для работы со списками: используйте CallList для получения больших объёмов данных.
• Для поэтапной обработки: используйте FetchList для обработки данных по мере поступления.
• Для пакетных операций: используйте Batch для выполнения до 50 команд в одном запросе.
• На стороне клиента (браузер): используйте встроенный объект B24Frame.