REST / BX24.callMethod, пагинация и ошибки

BX24.callMethod

Метод вызывает REST из JS-кода приложения, открытого внутри Bitrix24.

Базовый вызов

BX24.init(function () {
    BX24.callMethod(
        'user.current',
        {},
        function (result) {
            if (result.error()) {
                console.error(result.error());
                return;
            }

            console.log(result.data());
        }
    );
});

Проверка ошибки

Не стоит сразу обращаться к result.data(). Сначала нужно проверить result.error().

/**
 * Обрабатывает ответ BX24.callMethod.
 */
function handleBx24Result(result, success_callback) {
    if (result.error()) {
        console.error('REST error:', result.error());
        alert('Ошибка REST: ' + result.error());

        return;
    }

    success_callback(result.data());
}

BX24.callMethod('crm.item.get', {
    entityTypeId: 2,
    id: 123
}, function (result) {
    handleBx24Result(result, function (data) {
        console.log(data);
    });
});

Пагинация

Списочные методы REST не возвращают сразу все данные.

result.more и result.next

В callback BX24.callMethod можно проверить, есть ли ещё страницы, через result.more(), а следующий start получить через result.next().

BX24.callMethod(
    'crm.item.list',
    {
        entityTypeId: 2,
        select: ['id', 'title'],
        filter: {
            '>id': 0
        }
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data().items);

        if (result.more()) {
            console.log('Следующая страница:', result.next());
        }
    }
);

Получить все страницы

/**
 * Получает все страницы списочного REST-метода.
 */
function fetchAllRestItems(method, parameters, start, items, callback) {
    var current_items = items || [];
    var current_start = start || 0;

    BX24.callMethod(
        method,
        Object.assign({}, parameters, {
            start: current_start
        }),
        function (result) {
            if (result.error()) {
                console.error(result.error());
                callback([]);

                return;
            }

            var data = result.data();
            var page_items = data.items || data.result || data || [];

            current_items = current_items.concat(page_items);

            if (result.more()) {
                fetchAllRestItems(method, parameters, result.next(), current_items, callback);
                return;
            }

            callback(current_items);
        }
    );
}

fetchAllRestItems(
    'crm.item.list',
    {
        entityTypeId: 2,
        select: ['id', 'title'],
        filter: {
            '>id': 0
        }
    },
    0,
    [],
    function (items) {
        console.log(items);
    }
);

Для больших выборок лучше делать фильтр по ID и загружать данные частями, чтобы не упереться в лимиты и не перегрузить браузер.

start в REST

В обычном REST-запросе параметр start указывает, с какой страницы или позиции продолжать выборку. Размер страницы зависит от метода, но часто это 50 записей.

BX24.callMethod(
    'crm.item.list',
    {
        entityTypeId: 2,
        select: ['id', 'title'],
        start: 50
    },
    function (result) {
        console.log(result.data());
    }
);

Ошибки REST

Ошибки REST лучше обрабатывать одинаково во всех вызовах.

Где смотреть ошибку

Где вызывается REST	Где смотреть ошибку
`BX24.callMethod`	`result.error()`, DevTools Console, Network.
Входящий вебхук	JSON-ответ: `error`, `error_description`.
Серверное приложение	Лог своего приложения и ответ Bitrix24.

Типовые причины

у вебхука или приложения нет нужного scope;
пользователь не имеет прав на CRM-сущность;
неверный метод или устаревший метод;
неверная структура параметров;
закончился OAuth-токен;
метод доступен только приложению, но вызывается через вебхук.

Единая обёртка

/**
 * Вызывает REST-метод и возвращает Promise.
 */
function callRest(method, parameters) {
    return new Promise(function (resolve, reject) {
        BX24.callMethod(method, parameters || {}, function (result) {
            if (result.error()) {
                reject(result.error());
                return;
            }

            resolve(result.data());
        });
    });
}

callRest('user.current')
    .then(function (user) {
        console.log(user);
    })
    .catch(function (error) {
        console.error('REST error:', error);
    });