Skip to content

Latest commit

 

History

History
199 lines (150 loc) · 14.2 KB

API.md

File metadata and controls

199 lines (150 loc) · 14.2 KB

Справочник по API fast_bitrix24

Класс Bitrix

Объект класса Bitrix создаётся, чтобы через него выполнять все запросы к серверу Битрикс24.

Внутри объекта ведётся учёт скорости отправки запросов к серверу, поэтому важно, чтобы все запросы приложения в отношении одного аккаунта с одного IP-адреса отправлялись из одного экземпляра Bitrix.

Метод __init__(self, webhook: str, token_func: Awaitable = None, verbose: bool = True, respect_velocity_policy: bool = True, request_pool_size: int = 50, requests_per_second: float = 2.0, batch_size: int = 50, operating_time_limit: int = 480, ssl: bool = True, client: aiohttp.ClientSession = None):

Создаёт клиента для доступа к Битрикс24.

Параметры

  • webhook: str - URL вебхука, полученного от сервера Битрикс.
  • token_func: Awaitable = None - ссылка на асинхронную функцию, возвращающаю OAuth-токен для запросов к серверу. Если не указана, то OAuth-авторизация не используется.
  • verbose: bool = True - показывать прогрессбар при выполнении запроса.
  • respect_velocity_policy: bool = True - соблюдать политику Битрикса о скорости запросов.
  • request_pool_size: int = 50 - размер пула запросов, который можно отправить на сервер без ожидания
  • requests_per_second: float = 2.0 - максимальная скорость запросов, которая будет использоваться после переполнения пула
  • batch_size: int = 50 - максимальное количество запросов, которые будут отправляться на сервер в одном батче
  • operating_time_limit: int = 480 - максимальное допустимое время отработки запросов к одному методу REST API в секундах, допустимое за 10 минут, после которого запросы будут замедляться
  • ssl: bool = True - использовать ли проверку SSL-сертификата при HTTP-соединениях с сервером Битрикс.
  • client: aiohttp.ClientSession = None - использовать для HTTP-вызовов клиента, инициализированного и настроенного пользователем.

Параметры request_pool_size и requests_per_second установлены согласно ограничениям Битрикс24.

Вы можете повысить их, если у вас Энтерпрайз (https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=93&LESSON_ID=7885).

Либо, если хотите снизить скорость запросов к серверу, вы можете понизить значение этих параметров.

Метод get_all(self, method: str, params: dict = None) -> list | dict

Получить полный список сущностей по запросу method.

get_all() самостоятельно обрабатывает постраничные ответы сервера, чтобы вернуть полный список (подробнее см. "Как это работает" выше).

Параметры

  • method: str - метод REST API для запроса к серверу.

  • params: dict - параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24. get_all() не поддерживает параметры start и order.

Возвращает полный список сущностей, имеющихся на сервере, согласно заданным методу и параметрам.

Метод get_by_ID(self, method: str, ID_list: Iterable, ID_field_name: str = 'ID', params: dict = None) -> dict

Получить список сущностей по запросу method и списку ID.

Используется для случаев, когда нужны не все сущности, имеющиеся в базе, а конкретный список поименованных ID, либо в REST API отсутствует способ получения сущностей одним вызовом.

Например, чтобы получить все контакты, привязанные к сделкам в работе, нужно выполнить следующий код:

