Package: fast-bitrix24
fast_bitrix24API wrapper для Питона для быстрого получения данных от Битрикс24 через REST API.Основная функциональностьНачало работыПримеры использованияКак это работаетСоветы и подсказкиКак связаться с авторомПодробный справочник по APIОсновная функциональностьВысокая скорость обмена даннымиНа больших списках скорость обмена данными с сервером достигает тысяч элементов в секунду.Автоматическая упаковка запросов в батчи сокращает количество требуемых запросов к серверу и ускоряет обмен данными.Батчи отправляются на сервер не последовательно, а параллельно.Продвинутые стратегии работы с постраничным доступом ускоряют выгрузку на порядки (см.результаты тестов).Избежание отказов сервераАвтоматический autothrottling - если сервер возвращает ошибки, скорость автоматически понижается.Если сервер для сложных запросов начинает возвращать ошибки, можно в одну строку понизить скорость запроосов.Удобство кодаВысокоуровневые списочные методы для сокращения количества необходимого кода. Большинство операций занимают только одну строку кода. Обработка параллельных запросов, упаковка запросов в батчи и многое другое убрано "под капот".Позволяет задавать параметры запроса именно в таком виде, как они приведены вдокументации к Bitrix24 REST API. Параметры проверяются на корректность для облегчения отладки.Выполнение запросов автоматически сопровождается прогресс-баром из пакетаtqdm, иллюстрирующим не только количество обработанных элементов, но и прошедшее и оставшееся время выполнения запроса.Синхронный и асинхронный клиентыНаличие асинхронного клиента позволяет использовать библиотеку для написания веб-приложений (например, телеграм-ботов).Нас используютЯндексНачало работыУстановите модуль черезpip:pipinstallfast-bitrix24Далее в python:fromfast_bitrix24importBitrix# замените на ваш вебхук для доступа к Bitrix24webhook="https://your_domain.bitrix24.ru/rest/1/your_code/"b=Bitrix(webhook)Методы полученного объектаbв дальнейшем используются для взаимодействия с сервером Битрикс24.Примеры использованияget_all()Чтобы получить полностью список сущностей, используйте метод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().get_by_ID()Если у вас есть список 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']fordindeals])Методget_by_ID()возвращает словарь с элементами видаID: result, гдеresult- ответ сервера относительно этогоID.call()Чтобы создавать, изменять или удалять список сущностей, используйте методcall():# вставим в начало названия всех сделок их IDtasks=[{'ID':d['ID'],'fields':{'TITLE':f'{d["ID"]}-{d["TITLE"]}'}}fordindeals]b.call('crm.deal.update',tasks)Методcall()возвращает список ответов сервера по каждому элементу переданного списка.call(raw=True)Вызовcallс парамтеромraw=Trueотправляет на сервер переданные ему параметры в оригинальном, необработанном виде (пропуская упаковку в батчи), и возвращает ответ сервера без какой-либо обработки.Подобный вызов можно использовать в отладочных целях, но кроме того, придется его использовать для отправки запросов, которые:в параметрах имеютNone(None применяется для стирания значения полей, а упаковка в батчи мешает передаватьNone),используют устревшие методы Битрикс24, которые принимают на вход список (см.#157).# стереть DESCRIPTION в лиде 123params={"ID":123,"fields":{"DESCRIPTION":None}}b.call('crm.lead.update',params,raw=True)# добавить комментарий к задачеb.call('task.commentitem.add',[123,{"POST_MESSAGE":"Комментарий к задаче"}],raw=True)call_batch()Если вы хотите вызвать пакетный метод, используйте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():fromfast_bitrix24importBitrixAsyncb=BitrixAsync(webhook)Все методы у него - синхронные аналоги методов изBitrix(), описанных выше:leads=awaitb.get_all('crm.lead.list')Как это работаетПеред обращением к серверу во всех методах классаBitrixпроисходит проверка корректности самых популярных параметров, передаваемых к серверу, и поднимаются исключенияTypeErrorиValueErrorпри наличии ошибок.Cоздаются запросы на получение всех элементов из запрошенного списка.Созданные запросы упаковываются в батчи по 50 запросов в каждом.Полученные батчи параллельно отправляются на сервер с регулировкой скорости запросов (см. ниже "Как fast_bitrix24 регулирует скорость запросов").Ответы (содержимое поля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регулирует скорость запросовПо умолчаниюfast_bitrix24игнорирует официальные ограничения Битрикс24 по скорости запросов (см. ниже "Официальная политика Битрикс24 по скорости запросов") и вместо этого начинает снижать скорость запросов, если сервер начинает возвращать ошибки (autothrottling). Подобный подход позволяет на порядки увеличить скорость получения данных (см.тесты скорости).Чтобы соблюдать официальные правила, при создании экземпляра классаBitrixукажите параметрrespect_velocity_policy=True.Официальная политика Битрикс24 по скорости запросовСуществует пул из 50 запросов, которые можно направить без ожидания.Пул пополняется со скоростью 2 запроса в секунду.При исчерпании пула и несоблюдении режима ожидания сервер возвращает ошибку.Советы и подсказкиА умеет ли ваша библиотека ...?Посмотрите всправочник по API. Если не нашли ответа,свяжитесь с автором.А как мне сформировать запрос к Битриксу, чтобы  ...?Поищите вофициальной документации по REST API.Если на ваш вопрос там нет ответа - попробуйте задать его вгруппе "Партнерский REST API" в Сообществе разработчиков Битрикс24.Спросите в Телеграме вгруппе разработчиков Битрикс24.Спросите в Телеграме вгруппе пользователей fast_bitrix24.Спросите нарусском StackOverflow.А как понять, что отправляется на сервер и что он возвращает?Включите логирование запросов и ответов сервера.importlogginglogging.getLogger('fast_bitrix24').addHandler(logging.StreamHandler())Я хочу добавить несколько лидов списком, но получаю ошибку сервера.Оберните вызовcall()вslow:withb.slow():results=b.call('crm.lead.add',tasks)См. подробнееоslow.Я хочу вызватьcall()только один раз, а не по списку.Передавайте параметры запроса методуcall(), он может делать как запросы по списку, так и единичный запрос:method='crm.lead.add'params={'fields':{'TITLE':'Чпок'}}b.call(method,params)Результатом будет ответ сервера по этому одному элементу.Однако, если такие вызовы делаются несколько раз, то более эффективно формировать из них список и вызыватьcall()единожды по всему списку.Как сортируются результаты при вызовеget_all()?Пока что никак.Все обращения к серверу происходят асинхронно и список результатов отсортирован в том порядке, в котором сервер возвращал ответы. Если вам требуется сортировка, то вам нужно делать ее самостоятельно, например:deals=b.get_all('crm.deal.list')deals.sort(key=lambdad:int(d['ID']))Я используюget_all()для получения всех полей всех элементов списка, но это происходит слишком долго. Как ускорить этот процесс?Попробуйте применить методlist_and_get()- он стабильно показывает на порядок лучшие результаты на больших объемах информации.См.результаты тестов.Я получаю ошибку сертификата SSL. Что делать?Если вы получаетеSSLCertVerificationError/CERTIFICATE_VERIFY_FAILED, попробуйте отключить верификацию сертификата SSL. При инициализации передайте вBitrixAsyncпараметрclient,  где будет инициализированный вами экземплярaiohttp.ClientSession, у которого будет отключена верификация SSL:importaiohttpimportasynciofromfast_bitrix24importBitrixAsyncasyncdefmain():# Инициализировать HTTP-клиента без верификации SSL и передать его в `BitrixAsync`connector=aiohttp.TCPConnector(ssl=False)asyncwithaiohttp.ClientSession(connector=connector)asclient:b=BitrixAsync(webhook,client=client)# Далее ваши вызовы Битрикса...asyncio.run(main())Как связаться с авторомtelegram:https://t.me/+U7hfrV7h53bRvKASсоздать новый github issue:https://github.com/leshchenko1979/fast_bitrix24/issues/new