andrey-tech / bx24-wrapper-js
Простой класс-обертка на JavaScript для стандартной JS-библиотеки Битрикс24. Позволяет избежать ада колбеков и работать c REST API Битрикс24 с помощью асинхронных функций и асинхронных генераторов ECMAScript 9
Installs: 8
Dependents: 0
Suggesters: 0
Security: 0
Stars: 31
Watchers: 3
Forks: 14
Open Issues: 1
Language:JavaScript
This package is auto-updated.
Last update: 2024-11-06 09:18:01 UTC
README
Класс-обертка на JavaScript для стандартной JS-библиотеки Битрикс24. Данный класс позволяет избежать ада колбеков и работать c API Битрикс24 с помощью асинхронных функций и асинхронных генераторов ECMAScript 9.
Разработчики на PHP могут воспользоваться классом-оберткой andrey-tech/bitrix24-api-php.
Содержание
Требования
- Стандартная JS-библиотека Битрикс24 v1.0, которая представляет собой JavaScriptS SDK для REST API, что позволяет обращаться к API прямо из front-end приложения не погружаясь в реализацию авторизации по OAuth 2.0. Для внешних приложений и вебхуков библиотека использоваться не может.
Подключение стандартной библиотеки Битрикс24 v1.0:
<script src="//api.bitrix24.com/api/v1/"></script>
- Среда исполнения 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
.
(async () => { let bx24 = new BX24Wrapper(); // Устанавливаем максимальное число команд в одном пакете запросе bx24.batchSize = 25; // Устанавливаем троттлинг запросов к API Битрикс24 на уровне 0,5 запросов в секунду, // то есть 1 запрос в 2 секунды bx24.throttle = 0.5; // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах bx24.progress = percent => console.log(`Progress: ${percent}%`); })().catch(error => console.log('Error:', error));
Методы класса BX24Wrapper
Метод async callMethod()
Вызывает указанный метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис).
Обертка метода callMethod стандартной библиотеки Битрикс24.
callMethod(method [, params = {}, dataExtractor = null ]);
Параметры:- string
method
- строка, указывающая вызываемый метод REST-сервиса; - object
params
- объект параметров для метода REST-сервиса; - function
dataExtractor
- функция для извлечения данных из результатов запроса.
- string
(async () => { let bx24 = new BX24Wrapper(); // Загружаем компанию по её ID let company = await bx24.callMethod('crm.company.get', { ID: 6 }); console.log('Company:', company); })().catch(error => console.log('Error:', error));
Метод async callListMethod()
Вызывает указанный списочный метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис). Позволяет одним вызовом загружать произвольное число сущностей с фильтрацией по параметрам в виде массива объектов и контролировать прогресс выполнения загрузки.
callListMethod(listMethod [, params = {}, dataExtractor = null ]);
Параметры:- string
listMethod
- строка, указывающая вызываемый списочный метод REST-сервиса; - object
params
- объект параметров для списочного метода REST-сервиса; - function
dataExtractor
- функция для извлечения данных из результатов запроса.
- string
(async () => { let bx24 = new BX24Wrapper(); // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах bx24.progress = percent => console.log(`progress: ${percent}%`); let params = { filter: { CATALOD_ID: 21 }, select: [ '*', 'PROPERTY_*' ] }; // Загружем список всех товаров в заданном товарном каталоге CRM let products = await bx24.callListMethod('crm.product.list', params); for (let product of products) { console.log('Product:', product); } params = { filter: { iblockId: 11 }, select: [ '*', 'id', 'iblockId' ] }; // Задаем собственную функцию для извлечения массива товаров из объекта с результатами запроса let dataExtractor = data => data.products; // Загружем список всех товаров в заданном товарном каталоге products = await bx24.callListMethod('catalog.product.list', params, dataExtractor); for (let product of products) { console.log('Product:', product); } })().catch(error => console.log('Error:', error));
Метод 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
).
- string
(async () => { let bx24 = new BX24Wrapper(); // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах bx24.progress = percent => console.log(`progress: ${percent}%`); let params = { filter: { CATALOD_ID: 21 } }; // Загружем список всех товаров в заданном товарном каталоге CRM, используя асинхронный генератор let generator = bx24.fetchList('crm.product.list', params); for await (let products of generator) { for (let product of products) { console.log('Product:', product); } } params = { filter: { iblockId: 11 }, select: [ '*', 'id', 'iblockId' ] }; // Задаем собственную функцию для извлечения массива товаров из объекта с результатами запроса let dataExtractor = data => data.products; // Задаем имя поля ID загружаемых сущностей (товаров) в результатах запроса let idKey = 'id'; // Загружем список всех товаров в заданном товарном каталоге, используя асинхронный генератор generator = bx24.fetchList('catalog.product.list', params, dataExtractor, idKey); for await (let products of generator) { for (let product of products) { console.log('Product:', product); } } })().catch(error => console.log('Error:', error));
Метод async callBatch()
Отправляет пакет запросов к REST-сервису с максимальным числом команд в запросе 50 и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива или объекта. Обертка метода callBatch стандартной библиотеки Битрикс24.
callBatch(calls [, haltOnError = true, dataExtractor = null ]);
Параметры:- array|object
calls
- пакет запросов в виде массива или объекта; - bool
haltOnError
- флаг "прерывать исполнение пакета в при возникновении ошибки"; - function
dataExtractor
- функция для извлечения данных из результатов запроса.
- array|object
(async () => { let bx24 = new BX24Wrapper(); // Пакет запросов в виде массива с максимальным числом команд в запросе 50 let calls = [ [ 'crm.deal.get', { id: 2880 } ], [ 'crm.contact.get', { id: 8 } ], [ 'crm.company.get', { id: 6 } ] ]; // Отправляем пакет запросов в виде массива let response = await bx24.callBatch(calls, false); console.log('Response array:', response); // Пакет запросов в виде объекта с максимальным числом команд в запросе 50 calls = { get_deal: [ 'crm.deal.get', { id: 2880 } ], get_company: [ 'crm.company.get', { id: '$result[get_deal][COMPANY_ID]' } ], get_contact: [ 'crm.contact.get', { id: '$result[get_deal][CONTACT_ID]' } ] }; // Отправляем пакет запросов в виде объекта response = await bx24.callBatch(calls); console.log('Response object:', response); })().catch(error => console.log('Error:', error));
Метод async callLongBatch()
Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива.
callLongBatch(calls [, haltOnError = true, dataExtractor = null ]);
Параметры:- array
calls
- пакет запросов в виде массива; - bool
haltOnError
- флаг "прерывать исполнение пакета в при возникновении ошибки"; - function
dataExtractor
- функция для извлечения данных из результатов запроса.
- array
(async () => { let bx24 = new BX24Wrapper(); // Длинный пакет запросов в виде массива с произвольным числом команд в запросе let calls = [ [ 'crm.deal.get', { id: 2880 } ], [ 'crm.contact.get', { id: 8 } ], [ 'crm.company.get', { id: 6 } ], [ 'crm.product.get', { id: 1 } ] ]; // Отправляем длинный пакет запросов в виде массива let response = await bx24.callLongBatch(calls); console.log('Response array:', response); })().catch(error => console.log('Error:', error));
Метод async *callLargeBatch()
Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Generator (генератор). Позволяет получить результаты пакетного выполнения запросов в виде массива. Использование асинхронного генератора дает существенную экономию памяти при работе с длинными пакетами запросов.
callLargeBatch(calls [, haltOnError = true, dataExtractor = null ]);
Параметры:- array
calls
- пакет запросов в виде массива; - bool
haltOnError
- флаг "прерывать исполнение пакета в при возникновении ошибки"; - function
dataExtractor
- функция для извлечения данных из результатов запроса.
- array
(async () => { let bx24 = new BX24Wrapper(); // Длинный пакет запросов в виде массива с произвольным числом команд в запросе let calls = [ [ 'crm.deal.get', { id: 2880 } ], [ 'crm.contact.get', { id: 8 } ], [ 'crm.company.get', { id: 6 } ], [ 'crm.product.get', { id: 1 } ] ]; // Отправляем длинный пакет запросов в виде массива, используя асинхронный генератор let generator = bx24.callLargeBatch(calls, true); for await (let response of generator) { console.log('Response array:', response); } })().catch(error => console.log('Error:', error));
Метод static createCalls()
Создает пакет однотипных запросов для методов callBatch()
, callLongBatch()
и callLargeBatch()
и возвращает пакет запросов в виде массива.
BX24Wrapper.createCalls(method, items);
Параметры:- string
method
- строка, указывающая вызываемый метод REST-сервиса во всех запросах; - array
items
- массив параметров запросов.
- string
(async () => { let bx24 = new BX24Wrapper(); // Массив параметров однотипных запросов let items = [ { id: 4 }, { id: 6 }, { id: 8 } ]; // Создаем пакет запросов в виже массива let calls = BX24Wrapper.createCalls('crm.contact.get', items); // Отправляем пакет запросов в виде массива let response = await bx24.callBatch(calls); console.log('Response:', response); })().catch(error => console.log('Error:', error));
Метод getLastResult()
Возвращает последний объект ajaxResult, полученный от стандартной библиотеки Битрикс24.
getLastResult();
Обработка ошибок
При возникновении ошибок в методах класса выбрасываются исключения.
Последний объект ajaxResult,
полученный от стандартной библиотеки Битрикс24, может быть получен посредством метода getLastResult()
.
(async () => { let bx24 = new BX24Wrapper(); // Загружаем несуществующую компанию по её ID и перехватываем возникающее исключение let company = await bx24.callMethod('crm.company.get', { ID: 9999999999 }) .catch(error => { console.log('Error:', error); // Получаем последний объект ajaxResult, полученный от стандартной библиотеки Битрикс24 let ajaxResult = bx24.getLastResult(); console.log('ajaxResult:', ajaxResult); }); })().catch(error => console.log('Error:', error));
Автор
© 2019-2023 andrey-tech
Лицензия
Данный класс распространяется на условиях лицензии MIT.