deals = b.get_all(
    'crm.deal.list',
    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: Iterable - список ID, в отношении которых будут выполняться запросы.

  • ID_field_name: str - название поля, в которое будут подставляться значения из списка ID_list. По умолчанию 'ID'.

  • params: dict - параметры для передачи методу. Используется именно тот формат, который указан в документации к REST API Битрикс24. Если среди параметров, указанных в params, указан параметр ID, то поднимается исключение ValueError.

Возвращает словарь вида:

{
    ID_1: результат_выполнения_запроса_по_ID_1,
    ID_2: результат_выполнения_запроса_по_ID_2,
    ...
}

Ключом каждого элемента возвращаемого словаря будет ID из списка ID_list. Значением будет результат выполнения запроса относительно этого ID. Это может быть, например, список связанных сущностей или пустой список, если не найдено ни одной привязанной сущности.

Обратите внимание, что метод get_all() не может быть использован в сочетнии с группой методов REST API, начинающихся с task.elapseditem.*.

Метод list_and_get(self, method_branch: str, ID_field_name='ID') -> dict

!!! Метод устарел в связи с изменениями политики по ограничению скорости запросов Битрикса и будет удален в будущих версиях.

Скачать список всех ID при помощи метода method_branch + '.list', а затем значения всех полей всех элементов при помощи метода method_branch + '.get'. method_branch - группа методов, в которой есть подметоды *.list и *.get, например crm.lead.

Например:

all_lead_info = b.list_and_get('crm.lead')

Подобный подход показывает на порядок большую скорость получения больших объемов данных (полный набор полей на списках более 20 тыс. элементов), чем get_all() с параметром 'select': ['*', 'UF_*']. См. сравнение скоростей разных стратегий получения данных.

Параметры

  • method_branch: str - группа методов к использованию, например, "crm.lead".
  • ID_field_name='ID' - имя поля, в котором метод *.get принимает идентификаторы элементов (например, 'ID' для метода crm.lead.get)

Возвращает полное содержимое всех элементов в виде, используемом функцией get_by_ID() - словарь следующего вида:

{
    ID_1: <словарь полей сущности с ID_1>,
    ID_2: <словарь полей сущности с ID_2>,
    ...
}

Ограничения

list_and_get() не работает с теми группами методов, которые не поддерживают единое название поля с идентификатором в параметрах и результатах методов *.list и *.get.

Например, tasks.task.list в результатах идентификатор задачи возвращает в поле ID, но tasks.task.get принимает идентификаторы задач в поле taskId.

Метод call(self, method: str, items: dict | Iterable[dict] | Any = None, /, raw: bool = False) -> dict | list[dict] | Any

Вызвать метод REST API. Самый универсальный метод, применяемый, когда get_all и get_by_ID не подходят.

Параметры

  • method: str - метод REST API

  • items: dict | Iterable[dict] - параметры вызываемого метода. Может быть списком, и тогда метод будет вызван для каждого элемента списка, а может быть одним словарем параметров для единичного вызова.

  • raw: bool = False - режим обработки параметров запроса

    Если True, то items воспринимается как один элемент (даже если в items был передан список) и не заворачивается в батч. Требуется для работы со старыми методами, принимающими на вход параметры списком (tasks.elapseditem.*), а также для передачи значений None (которые плохо обрабатываются в батче). Подробней см. #199. При этом возвращается необработанный ответ сервера в виде словаря. По умолчанию - False.

    Если raw=False, то call() вызывает method, последовательно подставляя в параметры запроса все элементы items, и возвращает список ответов сервера для каждого из отправленных запросов. При этом запросы к Битриксу группируются в батчи. Либо, если items - не список, а словарь с параметрами, то происходит единичный вызов и возвращается его результат.

Метод call_batch(self, params: dict) -> dict

Вызвать метод batch (см. официальную документацию по методу batch).

Поддерживается примение результатов выполнения одной команды в следующей при помощи ключевого слова $result:

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]'
    }
})

Возвращает словарь вида:

{
    'имя_команды_1': результаты_выполнения_команды_1,
    'имя_команды_1': результаты_выполнения_команды_1,
    ...
}

Контекстный менеджер slow(max_concurrent_requests: int = 1)

Ограничивает количество одновременно выполняемых запросов к серверу Bitrix.

Иногда, когда серверу Битрикса посылается запрос, отбирающий много ресурсов сервера (например, на создание 2500 лидов), то сервер не выдерживает даже стандартных темпов подачи запросов, описанных в официальной документации, либо возвращая 500 Internal Server Error после нескольких первых запросов, либо вылетая по таймауту или разрыву соединения.

В такой ситуации помогает введение ограничений при помощи контекстного менеджера slow:

# временно ограничиваем скорость
# до 5 параллельно выполняемых запросов
max_concurrent_requests = 5
with b.slow(max_concurrent_requests):
    b.call('crm.lead.add', [{'NAME': x} for x in range(2500)])

# а теперь несемся с прежней скоростью
leads = b.get_all('crm.lead.list')
...

Параметры

  • max_concurrent_requests: int = 1 - макимальное количество одновременных запросов к серверу (по умолчанию 1).

Класс ErrorInServerResponseException(Exception)

Это исключение поднимается, когда ответ сервера содержал ошибки.