API wrapper для Питона для быстрого получения данных от Битрикс24 через REST API.

• Основная функциональность
• Начало работы
• Примеры использования
• Как это работает
• Советы и подсказки
• Как связаться с автором
• Подробный справочник по API

• На больших списках скорость обмена данными с сервером достигает тысяч элементов в секунду.
• Автоматическая упаковка запросов в батчи сокращает количество требуемых запросов к серверу и ускоряет обмен данными.
• Батчи отправляются на сервер не последовательно, а параллельно.
• Продвинутые стратегии работы с постраничным доступом ускоряют выгрузку на порядки (см. результаты тестов).

• Автоматический autothrottling - если сервер возвращает ошибки, скорость автоматически понижается.
• Если сервер для сложных запросов начинает возвращать ошибки, можно в одну строку понизить скорость запроосов.

• Высокоуровневые списочные методы для сокращения количества необходимого кода. Большинство операций занимают только одну строку кода. Обработка параллельных запросов, упаковка запросов в батчи и многое другое убрано "под капот".
• Позволяет задавать параметры запроса именно в таком виде, как они приведены в документации к Bitrix24 REST API. Параметры проверяются на корректность для облегчения отладки.
• Выполнение запросов автоматически сопровождается прогресс-баром из пакета tqdm, иллюстрирующим не только количество обработанных элементов, но и прошедшее и оставшееся время выполнения запроса.

• Наличие асинхронного клиента позволяет использовать библиотеку для написания веб-приложений (например, телеграм-ботов).

• Яндекс

Установите модуль через pip:

pip install fast-bitrix24

Далее в python:

from fast_bitrix24 import Bitrix

# замените на ваш вебхук для доступа к Bitrix24
webhook = "https://your_domain.bitrix24.ru/rest/1/your_code/"
b = Bitrix(webhook)

Методы полученного объекта b в дальнейшем используются для взаимодействия с сервером Битрикс24.

Чтобы получить полностью список сущностей, используйте метод get_all():

# список лидов
leads = b.get_all('crm.lead.list')

Метод get_all() возвращает список, где каждый элемент списка является словарем, описывающим одну сущность из запрошенного списка.

Вы также можете использовать параметр params, чтобы кастомизировать запрос:

# список сделок в работе, включая пользовательские поля
deals = b.get_all(
    'crm.deal.list',
    params={
        'select': ['*', 'UF_*'],
        'filter': {'CLOSED': 'N'}
})

Если у вас есть необходимость быстро выгрузить большие объемы информации (значения всех полей в длинных списках - в 20+ тыс. элементов), то используйте метод list_and_get().

Если у вас есть список ID сущностей, то вы можете получить их свойства при помощи метода get_by_ID() и использовании методов вида *.get:

'''
получим список всех контактов, привязанных к сделкам, в виде
{
    ID_сделки_1: [контакт_1, контакт_2, ...],
    ID_сделки_2: [контакт_1, контакт_2, ...],
    ...
}
'''

contacts = b.get_by_ID(
    'crm.deal.contact.items.get',
    [d['ID'] for d in deals])

Метод get_by_ID() возвращает словарь с элементами вида ID: result, где result - ответ сервера относительно этого ID.

Чтобы создавать, изменять или удалять список сущностей, используйте метод call():

# вставим в начало названия всех сделок их ID
tasks = [
    {
        'ID': d['ID'],
        'fields': {
            'TITLE': f'{d["ID"]} - {d["TITLE"]}'
        }
    }
    for d in deals
]

b.call('crm.deal.update', tasks)

Метод call() возвращает список ответов сервера по каждому элементу переданного списка.

Вызов call с парамтером raw=True отправляет на сервер переданные ему параметры в оригинальном, необработанном виде (пропуская упаковку в батчи), и возвращает ответ сервера без какой-либо обработки.

Подобный вызов можно использовать в отладочных целях, но кроме того, придется его использовать для отправки запросов, в параметрах которых есть None (None применяется для стирания значения полей, а упаковка в батчи мешает передавать None).

# стереть DESCRIPTION в лиде 123
params = {"ID": 123, "fields": {"DESCRIPTION": None}}
b.call('crm.lead.update', params, raw=True)

Если вы хотите вызвать пакетный метод, используйте call_batch():

results = b.call_batch ({
    'halt': 0,
    'cmd': {
        'deals': 'crm.deal.list', # берем список сделок
        # и берем список дел по первой из них
        'activities': 'crm.activity.list?filter[ENTITY_TYPE]=3&filter[ENTITY_ID]=$result[deals][0][ID]'
    }
})

Если требуется использование бибилиотеки в асинхронном коде, то вместо клиента Bitrix() создавайте клиент класса BitrixAsync():

from fast_bitrix24 import BitrixAsync
b = BitrixAsync(webhook)

Все методы у него - синхронные аналоги методов из Bitrix(), описанных выше:

leads = await b.get_all('crm.lead.list')

