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 unavailable
. - Размера батча контролируется для избежания ошибки HTTP
414 URI too long
. - Если сервер для сложных запросов начинает возвращать
500 Internal Server Error
, можно в одну строку понизить скорость запроосов.
Начало
Установите модуль через pip
:
pip install fast_bitrix24
Далее в python:
from fast_bitrix24 import *
# замените на ваш вебхук для доступа к 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()
и использовании методов вида *.get
:
'''
получим список всех контактов, привзяанных к сдлекам, в виде
[
(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
при наличии ошибок.
Метод __init__(self, webhook: str, verbose: bool = True):
Создаёт экземпляр объекта Bitrix
.
Параметры
-
webhook: str
- URL вебхука, полученного от сервера Битрикс. -
verbose: bool = True
- показывать прогрессбар при выполнении запроса.
Метод get_all(self, method: str, params: dict = None) -> list
Получить полный список сущностей по запросу method.
get_all()
самостоятельно обрабатывает постраничные ответы сервера, чтобы вернуть полный список.
Параметры
-
method: str
- метод REST API для запроса к серверу. -
params: dict
- параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24.get_all()
не поддерживает параметрыstart
,limit
иorder
.
Возвращает полный список сущностей, имеющихся на сервере, согласно заданным методу и параметрам.
Метод get_by_ID(self, method: str, ID_list: Sequence, ID_field_name: str = 'ID', params: dict = None) -> list
Получить список сущностей по запросу 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: Sequence
- список ID, в отношении которых будут выполняться запросы. -
ID_field_name
- название поля, в которое будут подставляться значения из спискаID_list
. По умолчанию'ID'
. -
params: dict
- параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24. Если среди параметров, указанных вparams
, указан параметрID
, то поднимается исключениеValueError
.
Возвращает список кортежей вида:
[
(ID, <результат запроса>),
(ID, <результат запроса>),
...
]
Первым элементом каждого кортежа будет ID из списка ID_list
. Вторым элементом каждого кортежа будет результат выполнения запроса относительно этого ID. Это может быть, например, список связанных сущностей или пустой список, если не найдено ни одной привязанной сущности.
get_by_ID()
гарантированно возвращает список такой же длины, как и поданный на вход ID_list
.
Метод call(self, method: str, item_list: Sequence) -> list
Вызвать метод REST API по списку. Самый универсальный метод,
применяемый, когда get_all
и get_by_ID
не подходят.
Параметры
-
method: str
- метод REST API -
item_list: Sequence
- список параметров вызываемого метода
call()
вызывает method
, последовательно подставляя в параметры запроса все элементы item_list
и возвращает список ответов сервера для каждого из отправленных запросов.
Контекстный менеджер slow
Иногда, когда серверу Битрикса посылается запрос, отбирающий много ресурсов сервера
(например, на создание 2500 лидов), то сервер не выдерживает даже стандартных
темпов подачи запросов, описанных в официальной документации, возвращая 500 Internal Server Error
после нескольких первых запросов.
В такой ситуации помогает замедление запросов при
помощи контекстного менеджера slow
:
# временно снижаем скорость до 0.2 запроса в секунду
slower_requests_per_second = 0.2
with 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
- создать новый github issue: https://github.com/leshchenko1979/fast_bitrix24/issues/new
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.3.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2971d4cc3af3c8dbf3cf5e61e1834c9bfa748d0ed696941aa08107754808a4b3 |
|
MD5 | 05b40ba5b96009cecbe15a1e58ec8c49 |
|
BLAKE2b-256 | 0d8364a8d9d1968515830b9ac6e52064cb597448ff7f8115184dd184dde91dce |