Download the PHP package andrey-tech/bx24-wrapper-js without Composer

Bitrix24 JS-lib Wrapper

Класс-обертка на JavaScript для стандартной JS-библиотеки Битрикс24. Данный класс позволяет избежать ада колбеков и работать c API Битрикс24 с помощью асинхронных функций и асинхронных генераторов ECMAScript 9.

Разработчики на PHP могут воспользоваться классом-оберткой andrey-tech/bitrix24-api-php.

Содержание

• Требования
• Класс BX24Wrapper
• Методы класса BX24Wrapper
  • Метод async callMethod()
  • Метод async callListMethod()
  • Метод async *fetchList()
  • Метод async callBatch()
  • Метод async callLongBatch()
  • Метод async *callLargeBatch()
  • Метод static createCalls()
  • Метод getLastResult()
• Обработка ошибок
• Автор
• Лицензия

Требования

• Стандартная JS-библиотека Битрикс24 v1.0, которая представляет собой JavaScriptS SDK для REST API, что позволяет обращаться к API прямо из front-end приложения не погружаясь в реализацию авторизации по OAuth 2.0. Для внешних приложений и вебхуков библиотека использоваться не может.

Подключение стандартной библиотеки Битрикс24 v1.0:

• Среда исполнения JavaScript, соответствущая спецификации ECMAScript 9 (ECMAScript® 2018) в части поддержки асинхронных генераторов JavaScript :
  • Google Chrome >= 63
  • Mozilla Firefox >= 55
  • Apple Safari >= 12
  • Microsoft Edge >= 79
  • Opera >= 50

Класс BX24Wrapper

Создание нового объекта класса BX24Wrapper:

• new BX24Wrapper();

Дополнительные параметры работы устанавливаются через свойства объекта класса BX24Wrapper.

Методы класса BX24Wrapper

Метод async callMethod()

Вызывает указанный метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис).
Обертка метода callMethod стандартной библиотеки Битрикс24.

• callMethod(method [, params = {}, dataExtractor = null ]);
  Параметры:
  • string method - строка, указывающая вызываемый метод REST-сервиса;
  • object params - объект параметров для метода REST-сервиса;
  • function dataExtractor - функция для извлечения данных из результатов запроса.

Метод async callListMethod()

Вызывает указанный списочный метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис). Позволяет одним вызовом загружать произвольное число сущностей с фильтрацией по параметрам в виде массива объектов и контролировать прогресс выполнения загрузки.

• callListMethod(listMethod [, params = {}, dataExtractor = null ]);
  Параметры:
  • string listMethod - строка, указывающая вызываемый списочный метод REST-сервиса;
  • object params - объект параметров для списочного метода REST-сервиса;
  • function dataExtractor - функция для извлечения данных из результатов запроса.

Метод async *fetchList()

Вызывает указанный списочный метод REST-сервиса с заданными параметрами и возвращает объект Generator (генератор). Позволяет одним вызовом загружать произвольное число сущностей с фильтрацией по параметрам в виде массива объектов и контролировать прогресс выполнения загрузки.

Реализует быстрый алгоритм, описанный в статье "Как правильно выгружать большие объемы данных". Использование асинхронного генератора дает существенную экономию памяти при обработке большого количества сущностей.

• fetchList(listMethod [, params = {}, dataExtractor = null, idKey = 'ID' ]);
  Параметры:
  • string listMethod - строка, указывающая вызываемый списочный метод REST-сервиса;
  • object params - объект параметров для списочного метода REST-сервиса;
  • function dataExtractor - функция для извлечения данных из результатов запроса;
  • string idKey - имя поля ID загружаемых сущностей (ID - CRM или id).

Метод async callBatch()

Отправляет пакет запросов к REST-сервису с максимальным числом команд в запросе 50 и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива или объекта. Обертка метода callBatch стандартной библиотеки Битрикс24.

• callBatch(calls [, haltOnError = true, dataExtractor = null ]);
  Параметры:
  • array|object calls - пакет запросов в виде массива или объекта;
  • bool haltOnError - флаг "прерывать исполнение пакета в при возникновении ошибки";
  • function dataExtractor - функция для извлечения данных из результатов запроса.

Метод async callLongBatch()

Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива.

• callLongBatch(calls [, haltOnError = true, dataExtractor = null ]);
  Параметры:
  • array calls - пакет запросов в виде массива;
  • bool haltOnError - флаг "прерывать исполнение пакета в при возникновении ошибки";
  • function dataExtractor - функция для извлечения данных из результатов запроса.

Метод async *callLargeBatch()

Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Generator (генератор). Позволяет получить результаты пакетного выполнения запросов в виде массива. Использование асинхронного генератора дает существенную экономию памяти при работе с длинными пакетами запросов.

• callLargeBatch(calls [, haltOnError = true, dataExtractor = null ]);
  Параметры:
  • array calls - пакет запросов в виде массива;
  • bool haltOnError - флаг "прерывать исполнение пакета в при возникновении ошибки";
  • function dataExtractor - функция для извлечения данных из результатов запроса.

Метод static createCalls()

Создает пакет однотипных запросов для методов callBatch(), callLongBatch() и callLargeBatch() и возвращает пакет запросов в виде массива.

• BX24Wrapper.createCalls(method, items);
  Параметры:
  • string method - строка, указывающая вызываемый метод REST-сервиса во всех запросах;
  • array items - массив параметров запросов.

Метод getLastResult()

Возвращает последний объект ajaxResult, полученный от стандартной библиотеки Битрикс24.

• getLastResult();

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

При возникновении ошибок в методах класса выбрасываются исключения.
Последний объект ajaxResult, полученный от стандартной библиотеки Битрикс24, может быть получен посредством метода getLastResult().

Автор

© 2019-2023 andrey-tech

Лицензия

Данный класс распространяется на условиях лицензии MIT.