A high-level Python SDK for Bitrix24 REST API aiming for speed of high volume transactions. Async operations, automatic batching and traffic throttling to prevent server rejections.
Project description
fast-bitrix24
Высокоуровневый API для Python 3.7+ для быстрого получения данных от Битрикс24 через REST API.
Основная функциональность
Удобство кода
- Высокоуровневые списочные методы для сокращения количества необходимого кода. Большинство операций занимают только одну строку кода. Обработка параллельных запросов, упаковка запросов в батчи и многое другое убрано "под капот".
- Позволяет задавать параметры запроса именно в таком виде, как они приведены в документации к Bitrix24 REST API. Параметры проверяются на корректность для облегчения отладки.
- Выполнение запросов автоматически сопровождается прогресс-баром из пакета
tqdm
, иллюстрирующим не только количество обработанных элементов, но и прошедшее и оставшееся время выполнения запроса.
Высокая скорость обмена данными
- На больших списках скорость обмена данными с сервером достигает тысяч элементов в секунду.
- Использование асинхронных запросов через
asyncio
иaiohttp
позволяет экономить время, делая несколько запросов к серверу параллельно. - Автоматическая упаковка запросов в батчи сокращает количество требуемых запросов к серверу и ускоряет обмен данными.
Избежание отказов сервера
- Скорость отправки запросов к серверу Битрикс контролируется для избежания ошибки HTTP
503 Service unanavilable
. - Размера батча контролируется для избежания ошибки HTTP
414 URI too long
. - Если сервер для сложных запросов начинает возвращать
500 HTTP Internal Server Error
, можно в одну строку понизить скорость запроосов.
Начало
Установите модуль через 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()
Чтобы получить полностью список сущностей, используйте метод get_all()
:
# список пользователей
users = b.get_all('user.get')
Метод get_all()
возвращает список, где каждый элемент списка является словарем, описывающим одну сущность из запрощенного списка.
Вы также можете использовать параметр params
, чтобы кастомизировать запрос:
# список сделок в работе, включая пользовательские поля
deals = b.get_all('crm.deal.get', params={
'select': ['*', 'UF_*'],
'filter': {'CLOSED': 'N'}
})
get_by_ID()
Если у вас есть список ID сущностей, то вы можете получить их при помощи метода get_by_ID()
:
'''
получим список всех контактов, привзяанных к сдлекам, в виде
[
(ID сделки1, [контакт1, контакт2, ...]),
(ID сделки2, [контакт1, контакт2, ...]),
...
]
'''
contacts = b.get_by_ID('crm.deal.contact.item.get',
[d['ID'] for d in deals])
Метод get_by_ID()
возвращает список кортежей вида (ID, result)
, где result
- ответ сервера относительно этого ID
.
call()
Чтобы создавать, изменять или удалять список сущностей, используйте метод call()
:
# вставим в начало названия всех сделок их ID
tasks = [
{
'ID': d['ID'],
'NAME': f'{d["ID"]} - {d["NAME"]}'
}
for d in deals
]
b.call('crm.deal.update', tasks)
Метод call()
возвращает список ответов сервера по каждому элементу переданного списка.
Класс Bitrix
Объект класса Bitrix
создаётся, чтобы через него выполнять все запросы к серверу Битрикс24. Внутри объекта ведётся учёт скорости отправки запросов к серверу, поэтому важно, чтобы все запросы приложения отправлялись из одного экземпляра Bitrix
.
Под капотом все методы класса используют параллельные запросы и автоматическое построение батчей, чтобы ускорить получение данных.
Все методы будут поднимать исключения класса aiohttp.ClientError
, если сервер Битрикс вернул HTTP-ошибку, и RuntimeError
, если код ответа был 200
, но ошибка сдержалась в теле ответа сервера (да, иногда бывает и такое!).
Перед обращением к серверу во всех методах происходит проверка корректности параметров, передаваемых к серверу, и поднимается TypeError
или ValueError
при наличии ошибок.
Метод __init__(self, webhook: str, autobatch: bool = True, verbose: bool = True):
Создаёт экземпляр объекта Bitrix
.
Параметры
-
webhook: str
- URL вебхука, полученного от сервера Битрикс. -
autobatch: bool = True
- автоматически объединять списки запросов в батчи для ускорения обмена с сервером. -
verbose: bool = True
- показывать прогрессбар при выполнении запроса.
Метод get_all(self, method: str, params: dict = None)
Получить полный список сущностей по запросу method.
get_all()
самостоятельно обратывает постраничные ответы сервера, чтобы вернуть полный список.
Параметры
-
method: str
- метод REST API для запроса к серверу. -
params: dict
- параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24.
Возвращает полный список сущностей, имеющихся на сервере, согласно заданным методу и параметрам.
Метод get_by_ID(self, method: str, ID_list: list, params: dict = None)
Получить список сущностей по запросу method
и списку ID.
Используется для случаев, когда нужны не все сущности, имеющиеся в базе, а конкретный список поименованных ID, либо в REST API отсутствует способ получения сущностей одним вызовом.
Например, чтобы получить все контакты, привязанные к сделкам в работе, нужно выполнить следующий код:
deals = b.get_all('crm.deal.get', params={
'filter': {'CLOSED': 'N'}
})
contacts = b.get_by_ID('crm.deal.contact.item.get',
[d['ID'] for d in deals])
Параметры
-
method: str
- метод REST API для запроса к серверу. -
ID_list: list
- список ID, в отношении которых будут выполняться запросы. -
params: dict
- параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24.
Возвращает список кортежей вида:
[
(ID, <результат запроса>),
(ID, <результат запроса>),
...
]
Вторым элементом каждого кортежа будет результат выполнения запроса относительно этого ID. Это может быть, например, список связанных сущностей или пустой список, если не найдено ни одной привязанной сущности.
Метод call(self, method: str, item_list: list of dicts)
Вызвать метод REST API по списку.
Параметры
-
method: str
- метод REST API -
item_list: list of dicts
- список параметров вызываемого метода
call()
вызывает method
, последовательно подставляя в параметры запроса все элементы item_list
и возвращает список ответов сервера для каждого из отправленных запросов.
Контекстный менеджер slow
Иногда, когда серверу Битрикса посылается запрос, отбирающий много ресурсов сервера
(например, на создание 2500 лидов), то сервер не выдерживает даже стандартных
темпов подачи запросов, описанных в официальной документации, возвращая 500 Internal Server Error
после нескольких первых запросов.
В такой ситуации помогает замедление запросов при
помощи контекстного менеджера slow
:
# временно снижаем скорость до 0.2 запроса в секунду
slower_requests_per_second = 0.2
with fast_bitrix24.slow(slower_requests_per_second):
b.call('crm.lead.add', [{} for x in range(2500)])
# а теперь несемся с прежней скоростью
leads = b.get_all('crm.lead.list')
...
slow(requests_per_second: float = 0.5)
Снижает скорость запросов. По вызовам Bitrix, происходящим внутри выхова этого контекстного менеджера:
- скорость запросов гарантированно не превысит
requests_per_second
- механика "пула запросов" отключается - считается, что размер пула равен 0, и запросы подаются равномерно
После выхода из контекстного менеджера механика пула восстанавливается, однако пул считается пустым и начинает наполняться с обычной скоростью 2 запроса в секунду.
Параметры
requests_per_second: float = 0.5
- требуемая замедленная скорость запросов. По умолчанию 0.5 запросов в секунду.
Как связаться с автором
- e-mail: leshchenko@gmail.com
- telegram: https://t.me/leshchenko1979
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for fast_bitrix24-0.2.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e25a834e6513316864374cb802fcf42c6355ebe454ecfad202bdbb5ff89f2f5 |
|
MD5 | 8bfb6bd67bc6cfa21565aa712543cfe4 |
|
BLAKE2b-256 | 3b8a1b4f50db99b59b477aea2863fdfe11539291bd2410e32224311842c8765c |