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.

Свойство	По умолчанию	Описание
`batchSize`	50	Максимальное число команд в одном пакете запросе (не более 50)
`throttle`	2	Максимальное число запросов к API в секунду (не более 2-х запросов в секунду)
`progress`	`percent => {};`	Функция для контроля прогресса выполнения запросов в методах `callListMethod()`, `fetchList()`, `callLongBatch()` и `callLargeBatch()` (`percent` - прогресс 0-100, %)

(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 - функция для извлечения данных из результатов запроса.

(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 - функция для извлечения данных из результатов запроса.

(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).

(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 - функция для извлечения данных из результатов запроса.

(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 - функция для извлечения данных из результатов запроса.

(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 - функция для извлечения данных из результатов запроса.

(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 - массив параметров запросов.

(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));

Автор

Лицензия

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

andrey-tech / bx24-wrapper-js

Maintainers

Details

README

Содержание

Требования

Класс BX24Wrapper

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

Метод `async callMethod()`

Метод `async callListMethod()`

Метод `async *fetchList()`

Метод `async callBatch()`

Метод `async callLongBatch()`

Метод `async *callLargeBatch()`

Метод `static createCalls()`

Метод `getLastResult()`

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

Автор

Лицензия

andrey-tech / bx24-wrapper-js

Maintainers

Details

README

Содержание

Требования

Класс BX24Wrapper

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

Метод async callMethod()

Метод async callListMethod()

Метод async *fetchList()

Метод async callBatch()

Метод async callLongBatch()

Метод async *callLargeBatch()

Метод static createCalls()

Метод getLastResult()

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

Автор

Лицензия

Метод `async callMethod()`

Метод `async callListMethod()`

Метод `async *fetchList()`

Метод `async callBatch()`

Метод `async callLongBatch()`

Метод `async *callLargeBatch()`

Метод `static createCalls()`

Метод `getLastResult()`