andrey-tech/bx24-wrapper-js

用于标准Bitrix24 JS库的简单JavaScript类包装器。它允许避免回调地狱，并使用异步函数和ECMAScript 9的异步生成器与Bitrix24 REST API协同工作。

维护者

详细信息

github.com/andrey-tech/bx24-wrapper-js

主页

源代码

问题

安装: 8

依赖项: 0

建议者: 0

安全: 0

星级: 30

关注者: 3

分支: 14

开放问题: 1

语言：JavaScript

1.5.1 2023-08-06 06:39 UTC

MIT 8d33ac4fad751ecdd1b893409ba4d653cfa0b000

javascriptapiJSthrottlingasyncbitrixBitrix24BX24async-generatorECMAScriptECMAScript9

This package is auto-updated.

Last update: 2024-09-06 09:01:09 UTC

README

Bitrix24 logo

Latest Stable Version GitHub stars GitHub forks GitHub watchers License

用于标准JS库的Bitrix24的JavaScript类包装器。此类允许避免回调地狱，并使用异步函数和ECMAScript 9的异步生成器与Bitrix24 API协同工作。

PHP开发者可以使用andrey-tech/bitrix24-api-php类包装器。

内容

要求

  • Bitrix24 v1.0标准JS库，该库是REST API的JavaScript SDK，允许直接从前端应用程序调用API，而不必深入OAuth 2.0认证实现。**对于外部应用程序和Webhook，此库无法使用**。

连接标准Bitrix24 v1.0库

<script src="//api.bitrix24.com/api/v1/"></script>
  • 符合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类的所有方法

异步调用方法

调用指定REST服务的指定方法，并返回Promise对象。
标准Bitrix24库callMethod方法的包装器。

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

异步调用列表方法

调用指定列表方法，并返回Promise对象。允许一次性加载任意数量的实体，通过参数数组进行过滤，并控制加载进度。

  • callListMethod(listMethod [, params = {}, dataExtractor = null ]);
    参数
    • string listMethod - 指示要调用REST服务的列表方法字符串;
    • object params - 列表方法的参数对象;
    • 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));

异步获取列表

调用指定列表方法，并返回Generator对象。允许一次性加载任意数量的实体，通过参数数组进行过滤，并控制加载进度。

实现了一篇名为"如何正确加载大量数据"的文章中描述的快速算法。使用异步生成器在处理大量实体时可以显著节省内存。

  • fetchList(listMethod [, params = {}, dataExtractor = null, idKey = 'ID' ]);
    参数
    • string listMethod - 指示要调用REST服务的列表方法字符串;
    • object params - 列表方法的参数对象;
    • 函数 dataExtractor - 用于从查询结果中提取数据的函数；
    • 字符串 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));

异步批量调用

向REST服务发送请求包，请求包中的最大命令数为50，并返回Promise（承诺）。允许以数组或对象的形式获取批量执行查询的结果。是标准Bitrix24库的callBatch方法的包装。

  • callBatch(calls [, haltOnError = true, dataExtractor = null ]);
    参数
    • 数组|对象 calls - 以数组或对象形式表示的请求包；
    • 布尔值 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));

异步长批量调用

以数组形式向REST服务发送请求包，其中包含任意数量的命令，并返回Promise（承诺）。允许以数组的形式获取批量执行查询的结果；

  • callLongBatch(calls [, haltOnError = true, dataExtractor = null ]);
    参数
    • 数组 calls - 以数组形式表示的请求包；
    • 布尔值 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));

异步大批量调用

以数组形式向REST服务发送请求包，其中包含任意数量的命令，并返回Generator（生成器）。允许以数组的形式获取批量执行查询的结果。使用异步生成器在处理长请求包时可以显著节省内存；

  • callLargeBatch(calls [, haltOnError = true, dataExtractor = null ]);
    参数
    • 数组 calls - 以数组形式表示的请求包；
    • 布尔值 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));

创建调用

为callBatch、callLongBatch和callLargeBatch方法创建相同类型的请求包，并返回以数组形式表示的请求包。

  • BX24Wrapper.createCalls(method, items);
    参数
    • 字符串 method - 表示所有请求中调用的REST服务方法的字符串；
    • 数组 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));

获取最后一个结果

返回从标准Bitrix24库获取的最后一个ajaxResult对象。

  • getLastResult();

错误处理

在类的方法中发生错误时抛出异常。
可以通过getLastResult()方法获取从标准Bitrix24库获取的最后一个ajaxResult对象。

(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许可证分发。