1. Перед обращением к серверу во всех методах класса Bitrix происходит проверка корректности самых популярных параметров, передаваемых к серверу, и поднимаются исключения TypeError и ValueError при наличии ошибок.
2. Cоздаются запросы на получение всех элементов из запрошенного списка.
3. Созданные запросы упаковываются в батчи по 50 запросов в каждом.
4. Полученные батчи параллельно отправляются на сервер с регулировкой скорости запросов (см. ниже "Как fast_bitrix24 регулирует скорость запросов").
5. Ответы (содержимое поля result) собираются в единый плоский список и возвращаются пользователю.
   • Поднимаются исключения класса aiohttp.ClientError, если сервер Битрикс вернул HTTP-ошибку, и RuntimeError, если код ответа был 200, но ошибка сдержалась в теле ответа сервера.
   • Происходит сортировка ответов (кроме метода get_all()) - порядок элементов в списке результатов совпадает с порядком соответствующих запросов в списке запросов.

В случае с методом get_all() пункт 2 выше выглядит немного сложнее:

• get_all() делает первый запрос к серверу Битрикс24 с указанным методом и параметрами.
• Сервер возвращает первую страницу (50 элементов) и параметр total - общее количество элементов, найденных по запросу.
• Исходя из полученного общего количества элементов, создаются запросы на каждую из страниц (всего total // 50 - 1 запросов), необходимых для получения всех запрошенных элементов.

В связи с тем, что выполнение get_all() по длинным спискам может занимать долгое время, в течение которого пользователи могут добавлять новые элементы в список, может возникнуть ситуация, когда общее полученное количество элементов может не соответствовать изначальному значению total. В таких случаях будет выдано стандартное питоновское предупреждение (warning).

По умолчанию fast_bitrix24 игнорирует официальные ограничения Битрикс24 по скорости запросов (см. ниже "Официальная политика Битрикс24 по скорости запросов") и вместо этого начинает снижать скорость запросов, если сервер начинает возвращать ошибки (autothrottling). Подобный подход позволяет на порядки увеличить скорость получения данных (см. тесты скорости).

Чтобы соблюдать официальные правила, при создании экземпляра класса Bitrix укажите параметр respect_velocity_policy=True.

1. Существует пул из 50 запросов, которые можно направить без ожидания.
2. Пул пополняется со скоростью 2 запроса в секунду.
3. При исчерпании пула и несоблюдении режима ожидания сервер возвращает ошибку.

Посмотрите в справочник по API. Если не нашли ответа, свяжитесь с автором.

1. Поищите в официальной документации по REST API.
2. Если на ваш вопрос там нет ответа - попробуйте задать его в группе "Партнерский REST API" в Сообществе разработчиков Битрикс24.
3. Спросите в Телеграме в группе разработчиков Битрикс24.
4. Спросите в Телеграме в группе пользователей fast_bitrix24.
5. Спросите на русском StackOverflow.

Включите логирование запросов и ответов сервера.

import logging

logging.getLogger('fast_bitrix24').addHandler(logging.StreamHandler())

Оберните вызов call() в slow:

with b.slow():
    results = b.call('crm.lead.add', tasks)

См. подробнее о slow.

Передавайте параметры запроса методу call(), он может делать как запросы по списку, так и единичный запрос:

method = 'crm.lead.add'
params = {'fields': {'TITLE': 'Чпок'}}
b.call(method, params)

Результатом будет ответ сервера по этому одному элементу.

Однако, если такие вызовы делаются несколько раз, то более эффективно формировать из них список и вызывать call() единожды по всему списку.

Пока что никак.

Все обращения к серверу происходят асинхронно и список результатов отсортирован в том порядке, в котором сервер возвращал ответы. Если вам требуется сортировка, то вам нужно делать ее самостоятельно, например:

deals = b.get_all('crm.deal.list')
deals.sort(key = lambda d: int(d['ID']))

Попробуйте применить метод list_and_get() - он стабильно показывает на порядок лучшие результаты на больших объемах информации.

См. результаты тестов.

Если вы получаете SSLCertVerificationError / CERTIFICATE_VERIFY_FAILED, попробуйте отключить верификацию сертификата SSL. При инициализации передайте в BitrixAsync параметр client, где будет инициализированный вами экземпляр aiohttp.ClientSession, у которого будет отключена верификация SSL:

import aiohttp
import asyncio

from fast_bitrix24 import BitrixAsync


async def main():
    # Инициализировать HTTP-клиента без верификации SSL и передать его в `BitrixAsync`
    connector = aiohttp.TCPConnector(ssl=False)
    async with aiohttp.ClientSession(connector=connector) as client:
        b = BitrixAsync(webhook, client=client)

        # Далее ваши вызовы Битрикса
        ...


asyncio.run(main())

• telegram: https://t.me/fast_bitrix24
• создать новый github issue: https://github.com/leshchenko1979/fast_bitrix24/issues/new