Локальные приложения

Локальные приложения лучше подходят для тех задач, которые требуют создания пользовательского интерфейса:

• различные отчеты;
• дополнительные автообработчики в рамках специфической бизнес-логики;
• решения, требующие управления доступом пользователей;
• чат-боты и приложения, расширяющие функционал мессенджера Битрикс24;
• дополнительные операции для автоматических бизнес-процессов Битрикс24.

Локальные приложения поддерживают все возможности REST API и вызывают REST по протоколу авторизации OAuth 2.0, но устанавливаются только на конкретном Битрикс24, без публикации в каталоге решений. Для добавления локального приложения требуется административный доступ.

Быстрый старт локального приложения.

  Webhooks

Вебхуки идеально подходят:

• для организации одноразового импорта-экспорта данных;
• простых интеграций с внешними и внутренними системами компании (ERP, учет рабочего времени, авто-мониторинг программных и аппаратных средств и т.д.);
• использования в автоматизации обработки лидов и сделок (триггеры и действия в CRM-роботах);

Использование вебхуков проще для технической реализации, поскольку не требует реализации протокола OAuth 2.0. Каждый пользователь может добавлять вебхуки "для себя" и REST API, вызываемый в рамках таких вебхуков, будет ограничиваться правами конкретного пользователя-владельца.

Быстрый старт с использованием вебхуков.

  Раздел Разработчикам

Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24:

Доступны следующие инструменты:

• Готовые сценарии
• Интеграции
• Статистика

Далее рассмотрим подробнее каждый из этих инструментов.

  Готовые сценарии

На этой вкладке представлены готовые сценарии для интеграции и доработки с примерами кода и предустановленными параметрами на базе вебхуков и локальных приложений.

В настройках каждого из сценариев есть генератор REST-запросов 1, с помощью которого можно подобрать нужные значения параметров для дальнейшего использования во внешних системах:

В генераторе запросов можно выбрать метод REST API, прочитать описание метода, скачать готовый пример кода (в примере уже есть необходимые параметры для выполнения запросов), добавить свои параметры. Здесь же можно выполнить сам запрос и получить результат, проверив работу вебхука.

Настройка прав доступа 2 позволяет разрешить выполнение запросов только определенным инструментам Битрикс24.

После сохранения созданные приложения и вебхуки будут отображаться во вкладке Интеграции.

  Интеграции

Все созданные интеграции (вебхуки и приложения) портала Битрикс24 выводятся единым списком на странице :

В этом списке выводится следующая информация об интеграциях:

• Кто создал
• Название
• Права доступа
• События
• Виджеты

Показ нужных полей можно настроить, кликнув по значку [dw]шестеренки[/dw][di] [/di] в левом верхнем углу списка.

Также из этого списка можно перейти к редактированию настроек интеграции (или удалить её).

  Статистика

В этом разделе выводится общее число ежедневных REST-запросов вашего Битрикс24, а также можно просмотреть детальную статистику по каждому вебхуку, внешней интеграции или приложению:

Установка

Пример состоит из SDK CRest и PHP-файла с примером, которые вы должны разместить на своем веб-сервере до добавления приложения в свой Битрикс24. Приложение умеет получать авторизацию пользователя Битрикс24 и используя ее, находясь при этом вне Битрикс24, обращаться к REST API, получая ФИО пользователя, установившего его.

Скачать архив:

Установить локальное приложение можно либо из раздела [ds]Разработчикам[/ds][di] Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24.

Подробнее...[/di] (Приложения > Разработчикам, вкладка «Готовые сценарии» > Другое > Локальное приложение), либо перейдя по цепочке: Приложения 1 – Разработчикам 2 – Другое 3 – Локальное приложение 4:

В открывшейся форме заполните базовые поля и укажите необходимые для приложения права (для нашего примера нужны права на управление пользователями), указав Путь вашего обработчика (это означает, что ваше приложение уже должно быть физически доступно по URL по протоколу HTTPS до того, как вы станете добавлять его в ваш Битрикс24)

Необходимо включить опцию Приложение использует только API – именно она указывает Битрикс24, что ваше приложение не будет показывать пользовательский интерфейс внутри Битрикс24. В этом случае, как вы увидите, в форме будут скрыты поля, в которых обычно указывается название пункта меню для вызова приложения из Битрикс24. Приложения, у которых включена опция "Приложение использует только API", либо предоставляют пользовательский интерфейс по какому-то своему URL, либо вообще не предоставляют пользовательский интерфейс.

Обратите также внимание на то, что мы заполнили поле Путь для первоначальной установки, указав install.php из архива с примером. Этот URL вызывается только один раз при сохранении формы локального приложения. Именно этот URL служит обработчиком события ONAPPINSTALL, в котором мы и сохраняем токены пользователя, установившего приложение.

После сохранения вы останетесь в форме добавления, но Битрикс24 вам сразу покажет ключи авторизации для протокола OAuth 2.0, которые вам потребуются внутри кода приложения:

Поскольку приложение без интерфейса работает "вне" Битрикс24, то оно должно реализовывать полный протокол авторизации OAuth 2.0. Откройте из примера файл settings.php и заполните константы с кодом приложения C_REST_CLIENT_ID и секретным ключом C_REST_CLIENT_SECRET, полученными при сохранении формы.

Загрузите измененный пример на свой сервер.

В Битрикс24 можно перейти в список «Интеграции» (Приложения > Разработчикам > Интеграции) и убедиться в появлении нового приложения в списке локальных приложений в вашем Битрикс24:

Использование

Откройте файл index.php из примера в браузере по вашему URL:

Запущенное приложение выведет ФИО установившего приложение пользователя, получая его по REST API с использованием авторизационных данных, сохраненных при создании приложения, а также автоматически продлевая токены (если при запросе окажется, что они недействительны).

Описание

Краткое описание механизма вебхуков: через пользовательский интерфейс Битрикс24 можно получить и зафиксировать ключ авторизации. Этот ключ в дальнейшем можно использовать для вызова методов REST, и при этом данный ключ не ограничивается по сроку действия (в отличие от токенов авторизации протокола OAuth 2.0).

Это делает вебхуки исключительно простым и удобным механизмом для работы с REST, но при этом надо понимать, что эта простота имеет и свои недостатки:

1. Для формирования вебхука требуется участие пользователя (вы не сможете генерировать вебхуки автоматически);
2. Поскольку срока действия у вебхука нет, то любая "утечка" URL вебхука чревата получением доступа к вашему Битрикс24 в рамках прав конкретного вебхука. Именно поэтому данный механизм годится для "внутренних" интеграций, но не подходит для тиражных вариантов использования;
3. Ряд методов REST недоступен для работы через вебхуки, поскольку их логика требует "контекста" приложения, а никакого приложения в терминах Битрикс24 для вебхуков нет (в частности, методы встраивания приложений в интерфейс Битрикс24, события телефонии, часть событий чат-ботов и т.д.).

Но несмотря на эти ограничения, для подавляющего большинства задач интеграции в рамках конкретного проекта вебхуки представляются идеальным вариантом работы с REST API.

  Создание Входящего вебхука

Входящий вебхук используется для работы с данными вашего Битрикс24 через API.

Создать входящий вебхук можно из раздела [ds]Разработчикам[/ds][di] Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24.

Подробнее...[/di] (Приложения > Разработчикам, вкладка "Готовые сценарии" > Другое > Входящий вебхук).

В открывшейся форме:

• измените название вебхука;
• в генераторе запросов выберите метод REST API (можно прочитать описание метода и скачать готовый пример кода с необходимыми параметрами для выполнения запросов);
• проверьте работу вебхука, нажав на кнопку Выполнить;
• укажите права доступа, разрешив выполнять запросы только определенным инструментам Битрикс24.

В генераторе запросов будет представлен образец URL, который нужно использовать при отправке данных из сторонней системы в Битрикс24

URL состоит из:

• doc-test-b24.bitrix24.ru - адрес вашего Битрикс24
• /rest - указание на то, что работа ведётся через rest с вебхуками
• /1 - идентификатор пользователя, создавшего вебхук
• /173glortu42lvpju - секретный код
  Внимание! Данный код является конфиденциальной информацией. Его необходимо держать в секрете.
  
  Секретные коды чужих вебхуков недоступны даже администратору. Если администратор отредактирует чужой вебхук, то секретный код будет сброшен, и владельцем этого вебхука станет администратор.

• /crm.contact.get - вызываемый метод [ds]REST API[/ds][di] Битрикс24 - программный продукт в виде облачного сервиса, а также коробочной версии, созданный компанией "1С-Битрикс".
  
  Разработчики могут создавать собственные приложения или интеграции для Битрикс24, используя открытый REST API, который работает как с облачным, так и с коробочным Битрикс24, а также с "1С-Битрикс: Управление сайтом" начиная с версии 16.6.0.
  
  Подробнее...[/di]. В данном случае - метод, возвращающий контакт по идентификатору
• .json - необязательный параметр ("транспорт"). При создании новых вебхуков можно не указывать (по умолчанию будет использоваться .json). В конструкторе готовых решений .json подставляется явно
• ?ID=42 - параметры, необходимые для конкретного метода. В данном случае - идентификатор. Параметры указываются после вопросительного знака и разделяются символом &

  Создание исходящего вебхука

Исходящий вебхук используется для получения информации о событиях, происходящих в вашем Битрикс24.

Создать исходящий вебхук можно из раздела [ds]Разработчикам[/ds][di] Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24.

Подробнее...[/di] (Приложения > Разработчикам, вкладка "Готовые сценарии" > Другое > Исходящий вебхук).

В открывшейся форме:

1. измените название вебхука;
2. укажите URL вашего обработчика - страницу на стороннем ресурсе, куда будет обращаться вебхук;
3. выберите событие, на которое будет инициализироваться вебхук.

При создании исходящего вебхука будет выведен токен в виде строки из случайных знаков. Этот код позволит внутри обработчика проверить, действительно ли обработчик вызван вашим Битрикс24.



4. На странице обработчика разместите код:

   Пример кода обработчика для события ONCRMDEALUPDATE

   <?
   print_r($_REQUEST);
   writeToLog($_REQUEST, 'incoming');
   /**
   	* Write data to log file.
   	*
   	* @param mixed $data
   	* @param string $title
   	*
   	* @return bool
   	*/
   function writeToLog($data, $title = '') {
   	$log = "\n------------------------\n";
   	$log .= date("Y.m.d G:i:s") . "\n";
   	$log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
   	$log .= print_r($data, 1);
   	$log .= "\n------------------------\n";
   	file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
   	return true;
   } 

   Для проверки откройте любую сделку на редактирование и сохраните изменения, в логе отобразится примерно такая история:

   2017.01.17 12:58:29
   incoming
   Array
   (
   	[event] => ONCRMDEALUPDATE
   	[data] => Array
   		(
   			[FIELDS] => Array
   				(
   					[ID] => 662
   				)
   
   		)
   
   	[ts] => ххх
   	[auth] => Array
   		(
   			[domain] => ххх.bitrix24.ru
   			[client_endpoint] => https://ххх.bitrix24.ru/rest/
   			[server_endpoint] => https://oauth.bitrix.info/rest/
   			[member_id] => ххх
   			[application_token] => ххх
   		)
   
   )

Создание

Архив с примером содержит SDK CRest, модификации SDK CRest для упрощенного варианта использования OAuth 2.0. Представляет собой готовое приложение, обращающееся к REST API и показывающее ФИО текущего пользователя. Другой пример такого приложения описан в уроке REST для sms.

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет необходимо в кабинете разработчика решений открыть [dw]Добавить приложение[/dw][di][/di], далее выбрать регион публикации. В открывшейся форме необходимо [dw]выбрать или добавить[/dw][di] [/di] версию приложения:

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

В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая [dw]тестовые установки[/dw][di][/di] на своих Битрикс24, и только потом подаете решение на модерацию.

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.

  Тестирование приложения

Для тестирования приложения, необходимо открыть [dw]Тестировать в версии приложения[/dw][di][/di] или [dw]Протестировать в приложении[/dw][di][/di]:

После установки приложения Битрикс24 сразу откроет его интерфейс. Вы также сможете переходить в приложение из соответствующего пункта левого меню или меню Еще в разделе Приложения. Запущенное [dw]приложение выведет[/dw][di] [/di] отладочную информацию о передаваемых авторизационных данных текущего пользователя, а также ФИО текущего пользователя, получая его по REST API с использованием этих авторизационных данных. Поскольку это приложение работает в интерфейсе Битрикс24 и использует авторизацию текущего пользователя, который открыл приложение, то оно действует исключительно только в рамках прав этого пользователя.

  Универсальный механизм отправки сообщений

Битрикс24 умеет отправлять SMS не только из бизнес-процессов и роботов CRM, но и из карточки CRM (которая доступна везде, включая бесплатный тариф без бизнес-процессов). Для решения этой задачи есть соответствующий специальный REST для служб сообщений. В первую очередь его используют для интеграции с SMS, но вообще это универсальный механизм и в дальнейшем его можно использовать для отправки сообщений в произвольные источники.

Авторам интеграций с SMS-провайдерами рекомендуется перевести свои приложения на новый REST, чтобы у пользователей не было проблем с установкой на бесплатном тарифе. И, несмотря на прозрачность вызовов существующих провайдеров для бизнес-процессов и роботов CRM, лучше работать с методами REST для службы сообщений. Тем более, что только эти методы позволят не только отправлять SMS, но и сообщать Битрикс24 о статусе отправленных сообщений. Этот статус пользователи видят прямо в карточке CRM (а в будущем увидят и в отчетах инструментов CRM-маркетинга).

Рассмотрим практический пример того, как можно быстро сделать интеграцию с SMS-провайдером.

Скачать архив примера:

  Для начала

Чтобы стать технологическим партнером 1С-Битрикс, достаточно заполнить анкету: указать общую информацию, а также данные для дальнейшей авторизации в партнерском кабинете.

Обратите внимание на поле Код партнера - это префикс, который будет подставляться в дальнейшем в символьный код, идентифицирующий ваши решения в нашем каталоге. Если взять в качестве примера решение по интеграции со Stripe https://www.bitrix24.ru/apps/?app=integrations24ru.stripe, то integrations24ru является как раз этим кодом партнера (разработчика решения), а код stripe является кодом конкретного решения, который вы укажите в дальнейшем при заполнении формы регистрации решения.

Поэтому желательно, чтобы код партнера был связан с названием вашей компании или продукта. Поменять его потом не получится, отнеситесь к его формированию вдумчиво и ответственно.

После заполнения анкеты вы сразу получите доступ в кабинет разработчика решений. Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет, необходимо открыть [dw]Добавить приложение[/dw][di][/di], далее выбрать регион публикации. В открывшейся форме необходимо [dw]выбрать или добавить[/dw][di] [/di] версию приложения:

Заполните доступные разделы системы (1) для данного примера значением "Сервис сообщений". Битрикс24 в этом случае будет сам вызывать наш провайдер из нужных точек в интерфейсе: из бизнес-процессов, из роботов CRM, из карточки CRM и так далее. Ознакомьтесь с правилами публикации (2). Это необходимо для понимая требований, которые накладываются на тиражные решения.

В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая [dw]тестовые установки[/dw][di][/di] на своих Битрикс24, и только потом подаете решение на модерацию.

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.

  Общая логика приложения

Приложение регистрирует в конкретном Битрикс24 некий обработчик. Когда пользователь (или автоматический процесс) на стороне Битрикс24 хочет отправить SMS, он дергает этот обработчик и передает в него текст и номер телефона получателя. Обработчик (зная параметры вызова API SMS-оператора) отправляет SMS. Вот такая простая схема:

В нашем примере, скрипт install.php запросит у пользователя параметры для подключения API SMS-оператора и сохраняет их на своей стороне в привязке к конкретному Битрикс24. В таблице БД, например. Этот же скрипт регистрирует так называемый "провайдер сообщений" в Битрикс24, обращаясь к соответствующему методу REST. Фактически, это и будет регистрацией обработчика, который реализуется в примере в файле handler.php по адресу https://mydomain.ru/sms/handler.php. Если регистрация прошла успешно, install.php должен завершить установку.

В дальнейшем приложение ожидает, когда Битрикс24 обратится к нему:

Обращение произойдет, если пользователь, допустим, решит отправить SMS из карточки CRM. В этом случае, handler.php получит целую кучу данных в массиве $_REQUEST:

requestArray
(
	[module_id] => crm
	[bindings] => Array
		(
			[0] => Array
				(
					[OWNER_TYPE_ID] => 1
					[OWNER_ID] => 5783
				)

		)

	[properties] => Array
		(
			[phone_number] => +9172012345
			[message_text] => тест
		)

	[type] => SMS
	[code] => fastsms
	[message_id] => e35864edce3eaad987d32f8955c1177b
	[message_to] => +9172012345
	[message_body] => тест
	[ts] => 1513177809
	[auth] => Array
		(
			[access_token] => x4o81wfl4g57qur2u8sjrlcha76zn0tj
			[expires_in] => 3600
			[scope] => messageservice
			[domain] => restapi.bitrix24.ru
			[server_endpoint] => https://oauth.bitrix.info/rest/
			[status] => F
			[client_endpoint] => https://restapi.bitrix24.ru/rest/
			[member_id] => da45a03b265edd8787f8a258d793cc5d
			[user_id] => 1
			[application_token] => 127acc1c34feccc4da8fbf5020856f12
		)

)

Нас интересует:

• адресат message_to,
• текст сообщения message_body,
• внутренний идентификатор сообщения message_id, который потребуется для того, чтобы в дальнейшем отдельно сообщать в Битрикс24 о статусе доставки,
• параметры авторизации в массиве auth для работы с REST Битрикс24.

Обработчик, получив данные о сообщении, должен:

1. обратиться к API SMS провайдера, чтобы отправить сообщение,
2. запомнить id-сообщения и привязку к конкретному Битрикс24 где-то у себя в некой очереди.

Можно и не запоминать, но тогда приложение не сможет во всей полноте реализовать хорошие пользовательские сценарии. Так как статус доставки SMS-сообщения становится известным только через некоторое время (иногда это могут быть часы), мы не сможем прямо из handler.php тут же сообщить в Битрикс24 о результате доставки. Приложению придется делать это отдельно, и для этого в архиве примера есть файл statuses.php. Подразумевается, что какой-то менеджер заданий обращается к этому файлу с некой периодичностью и этот скрипт «смотрит» на очередь отправленных SMS и по каждому из них пытается узнать статус доставки, обращаясь к API SMS-провайдера:

О результатах он сообщает в Битрикс24, и удаляет из очереди обработанные сообщения.

  Отладка

Для тестирования приложения, необходимо открыть [dw]Тестировать в версии приложения[/dw][di][/di] или [dw]Протестировать в приложении[/dw][di][/di]:

После нажатия "Установить" откроется указанный Битрикс24 на странице установки приложения. [dw]Установите приложение[/dw][di][/di].

Нажмите “Save”, приложение будет считаться установленным (о техническом завершении - ниже), и Битрикс24 автоматически откроет уже основной интерфейс приложения index.php. В архиве примера этот интерфейс не сильно отличается от интерфейса установки и должен «подхватывать» сохраненные параметры авторизации SMS-провайдера. Но, поскольку это просто «заготовка» для приложения, а не работающая интеграция с конкретным провайдером, то мы увидим просто форму для ввода ключа.

  Волшебный код

Начнем с install.php. Когда Битрикс24 показывает во фрейме скрипт приложения (это касается как скрипта установки, так и основного скрипта приложения), то он передает в массив $_REQUEST все необходимые для OAuth 2.0 параметры авторизации. Следовательно, мы их можем схватить и сохранить на стороне приложения для дальнейшего использования. Именно это и происходит в коде при формировании hidden-полей:

<form id="sms-settings">
	<input type="hidden" name="save" value="Y">
	<input type="hidden" name="access_token" value="<?=$_REQUEST['AUTH_ID'];?>">
	<input type="hidden" name="refresh_token" value="<?=$_REQUEST['REFRESH_ID'];?>">
	<input type="hidden" name="domain" value="<?=$_REQUEST['DOMAIN'];?>">
	<input type="hidden" name="member_id" value="<?=$_REQUEST['member_id'];?>">
	<div class="form-group">
		<label for="sms_token">API-key FastSMS</label>
		<input type="text" class="form-control" name="sms_token" id="sms_token" placeholder="FastSMS API token">
	</div>
	<button type="submit" class="btn btn-primary btn-lg btn-save">Save</button>
</form>

Далее, мы делаем обработчик onsubmit, который позволит перехватить нажатие на кнопку "Save".

$('#sms-settings').submit(function(e){

	e.preventDefault();
	// 1. сохраняем данные авторизации на стороне приложения, чтобы в
	// дальнейшем использовать их для отправки смс


	// 2. прописываем обработчик для провайдера
	var params = {
		CODE: 'fastsms',
		TYPE: 'SMS',
		HANDLER: 'https://mydomain.ru/sms/handler.php',
		NAME: 'Provider FastSms',
		DESCRIPTION: 'Description sms provider'
	};

	BX24.callMethod(
		'messageservice.sender.add',
		params,
		function(result)
		{
			if(result.error())
				{
					alert("Error: " + result.error());
				}
			else
				{
				// Обработчик для провайдера прописан успешно

				// 3. заканчиваем процедуру установки на стороне Битрикс24
				BX24.installFinish();
				}
			}
	);
});

В этом обработчике можно прописать свой механизм сохранения нужных параметров. А далее зарегистрируйте тот самый обработчик, обращаясь для этого к методу messageservice.sender.add. Если регистрация прошла успешно, мы вызываем метод installFinish, который сообщает Битрикс24 об успешном завершении установки.

В index.php все то же самое, та же форма настроек, та же обработка события onsubmit, в которой вам придется писать свой код сохранения настроек и параметров авторизации. Но тут уже нет никакого installFinish, потому что приложение уже установлено:

$('#sms-settings').submit(function(e){

	e.preventDefault();
	// сохраняем данные авторизации на стороне приложения, чтобы в
	// дальнейшем использовать их для отправки смс


});

Код в handler.php. В примере просто сохраняется то, что нам передает Битрикс24 в лог:

CRest::setLog($_REQUEST, 'handler');
print_r($_REQUEST);

Но вы можете здесь обращаться к API провайдера SMS, инициируя отправку SMS теми средствами, которые вам предоставит оператор. Пример содержимого массива $_REQUEST есть выше.

Самое сложое находится в файле statuses.php. Подразумевается, что этот файл будет вызываться с некой периодичностью и он должен уметь обращаться к некой очереди, которую вы должны сделать самостоятельно. И получая из этой очереди информацию об отправленных SMS-сообщениях, он должен дергать API SMS-провайдера, получать от него статус доставки и передавать его обратно в Битрикс24. Для этого придется в очереди запоминать как ID-сообщения, который присылает Битрикс24, так и соответствующий ему ID-сообщения на стороне SMS-оператора. Посмотрим на код:

require_once(__DIR__ . '/crest.php');

/**
 * message_id полученный в handler.php
 */
$messageId = '520108d3dabbe6e98586549f467cab8d';

/**
 * sms status: delivered, undelivered, failed
 */
$status = 'delivered';

$result = CRest::call(
	'messageservice.message.status.update',
	[
		'CODE' => 'fastsms',
		'message_id' => $messageId,
		'status' => $status,
	]
);


echo "<pre>"; print_r($result); echo "</pre>";

if (isset($result['error'])) {
	// что-то пошло не так, анализируем ошибку и реагируем на нее
}

Представим, что на каждом шаге цикла обработки очереди мы получили из очереди $messageId , потом вытащили оттуда же название домена Битрикс24 и токены, которые передадим в getSettingData/setSettingData переопределив методы для работы с несколькими Битрикс24. Домен и access_token нам нужны, чтобы обратиться к REST Битрикс24. Это простой HTTP-запрос, в котором указывается домен Битрикс, название нужного метода (в нашем случае это метод messageservice.message.status.update для обновления статуса доставки), параметры метода и токен авторизации access_token.

Для автоматического продления токенов необходимо заполнить константы: C_REST_CLIENT_ID (1) и C_REST_CLIENT_SECRET (2). Значения для [dw]этих констант[/dw][di]Такая пара ключей действует на всех Битрикс24, на которых потом будет устанавливаться ваше приложение.[/di] вам нужно взять из карточки приложения:

Используйте функцию CRest::call(). Она получает название нужного метода REST, параметры для этого метода и токены авторизации из методов getSettingData/setSettingData.

Используйте стандартную заготовку в виде архива примера, адаптируйте к реальному оператору SMS и публикуйте решения в каталоге Битрикс24.Маркет.

Создание

Архив с примером содержит SDK CRest и два файла, которые представлят собой готовое приложение. Приложение обращается к REST API, встраивает всплывающие диалоги в списки контактов и компаний CRM и выводит данные объекта CRM, выбранного пользователем.

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет, необходимо в кабинете разработчика решений открыть [dw]Добавить приложение[/dw][di][/di], далее выбрать регион публикации. В открывшейся форме необходимо [dw]выбрать или добавить[/dw][di] [/di] версию приложения:

Заполните доступные разделы системы (1) для данного примера значениями "CRM", "Пользователи", "Встраиваемые приложения". Ознакомьтесь с правилами публикации (2). Это необходимо для понимая требований, которые накладываются на тиражные решения.

В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая [dw]тестовые установки[/dw][di][/di] на своих Битрикс24, и только потом подаете решение на модерацию.

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.

  Тестирование приложения

Для тестирования приложения, необходимо открыть [dw]Тестировать в версии приложения[/dw][di][/di] или [dw]Протестировать в приложении[/dw][di][/di]:

Укажите адрес вашего тестового Битрикс24 (1) и нажмите кнопку "Установить" (2). После установки приложения Битрикс24 выдаст сообщение "Приложение не найдено". Это нормальная ситуация, поскольку у нашего примера включена опция "Использовать только API" и оно ещё не опубликовано в публичном каталоге. Когда ваше приложение будет доступно в каталоге Битрикс24.Маркет, то Битрикс24 после установки будет оставлять пользователя на странице с описанием приложения.

Перейдите в список контактов или компаний. В контекстном меню любого контакта или компании в подменю "Приложения" теперь доступен пункт [dw]"Public embedded form"[/dw][di][/di], при нажатии на который откроется слайдер с приложением.

Приложение [dw]выведет отладочную информацию[/dw][di][/di] о передаваемых авторизационных данных текущего пользователя, а также данные контакта (или компании, если его вызвать из списка компаний CRM), получая их по REST API с использованием этих авторизационных данных. Поскольку это приложение работает в интерфейсе Битрикс24 и использует авторизацию текущего пользователя, который открыл приложение, то оно действует исключительно только в рамках прав этого пользователя.

  Создание записи приложения в Маркетплейсе

Пример состоит из SDK CRest и PHP-файла с примером, которые вы должны разместить на своем веб-сервере до добавления приложения в свой Битрикс24. Приложение умеет получать авторизацию пользователя Битрикс24 и используя ее, находясь при этом вне Битрикс24, обращаться к REST API, получая ФИО пользователя, установившего приложение.

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет, необходимо в кабинете разработчика решений открыть [dw]Добавить приложение[/dw][di][/di], далее выбрать регион публикации. В открывшейся форме [dw]выбрать или добавить[/dw][di] [/di] версию приложения:

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

В отличие от локальных приложений, тиражные решения состоят из версий. Каждая версия в дальнейшем подается на модерацию. (При модерации версии проверяется и карточка приложения). На этапе разработки и тестирования модерация не нужна, вы сами занимаетесь разработкой и доведением своего решения до полнофункционального состояния, включая [dw]тестовые установки[/dw][di][/di] на своих Битрикс24, и только потом подаете решение на модерацию.

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.

  Тестирование приложения

Для тестирования приложения, необходимо открыть [dw]Тестировать в версии приложения[/dw][di][/di] или [dw]Протестировать в приложении[/dw][di][/di]:

Нажмите на ссылку и введите адрес такого Битрикс24, вы будете перенаправлены на процедуру установки, которая полностью воспроизводит последовательность действий пользователей, устанавливающих уже опубликованные решения:

Для автоматического продления токенов необходимо заполнить в файле settings.php константы: C_REST_CLIENT_ID (1) и C_REST_CLIENT_SECRET (2). Значения для [dw]этих констант[/dw][di]Такая пара ключей действует на всех Битрикс24, на которых потом будет устанавливаться ваше приложение.[/di] вам нужно взять из карточки приложения:

Откройте index.php примера в браузере по вашему URL: приложение выведет Фамилию Имя текущего пользователя, получив его по REST API с использованием авторизационных данных, полученных при установке приложения.

Описание

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Битрикс24.Маркет, необходимо в кабинете разработчика решений открыть [dw]Добавить приложение[/dw][di][/di], далее выбрать регион публикации. В открывшейся форме [dw]выбрать или добавить[/dw][di] [/di] версию приложения:

После добавления версии приложения необходимо заполнить название (1) код приложения (2), категории (3), описание приложения (4), ценовую политику (5) и протестировать (6):

Смысл части обязательных полей понятен из названия, поясним то, что может вызвать затруднения.

В отличие от локальных приложений, у каждого тиражного решения необходимо задать уникальный символьный код. Код состоит из двух частей: вашего уникального символьного кода партнера (указывается в партнерской карточке) и части, которую вы присваиваете конкретному создаваемому приложению (2 на рис. выше).

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

Для некоторых стран или регионов в Битрикс24.Маркет существует возможность публикации платных приложений по модели подписки Битрикс24. Маркет Плюс.

Можно сразу привязать свое решение к нужной категории решений (3). Эти категории служат для навигации пользователей по [dw]каталогу решений[/dw][di][/di].

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

Ознакомьтесь с правилами публикации. Это необходимо для понимая требований, которые накладываются на тиражные решения.

Сохраните карточку приложения, заполнив все необходимые поля. Первый шаг сделан - фактически, вы подготовили описательную часть вашего будущего приложения. Теперь необходимо сформировать ту часть, которая отвечает за техническую реализацию.

  Версии приложения

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

При создании нового решения нам необходимо [dw]создать[/dw][di][/di](2) первую версию приложения. В открывшейся форме заполните базовые поля и укажите необходимые для приложения права. (Нужно выбирать только права на те модули Битрикс24, которые фактически используются вашим решением). Далее загрузите архив с приложением, или укажите URL внешнего приложения:

После сохранения вы увидите сообщение Изменения сохранены, а закрыв слайдер с версией, увидите заполненное версией решение.

Когда ваша версия будет полностью готова к публикации, то есть будет находиться на рабочем сервере, вы сами удостоверитесь в её работоспособности, проверите описания и материалы на соответствие регламентам Приложений24 и т.д., необходимо подать ее на модерацию.

Для этого откройте страницу Мои приложения и в списке решений в столбце Статус нажмите на модерацию. Откроется слайдер с проверкой приложения перед отправкой на модерацию, если нет замечаний нажмите "Отправить", иначе необходимо исправить все замечания перед отправкой решения на модерацию. Ваше решение попадет в соответствующую очередь и будет рассмотрено модераторами. Если они найдут какие-то недочеты или несоответствие правилам, они свяжутся с вами через механизм "Обсуждений".

Базовый

Этот вариант состоит в том, что если у вашего приложения не включена опция "Использовать только API", то внутри Битрикс24, на котором установлено приложение, будет добавлена отдельная страница, на которой в IFRAME будет выводиться index.html статичного приложения или открываться URL вашего серверного приложения. 

Из IFRAME нельзя получить доступ к родительскому окну. Это большой плюс с точки зрения безопасности, но минус с точки зрения усложнения разработки. Снять ограничения работы в IFRAME помогает JavaScript-библиотека функций. Например:

• для изменения окна IFRAME используются функции BX24.resizeWindow, BX24.setTitle, BX24.getScrollSize.
• для вызова нативных интерфейсов служат BX24.selectUser, BX24.selectUsers, BX24.selectAccess.

Встраивание

Помимо основного независимого интерфейса самого приложения на отдельной странице, ваше приложение может добавлять функционал в специальные отведенные области стандартного интерфейса: карточки объектов CRM, различные списки элементов и т.д.

Для этого установите обработчик места встраивания при помощи placement.bind. Одно приложение может установить произвольное число обработчиков, даже для одного и того же места встраивания (например, если вам нужно добавить несколько разных операций в контекстное меню лида в CRM).

Обработчик ограничен условиями:

• запрос на установку обработчика должен выполняться с авторизацией администратора,
• обработчик лежит в том же домене, что и зарегистрированный redirect_uri приложения
• каждый placement привязан к праву доступа (scope). Чтобы установить обработчик места встраивания в интерфейсе CRM, дайте приложению доступ к CRM. Кроме этого, у приложения должен быть указан непосредственно scope механизма встраивания - placement.

Метод при установке обработчика определяет места встраивания приложения. При разработке контекстных приложений учитывайте, что у каждого места встраивания могут быть свои особенности отображения и свой js-интерфейс. Например, места встраивания CRM_*_LIST_MENU представляют собой слайдеры, открывающиеся из контекстного меню соответствующих сущностей CRM, а CALL_CARD будет представлять собой переключатель приложений в виде табов в карточке звонка.

Текущий доступный список мест для встраивания описан в справочнике по REST API.

Пример вызова:

http://portal.bitrix24.com/rest/placement.bind/?access_token=sode3flffcmv500fuagrprhllx3soi72
	&PLACEMENT=CRM_CONTACT_LIST_MENU
	&HANDLER=http%3A%2F%2Fwww.applicationhost.com%2Fplacement%2F
	&TITLE=Тестовое приложение

HTTP/1.1 200 OK

{
	"result": true
}

В конце установки приложения используйте функцию BX24.installFinish. Она сигнализирует об окончании работы инсталлятора или настройщика приложения.

Результат вызова - в контекстном меню списка контактов появляется пункт меню Приложения с подпунктом Тестовое приложение.

Как работает встроенное приложение

В примере выше при клике по пункту приложения будет открыт слайдер с приложением. В слайдере будет отображен фрейм, в который будет загружено приложение по заданному адресу обработчика. Работа в этом фрейме мало чем отличается от работы приложения на отдельной странице (базовый вариант добавления интерфейса), за несколькими небольшими исключениями:

• Не везде будет разрешено менять размер фрейма или влиять на родительское окно, методы BX24.resizeWindow, BX24.fitWindow, BX24.scrollParentWindow, BX24.reloadWindow заблокированы.
• Данные о контексте вызова обработчика плейсмента будут переданы в POST-данных при вызове обработчика и доступны через js-библиотеку посредством метода BX24.placement.info.

Вот что получится для простейшего обработчика с кодом:

echo '<pre>'; print_r($_REQUEST); echo '</pre>';

При встраивании в меню приложению не предоставляется никакого дополнительного интерфейса. Это неудивительно, учитывая, что слайдер перекрывает интерфейс под собой и не дает никак с ним работать, пока приложение открыто.

JS методы встраивания приложений доступны и при встраивании в интерфейс и на обычной странице приложения с фреймом. В этом случае места встраивания передаются как DEFAULT, а параметры контекста вызова - как GET-параметры страницы.

Для открытия приложение используйте метод BX24.openApplication, для закрытия - BX24.closeApplication

Создание типа поля и поля

Зарегистрируйте тип поля.

Создайте пользовательское поле вручную, либо через API. Например, для Лидов CRM используется crm.lead.userfield.add.

Обработка данных во фрейме

Когда открывается форма, допустим, карточка лида в CRM, в которой выводится поле нашего пользовательского типа, то в карточке, фактически, выводится фрейм с приложением. В этот фрейм передаются все данные о поле, значении и режиме работы. Для приложения все выглядит так, как если бы оно было открыто в месте встройки с идентификатором USERFIELD_TYPE.

Вот пример POST-данных, пришедших в фрейм:

Array
(
	[DOMAIN] => sometestportal.bitrix24.com
	[PROTOCOL] => 1
	[LANG] => ru
	[APP_SID] => 14d2c95b446cb049375e4a045dc2a177
	[AUTH_ID] => xomlj71xez3p4q8bqsb5icqjcgjetf0p
	[AUTH_EXPIRES] => 3600
	[REFRESH_ID] => 51556ja184k22cqot442w0lp1quxg0p2
	[member_id] => 6f61b5484aff6f8aa3fef768153d0226
	[status] => L
	[PLACEMENT] => USERFIELD_TYPE
	[PLACEMENT_OPTIONS] => {"MODE":"view","ENTITY_ID":"CRM_LEAD","FIELD_NAME":"UF_CRM_1511508634350","ENTITY_VALUE_ID":"2","VALUE":["\u0435\u0445\u0430\u043b \u0433\u0440\u0435\u043a\u0430 \u0447\u0435\u0440\u0435\u0437 \u0440\u0435\u043a\u0443","\u0432\u0438\u0434\u0438\u0442 \u0433\u0440\u0435\u043a\u0430 \u0432 \u0440\u0435\u043a\u0435 \u0440\u0430\u043a","c\u0443\u043d\u0443\u043b \u0433\u0440\u0435\u043a\u0430 \u0440\u0443\u043a\u0443 \u0432 \u0440\u0435\u043a\u0443","\u0440\u0430\u043a \u0437\u0430 \u0440\u0443\u043a\u0443 \u0433\u0440\u0435\u043a\u0430 \u0446\u0430\u043f"],"MULTIPLE":"Y","MANDATORY":"N","XML_ID":null}
)

Детально разберём json-строку PLACEMENT_OPTIONS:

Array
(
	[MODE] => view
	[ENTITY_ID] => CRM_LEAD
	[FIELD_NAME] => UF_CRM_1511508634350
	[ENTITY_VALUE_ID] => 2
	[VALUE] => Array
		(
			[0] => ехал грека через реку
			[1] => видит грека в реке рак
			[2] => cунул грека руку в реку
			[3] => рак за руку грека цап
		)

	[MULTIPLE] => Y
	[MANDATORY] => N
	[XML_ID] => 
)

Ключи:

js-интерфейс

Для поля также доступен js-интерфейс получения и установки значения:

Вызов метода:

BX24.placement.call('getValue', function(value){console.log(value)});

Результат выполнения метода:

["ехал грека через реку", "видит грека в реке рак", "cунул грека руку в реку", "рак за руку греку цап"]

Вызов метода:

BX24.placement.call('setValue', ["ехал грека через реку", "видит грека в реке рак", "cунул грека руку в реку", "рак за руку греку цап"], function(){console.log('value set')});

Результат выполнения метода:

value set

Нужно учитывать, что js-интерфейс служит исключительно для передачи данных в форму. Пока форма тем или иным способом не будет сохранена пользователем, значение в базу не попадет.

Демо-приложение

Демо-приложение, которое регистрирует обычное текстовое поле со своим интерфейсом ввода и вывода. Скачать

Особенность коробки Битрикс24

В облачном Битрикс24 всегда доступен REST "самой последней версии". Однако бывает, что обновления для коробочной версии выходят через некоторое время после появления в облаке, в связи с тем, что коробочный Битрикс24 содержит дополнительный функционал, на тестирование совместимости с которым требуется дополнительное время.

Более того, в случае с конкретной коробочной установкой нет гарантии, что владелец установил последние доступные обновления и в целом установил нужные для приложения модули Битрикс24 (например, никто не мешает в коробочном Битрикс24 совсем отключить модуль телефонии). А значит, при установке приложения нет уверенности в доступности конкретных методов REST.

Поэтому рекомендация номер 1 - в скрипте установки своего решения проверяйте перечень доступных методов и событий, обращаясь к методам methods и events, и информируйте пользователя о том, что ему нужно поставить обновления на Битрикс24

Сервер авторизации Битрикс24

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

либо к серверу авторизации

В случае облачного Битрикс24 одинаково хорошо сработают оба варианта, поскольку облачный Битрикс24 просто будет "прокидывать" ваш запрос к реальному серверу авторизации, однако коробочный Битрикс24 этого может и не сделать.

Поэтому рекомендация номер 2 - для обновления токенов всегда обращайтесь только напрямую к серверу авторизации. Это будет работать и для облака, и для коробки.

Сетевые ограничения

Обращаясь к REST-методам, ваше приложение выполняет запрос к конкретному Битрикс24. Однако события REST в любом случае проходят в ваше приложение не напрямую из конкретного Битрикс24, а через очередь событий, которая находится в облаке, даже если речь идет о коробочном Битрикс24.

Возможна ситуация, когда владелец коробочного Битрикс24 по каким-то соображениям закрыл сетевой доступ к серверу очереди событий. В этом случае, события просто не будут работать. Если вы внедряете решение, общаясь с клиентом, то нужно рекомендовать внести адрес сервера очередей в белый список.

То же самое касается и сервера авторизации. Если сетевой доступ к нему закрыт, то REST работать в коробочном Битрикс24 не будет, поскольку коробочный Битрикс24 не сможет валидировать токен, с которым к нему обращается ваше приложение.

Есть альтернативный вариант, когда вы специально для конкретного клиента на стороне его коробочного Битрикс24 подключите свой механизм авторизации и событий. Подробнее о таком способе было рассказано в докладе Максима Сидоренко:

Изолированная коробка

Работа приложений в коробочном Битрикс24, закрытом от внешней сети.

Политика безопасности компаний может иметь самые разные ограничения для внутренних и внешних сетевых ресурсов, из-за чего приложения на REST для Битрикс24 не всегда могут "достучатся" до коробочного Битрикс24 или внешних облачных сервисов. Тем не менее, существует решение, которое позволяет разрабатывать приложения на стандартном REST API для Битрикс24 даже в таких случаях.

Обращения к внешним ресурсам

В работе Rest-приложения есть три момента, когда происходит обращение из портала во вне:

1 - Валидатор авторизации
2 - Провайдер авторизации
3 - Провайдер событий

Рассмотрим способы, которые позволят избежать обращений к внешним ресурсам.

Валидатор авторизации

Создадим свой обработчик событий

<?php
namespace Demo\AuthProvider;

class AuthSimple
{
	const AUTH_TYPE = 'demo_simple';

	const AUTH_PARAM_NAME = 'secret_word';
	const AUTH_PARAM_VALUE = 'MySuperSecurePassword123456';

	public static function onRestCheckAuth(array $query, $scope, &$res)
	{
		if(array_key_exists(static::AUTH_PARAM_NAME, $query))
		{
			$res = array('error' => 'INVALID_CREDENTIALS', 'error_description' => 'Invalid request credentials');

			return false;
		}

		return null;
	}
}

На вход валидатор получает все полные данные запроса приложения. Если в запросе нет параметра secret_word, то он отвечает return null, то есть: "не мой запрос". Если этот параметр в запросе присутствует, то обработчик проверяет запрос по значению. Если значение существует, но не соответствует сохранённому, то в ответ сообщается: "да, запрос мой, но неверное значение". Если значение верное, то он сообщает ID пользователя, список доступных скоупов, указывает, какие параметры нужно удалить, прежде чем отдавать запрос разработчику, и сообщает идентификатор типа авторизации, так как некоторые методы имеют ограничение по типам авторизации.

После этого обработчиком вызывается метод модуля REST, который авторизует на данном хите пользователя. Если всё прошло хорошо, то возвращается true.

Провайдер событий

Отнаследуем оригинальный класс провайдера событий и укажем что он реализует интерфейс провайдера событий. В своём классе мы переопределим только одну функцию send, которая и занимается отправкой. В данном примере покажем, как в случае необходимости вызвать внешний обработчик мы вместо обращения к внешней очереди событий, будем выполнять прямой http-запрос обработчика ($http->post(...))

<?php
namespace Demo\AuthProvider;

use Bitrix\Rest\Event\ProviderInterface;
use Bitrix\Rest\Event\ProviderOAuth;
use Bitrix\Rest\Event\Sender;

class EventProvider extends ProviderOAuth implements ProviderInterface
{
	public static function onEventManagerInitialize()
	{
		Sender::setProvider(static::instance());
	}

	public function send(array $queryData)
	{
		$http = new \Bitrix\Main\Web\HttpClient();
		foreach($queryData as $key => $item)
		{
			if($this->checkItem($item))
			{
				$http->post($item['query']['QUERY_URL'], $item['query']['QUERY_DATA']);
				unset($queryData[$key]);
			}
		}

		if(count($queryData) > 0)
		{
			parent::send(array_values($queryData));
		}
	}

	protected function checkItem(array $item)
	{
		return AuthProvider::instance()->checkClient($item['client_id']);
	}
}

В обработчике проверяется весь массив вызова событий на предмет того, наше ли это приложение и наш ли обработчик. Если это не наше приложение, то запрос будет переадресован родительскому классу, если наше, то на этом же хите будет совершён post запрос к приложению. Затем зарегистрируем новый провайдер событий в качестве основного и вызовем событие.

Провайдер авторизации

Самая сложная часть.

Принцип прежний: отнаследуется оригинальный класс провайдера и создастся свой класс провайдера, реализующий нужный нам альтернативный интерфейс провайдера авторизации.

<?php
namespace Demo\AuthProvider;


use Bitrix\Main\Context;
use Bitrix\Main\NotImplementedException;
use Bitrix\Main\ObjectNotFoundException;
use Bitrix\Main\Security\Random;
use Bitrix\Rest\Application;
use Bitrix\Rest\AppTable;
use Bitrix\Rest\AuthProviderInterface;
use Bitrix\Rest\OAuth\Provider;
use Bitrix\Rest\RestException;

class AuthProvider extends Provider implements AuthProviderInterface
{
	const TOKEN_TTL = 3600;
	const TOKEN_PREFIX = 'demo.';

	protected $applicationList = array();

	/**
	 * @var AuthProvider
	 */
	protected static $instance = null;

	/**
	 * @var AuthStorageInterface
	 */
	protected $storage;

	/**
	 * @return AuthProvider
	 */
	public static function instance()
	{
		if(static::$instance === null)
		{
			static::$instance = new static();
		}

		return static::$instance;
	}

	public static function onApplicationManagerInitialize()
	{
		Application::setAuthProvider(static::instance());
	}

	public function get($clientId, $scope, $additionalParams, $userId)
	{
		if(!$this->checkClient($clientId))
		{
			return parent::get($clientId, $scope, $additionalParams, $userId);
		}

		if($userId > 0)
		{
			$applicationData = AppTable::getByClientId($clientId);

			if($applicationData)
			{
				$authResult = array(
					'access_token' => $this->generateToken(),
					'user_id' => $userId,
					'client_id' => $clientId,
					'expires' => time() + static::TOKEN_TTL,
					'expires_in' => static::TOKEN_TTL,
					'scope' => $applicationData['SCOPE'],
					'domain' => Context::getCurrent()->getServer()->getHttpHost(),
					'status' => AppTable::STATUS_LOCAL,
					'client_endpoint' => \CRestUtil::getEndpoint(),
					'member_id' => \CRestUtil::getMemberId(),
				);

				$this->store($authResult);

				return $authResult;
			}
			else
			{
				$authResult = array('error' => RestException::ERROR_OAUTH, 'Application not installed');
			}

			return $authResult;
		}

		return false;
	}

	public function authorizeClient($clientId, $userId, $state = '')
	{
		if(!$this->checkClient($clientId))
		{
			return parent::authorizeClient($clientId, $userId, $state);
		}

		throw new NotImplementedException('Full OAuth authorization is not implemented in this demo');
	}

	public function checkClient($clientId)
	{
		return in_array($clientId, $this->applicationList);
	}

	protected function store(array $authResult)
	{
		$this->getStorage()->store($authResult);
	}

	public function checkToken($token)
	{
		return substr($token, 0, strlen(static::TOKEN_PREFIX)) === static::TOKEN_PREFIX;
	}

	protected function generateToken()
	{
		return static::TOKEN_PREFIX.Random::getString(32);
	}

	/**
	 * @return AuthStorageInterface
	 * @throws ObjectNotFoundException
	 */
	public function getStorage()
	{
		if($this->storage === null)
		{
			throw new ObjectNotFoundException('No token storage set. Use '.__CLASS__.'::instance()->setStorage().');
		}

		return $this->storage;
	}

	/**
	 * @param AuthStorageInterface $storage
	 * @return AuthProvider
	 */
	public function setStorage(AuthStorageInterface $storage)
	{
		$this->storage = $storage;

		return $this;
	}

	/**
	 * @param string $clientId
	 * @return AuthProvider
	 */
	public function addApplication($clientId)
	{
		$this->applicationList[] = $clientId;

		return $this;
	}
}

Основной метод - метод get, который служит для выдачи авторизации приложению. Метод получает на вход приложение, которое "затребовало" авторизацию и проверяет, является ли это приложение тем самым, которое мы хотим "пустить в обход" стандартного механизма авторизации. Далее получаются данные о приложении и формируется структура, схожая со структурой, которую получают все приложения от стандартного OAuth-сервера Битрикс24. В массиве:

• access_token - созданный токен.
• user_id - пользователь, для которого нужно дать авторизацию.
• client_id - приложение. Обратите внимание, что можно указать любое время жизни токена, а не только час времени, используемый по умолчанию в обычной авторизации.
• expires - дата истечения токена.
• scope - требуемые скоупы.
• служебные данные.

Далее эти данные сохраняются на портале. Далее сформированная структура возвращается.

	protected function store(array $authResult)
	{
		$this->getStorage()->store($authResult);
	}

	protected function generateToken()
	{
		return static::TOKEN_PREFIX.Random::getString(32);
	}

	public function checkToken($token)
	{
		return substr($token, 0, strlen(static::TOKEN_PREFIX)) === static::TOKEN_PREFIX;
	}

	public function checkClient($clientId)
	{
		return in_array($clientId, $this->applicationList);
	}

Далее регистрируем наш провайдер в качестве текущего провайдера авторизации:

\Bitrix\Rest\Application::setAuthProvider(
	Demo\AuthProvider\AuthProvider::instance()
);

Если теперь совершить запрос с этим авторизационным токеном и вызвать метод \Bitrix\Rest\AppInfo, то мы получим данные приложения в текущем Битрикс24:

Делаем свой валидатор авторизации.

<?php
namespace Demo\AuthProvider;

use Bitrix\Rest\OAuth\Auth;

class AuthFull extends Auth
{
	protected static function check($accessToken)
	{
		if(!AuthProvider::instance()->checkToken($accessToken))
		{
			return parent::check($accessToken);
		}

		$authResult = AuthProvider::instance()->getStorage()->restore($accessToken);

		if($authResult === false)
		{
			$authResult = array('error' => 'invalid_token', 'error_description' => 'Token expired or invalid');
		}

		return $authResult;
	}

}

В валидаторе достаточно отнаследоваться от оригинального валидатора авторизации и переопределить у него функцию check, которая и занимается проверкой accessToken. Если проверка прошла, то происходит восстановление приложения из хранилища. Затем регистрируем обработчик события, выполнив код на портале один раз:

\Bitrix\Main\EventHandler::getInstance()
	->registerEventHadler(
		"rest", "onRestCheckAuth", "demo.authprovider", "\\Demo\\AuthProvider\\AuthFull", "onRestCheckAuth", 90
	);

Последний параметр - сортировка. Необходимо встроиться до того, как сработает оригинальный обработчик.

Если теперь совершить запрос с этим авторизационным токеном и вызвать метод \Bitrix\Rest\AppInfo, то можно получить данные приложения на этом портале.

Осталось только дополнить провайдер событий, чтобы передавать приложению авторизационные данные в обработчики событий:

if($item['additional']['sendAuth'])
	{
		$item['query']['QUERY_DATA']['auth'] = AuthProvider::instance()->get(
			$item['client_id'],
			'',
			$item['auth'],
			$item['auth'][AuthFull::PARAM_LOCAL_USER]
		);
	}

<?php
namespace Demo\AuthProvider;

class AuthSimple
{
	const AUTH_TYPE = 'demo_simple';

	const AUTH_PARAM_NAME = 'secret_word';
	const AUTH_PARAM_VALUE = 'MySuperSecurePassword123456';

	public static function onRestCheckAuth(array $query, $scope, &$res)
	{
		if(array_key_exists(static::AUTH_PARAM_NAME, $query))
		{
			if($query[static::AUTH_PARAM_NAME] === static::AUTH_PARAM_VALUE)
			{
				$error = false;

				$res = array(
					'user_id' => 1,
					'scope' => implode(',', \CRestUtil::getScopeList()),
					'parameters_clear' => array(static::AUTH_PARAM_NAME),
					'auth_type' => static::AUTH_TYPE,
				);

				if(!\CRestUtil::makeAuth($res))
				{
					$res = array('error' => 'authorization_error', 'error_description' => 'Unable to authorize user');
					$error = true;
				}

				return !$error;
			}

			$res = array('error' => 'INVALID_CREDENTIALS', 'error_description' => 'Invalid request credentials');

			return false;
		}

		return null;
	}
}

В результате обработчик получит полную структуру данных, которые ему требуются для работы.

Небольшое замечание по поводу производительности. Код, добавленный в провайдер событий в нашем примере выше, выполняется непосредственно в обработчике события. В коде есть post запрос к стороннему серверу. Следовательно, если сторонний сервер "тормозит", то будет "тормозить" и весь портал. Если производится какая-то массовая операция, например: импорт данных в CRM, то этот код серьёзно может замедлить работу портала.

Обойти эту проблему производительности можно двумя способами:

• Построение очереди. Вместо отправки post запроса складывать данные в какую-то таблицу и какими-то дополнительными процессами выбирать из неё данные. По сути - кастомная реализация очереди.
• Воспользоваться механизмом офлайн событий

OAuth 2.0

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

Как работает протокол

Протокол очень распространён, используется огромным количеством сервисов по всему миру, поскольку позволяет приложению получить доступ к API от имени конкретного пользователя конкретного портала.

Для OAuth-сервера авторизация - это указание на то, что пользователь дал доступ приложению. Приложение предоставляет свой секрет. Портал это всё объединяет и выдаёт приложению соответствующий тип доступа.

Протокол состоит из двух шагов:

• Пользователь сообщает порталу, что он авторизован. Приложение добавляет свой идентификатор: client id. В ответ сервер передаёт пользователю, а через него и приложению, первый авторизационный код: code.
• Этот код приложение, уже скрыто от пользователя, [dw]передаёт обратно порталу[/dw][di]Важно! Запрос code не может делаться ajax запросом со страниц другого сайта, так как браузер его будет блокировать. Запрос для получения access token должен исходить именно от серверной части приложения.[/di], присоединяя к нему свой секретный ключ: client secret. Приложение таким образом подтверждает, что оно то самое приложение, которое известно порталу и которое может с ним работать. В ответ портал сообщает два параметра: access_token - параметр, который собственно требуется для доступа к авторизации и refresh_token - токен, который требуется для продления авторизации.
• После использования refresh_token и выданный вместе с ним access_token становятся недействительными. Для доступа к REST API следует использовать новый полученный access_token, а для продления доступа - новый refresh_token.

Общий порядок работы с OAuth

• добавляется и устанавливается тиражное приложение, либо локальное в своем отдельном Битрикс24;
• запрашиваются с удаленного сервера ключи;
• сервер перенаправляет браузер на зарегистрированный приложением URL;
• обрабатывается ответ;
• подписываются полученным ключом все запросы к Rest API.

Полная OAuth-авторизация в Битрикс24

В качестве сервера данных и держателя пользовательской авторизации выступает конкретный Битрикс24. В качестве держателя авторизации приложения служит сервер авторизации, доступный по адресу https://oauth.bitrix.info/.

Полный сценарий OAuth-авторизации проходит в несколько шагов:

1. Авторизация пользователя в Битрикс24.

   Приложение запрашивает у пользователя адрес Битрикс24 и переадресует его на специально сформированный URL, например, такой:

   https://portal.bitrix24.com/oauth/authorize/?
       client_id=app.573ad8a0346747.09223434
       &state=JJHgsdgfkdaslg7lbadsfg

   Параметры:

   • сlient_id - код приложения, получаемый в партнерском кабинете при регистрации приложения (и действующий для любых Битрикс24), либо получаемый в конкретном Битрикс24 в случае локального приложения (будет действовать только для этого Битрикс24). Обязательный параметр.
   • state - дополнительный параметр, позволяющий приложению передать произвольные дополнительные данные между шагами авторизации. Необязательный параметр.

   По данной ссылке пользователю будет выведена форма авторизации. После авторизации (либо при наличии авторизованной сессии), если приложение с переданным client_id установлено на портале, портал вернет пользователя на redirect_uri приложения. Если же приложение на портал не установлено, пользователю будет выведено соответствующее сообщение об ошибке.

   Итогом успешной пользовательской авторизации должен стать возврат пользователя на зарегистрированный адрес приложения с дополнительными параметрами:

   https://www.applicationhost.com/application/?
       code=avmocpghblyi01m3h42bljvqtyd19sw1
       &state=JJHgsdgfkdaslg7lbadsfg
       &domain=portal.bitrix24.com
       &member_id=a223c6b3710f85df22e9377d6c4f7553
       &scope=crm%2Centity%2Cim%2Ctask
       &server_domain=oauth.bitrix.info

   Параметры:

   • code - первый авторизационный код, см. ниже;
   • state - значение переданное в первом запросе;
   • domain - домен портала, на котором происходит авторизация;
   • member_id - уникальный идентификатор портала, на котором происходит авторизация;
   • scope - разделенный запятыми список прав доступа к REST API, которые портал предоставляет приложению;
   • server_domain - домен сервера авторизации.
   Внимание! В партнерском кабинете можно зарегистрировать приложение, которое не будет иметь "обратного адреса" redirect_uri. (По redirect_uri получаются авторизационные данные.) Такой сценарий возможен для тиражных решений, которые не имеют постоянного адреса. В этом случае предполагается, что пользователь вручную передает первый авторизационный код приложению. Упрощенный первый авторизационный код будет выведен пользователю непосредственно на странице, а приложение должно предоставить пользователю поле для ввода значения кода.

2. Авторизация приложения

   Внимание! Предыдущая реализация протокола предполагала отдачу client_secret приложения непосредственно Битрикс24. В связи с расширением механизма REST API на коробочные установки Битрикс24 такое действие становится небезопасным. Все операции, предполагающие участие секретного кода приложения, должны проводиться исключительно с сервером авторизации oauth.bitrix.info. По той же причине этот сервер авторизации должен быть единственным доверенным источником информации о платежном статусе приложения на портале.

   Получив тем или иным способом первый авторизационный код code, приложение должно совершить второй шаг OAuth-авторизации и сделать скрытый от пользователя запрос вида:

   https://oauth.bitrix.info/oauth/token/?
       grant_type=authorization_code
       &client_id=app.573ad8a0346747.09223434
       &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
       &code=avmocpghblyi01m3h42bljvqtyd19sw1

   Параметры (все - обязательны):

   • grant_type - параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение authorization_code;
   • client_id - код приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
   • client_secret - секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
   • code - значение параметра code, переданного приложению в конце предыдущего шага.
   Внимание! Время жизни первого авторизационного кода code - всего 30 секунд, и он должен быть использован сразу после получения.

   В ответ на такой запрос приложение получит json следующего содержания:

   GET /oauth/token/
   
   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
   	"access_token": "s1morf609228iwyjjpvfv6wsvuja4p8u",  
   	"client_endpoint": "https://portal.bitrix24.com/rest/",  
   	"domain": "oauth.bitrix.info",  
   	"expires_in": 3600,  
   	"member_id": "a223c6b3710f85df22e9377d6c4f7553",  
   	"refresh_token": "4f9k4jpmg13usmybzuqknt2v9fh0q6rl",  
   	"scope": "app",  
   	"server_endpoint": "https://oauth.bitrix.info/rest/",  
   	"status": "T"
   }

   Значимые параметры:

   • access_token - основной авторизационный токен, требуемый для доступа к REST API;
   • refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
   • client_endpoint - адрес REST-интерфейса портала;
   • server_endpoint - адрес REST-интерфейса сервера;
   • status - статус приложения на портале.

   Также на этом этапе приложение может получить ошибку авторизации, если, например, истек пробный или оплаченный период.

   {
   	"error": "PAYMENT_REQUIRED",  
   	"error_description": "Payment required"
   }

Простое получение токенов

Простейшим сценарием для получения доступа к REST API является работа приложения в интерфейсе Битрикс24. В этом случае все необходимые авторизационные данные выдаются приложению при открытии, а также доступна возможность использования js-библиотеки для совершения вызовов к API.

Приложение получает следующий массив POST-данных:

array (
	'DOMAIN' => 'portal.bitrix24.com', // домен портала
	'PROTOCOL' => '1', // протокол обращения: 0 - http, 1 - https
	'LANG' => 'ru', // текущий язык, на котором пользователь просматривает портал
	'APP_SID' => 'dd8cec11e347088fe87c44870a9f1dba', // служебный параметр для связи js-библиотеки с окружением приложения
	'AUTH_ID' => 'ahodg4h37n89vo17gbkgq0x1l825nnb5', // основной авторизационный токен, требуемый для доступа к REST API
	'AUTH_EXPIRES' => '3600', // время жизни авторизационного токена
	'REFRESH_ID' => '2lg086mxijlpvwh0h7r4nl19udm4try5', // дополнительный авторизационный токен, служащий для продления сохраненной авторизации
	'member_id' => 'a223c6b3710f85df22e9377d6c4f7553', // уникальный идентификатор портала, не зависящий от доменного имени
	'status' => 'P', // статус приложения на портале. значение поля служит чисто для информации, чтобы получить доверенное значение, используйте метод oauth.bitrix.info/rest/app.info
)

При помощи значения параметра AUTH_ID можно сразу совершать запросы к API.

И как написано выше, приложения в интерфейсе могут совершать запросы к API на стороне клиента, то есть браузера пользователя, подключив js-библиотеку и используя методы BX24.callMethod и BX24.callBatch. В этом случае работа с авторизацией будет происходить автоматически.

Таким образом, становится доступным простой сценарий получения авторизационных токенов пользователя при установке приложения. Как вы знаете (это было продемонстрировано в соответствующем примере раздела "Быстрый старт"), у публичного тиражного решения существует возможность задать отдельный скрипт установки, который будет показываться пользователю, устанавливающему ваше решение, во фрейме один раз - в момент установки решения. И в этот фрейм Битрикс24 передает те же самые данные в POST-запросе, что и в обычном случае. Следовательно, вы можете так разработать скрипт установки, чтобы сохранять токены (что самое важное - refresh_token в том числе) на стороне своего приложения, чтобы в дальнейшем реализовать сценарий автоматического возобновления токенов.

Событие установки приложения

Для приложений, не имеющих страницы в интерфейсе Битрикс24 (параметр Использует только API в форме редактирования приложения в партнерском кабинете или на портале), доступен вот такой способ авторизации. В форме редактирования версии (или в форме редактирования локального приложения на портале) можно указать значение параметра Ссылка-callback для события установки. Если указать в этом поле ссылку на обработчик на стороне приложения, то при установке приложения обработчик получит POST-запрос со следующими данными (application/x-www-form-urlencoded):

array(
	'event' => 'ONAPPINSTALL',
	'data' => array(
		'VERSION' => '1',
		'LANGUAGE_ID' => 'ru',
	),
	'ts' => '1466439714',
	'auth' => array(
		'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
		'expires_in' => '3600',
		'scope' => 'entity,im',
		'domain' => 'portal.bitrix24.com',
		'server_endpoint' => 'https://oauth.bitrix.info/rest/',
		'status' => 'F',
		'client_endpoint' => 'https://portal.bitrix24.ru/rest/',
		'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
		'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
		'application_token' => '51856fefc120afa4b628cc82d3935cce',
	),
)

Поля запроса содержат информацию о событии (event), данные события (data), а также, авторизационные данные для доступа к REST API (auth) от имени пользователя, установившего приложение.

Значимые параметры:

• access_token - основной авторизационный токен, требуемый для доступа к REST API;
• refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
• client_endpoint - адрес REST-интерфейса портала;
• server_endpoint - адрес REST-интерфейса сервера;
• status - статус приложения на портале.

Смотри События

  Интерактивные приложения

Если вам необходимо написать свой собственный клиент, то читайте дальше. Если вам не нужен новый клиент, а нужно просто добавить функционал интерактивности в уже существующее приложение, то читайте это.

С помощью подключения к RT-серверам создаётся действительно интерактивное приложение: меняется состояние приложения, мгновенно обновляется интерфейс без необходимости ajax запросов. Прочитать про технологию вы можете в курсе Администратор. Модули.

  Разработка приложения

Для работы с сервисом есть два способа подключения: [ds]Long polling и websocket[/ds][di]Когда пользователь входит на сайт, его браузер, настольное или мобильное приложение устанавливают и держат постоянное соединение с Push-сервером.
Обычно это делается с помощью WebSocket , который используют 95% современных браузеров. А если технология WebSocket не поддерживается браузером, то используется Long Polling — постоянный долгий опрос.

Подробнее ...[/di]. Основным методом подключения рекомендуется использовать websocket. Long polling используется только для устройств у которых нет поддержки websocket, или если при подключении к websocket у клиента часто возникают проблемы.

Для получения данных о сервере и адресах подключения используйте REST команду pull.application.config.get

Для подключения к серверу, возьмите в настройках сервера (поле server) адрес подключения нужного типа (например, websocket_secure) и [dw]добавьте[/dw][di]Каналы перечисляются в GET параметре CHANNEL_ID.[/di] к нему все доступные каналы через /. В случае, если на портале используется облачный push-сервер, к URL'у для подключения к серверу необходимо добавить параметр clientId.

Пример подключения для websocket для коробочного push-сервера:

wss://rt.bitrix24.com/sub/?CHANNEL_ID=46a437d2336d4a88e4e9b3cd956ecf45:6221e0eb48981fce67cf4756e82e8102.7910bb25e660bf211fdec15e33c5e25e4c3b644a/fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0

Пример подключения для websocket для облачного push-сервера:

wss://rtc-cloud-ms1.bitrix.info/subws/?CHANNEL_ID=beb502091dfc9b93d7fd648aa4ec332e%3A7cc478c89de71ec78bf4820d3d814a3e.4f5466742ca1e59e263fee732a7dbe002889ba91%2F1ab4f7a440cea35a1abccd5c2566c688.b33914ef342e5cd21e4fbcf4ac92acd2e9ea3755&clientId=fcda45d0859442735f07b8bb5825ded1

Время работы каждого канала ограничено 12 часами. Необходимо отслеживать время окончания и делать повторный запрос к pull.application.config.get когда у одного из каналов завершилось время работы.

Для доступа к истории в канала к указанному выше адресу добавьте специальные get-метки: &tag= и &time= (для версии сервера 2 и ниже) или &mid= (для версии 3 и выше). Все необходимые данные для get-меток вы получите при разборе каждой команды из канала. После подключения с данными метками, вам будут одноразово доступны сообщения, которые для текущей сессии не были доступны.

  Общий формат команд от сервера

Для сервера версии 3 и ниже при поступлении команд, приходит текст вида:

#!NGINXNMS!#{"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}}#!NGINXNME!#
#!NGINXNMS!#{"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}#!NGINXNME!#

Для работы с командой, необходимо получить её содержимое и преобразовать в JSON. Текст команды располагается между управляющими фразами #!NGINXNMS!# и #!NGINXNME!#.

Начиная с версии сервера 4, используйте добавление GET-параметра &format=json при подключении и при поступлении команд, он будет вам отдан в формате JSON:

[
    {"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}},
    {"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}
]

JSON структура команды имеет следующий унифицированный вид:

{
	"id" : 320146,
	"mid" : "14526134350000000000320146",
	"channel" : "6221e0eb48981fce67cf4756e82e8102",
	"tag" : "672",
	"time" :"Mon, 03 Oct 2017 06:36:01 GMT",
	"text" : {
	"module_id" : "main",
	"command" : "user_online",
	"params" : {
            ...
	},
	"extra" : {
		"server_time": "2017-10-03T08:36:01+02:00",
		"server_time_unix": 1507012561,
		"server_time_ago": 0,
		'revision': 16,
			'revisionMobile': 1,
		"channel" : "6221e0eb48981fce67cf4756e82e8102"
	}
}

Где:

• id - идентификатор сообщения
• mid - идентификатор сообщения (только для версии сервера 3 и выше, используется для восстановления истории с определенного сообщения)
• channel - идентификатор канала (только для версии сервера 3 и выше, для более ранних используйте extra.channel )
• tag - E-tag (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
• time - время сообщения (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
• text - структура, описывающая действие команды, содержит следующие ключи:
  • module_id - идентификатор модуля, отправившего команду (для приложений marketplace - appId)
  • command - идентификатор команды
  • params - дополнительные данные для выполнения команды
• extra - структура, описывающая дополнительные сведения:
  • server_time - время сервера на момент формирования команды (формат ATOM)
  • server_time_unix - время сервера на момент формирования команды (в формате Unix timestamp с часовым поясом браузера)
  • server_time_ago - количество секунд, прошедших с момента отправки команды
  • server_name - имя сервера, отправившего команду
  • revision - ревизия модуля push & pull для браузерного скрипта
  • revisionMobile - ревизия модуля push & pull для мобильного клиента
  • channel - идентификатор канала (только для версии сервера 1)

  Работа с ошибками

Во время работы с сервером могут возникать разные ошибки. Во избежания блокировки за подозрительную активность важно правильно их обрабатывать.

Если подключение к серверу приводит к ошибкам, необходимо инкрементально увеличивать время подключения:

• При возникновении ошибки в первый раз, задержка при подключении - 100мс.
• При повторной ошибке - 15 секунд.
• От 3 до 5 ошибок - 45 секунд.
• От 5 до 10 ошибок - 10 минут.
• Более 10 ошибок подряд - 1 час.

При работе с websocket при возникновении ошибок более 4х раз, рекомендуется переходить на работу с Long polling. Очень вероятна ситуации что на компьютере клиента заблокирована работа websocket протокола (код завершения websocket 1006 и 1008).

  Формат поступающих команд для управления подключением

Для собственной реализации работы с протоколом Push & Pull предусмотрите обработку управляющих команд.

channel_expire

Команда об истечении времени работы канала.

{
	"module_id" : "pull",
	"command" : "channel_expire",
	"params" : {
		"action" : "reconnect",
		"channel" : {
			"id" : "46a437d2336d4a88e4e9b3cd956ecf45.7910bb25e660bf211fdec15e33c5e25e4c3b644a",
			"type": "shared"
		},
		"new_channel": {
			"id": "fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0",
			"start": "2017-06-28T09:57:48+02:00",
			"end": "2017-06-28T21:57:48+02:00",
			"type": "shared"
		}
	}
}

Параметры

Описание работы с командой

При поступлении команды channel_expire, в зависимости от значения action, выполните:

• Если action == reconnect, то данными из new_channel замените информацию о [dw]текущем канале[/dw][di]Информация о каком канале речь есть в channel[/di]. После чего переустановите подключение к серверу заново.
• Если action == get_config, то отключитесь от сервера, запросите новые данные о каналах через REST pull.application.config.get. После чего установите подключение к серверу заново.

config_expire и server_restart

Команда о изменении настроек сервера

{
	"module_id" : "pull",
	"command" : "config_expire",
	"params" : {}
}

Описание работы с командой

Если поступила команда config_expire или server_restart, то отключитесь от сервера, и через случайный промежуток времени (от 10 до 120 секунд), запросите новые данные о каналах через REST pull.application.config.get. После чего установите подключение к серверу заново.

Офлайн события

Приложение не в всегда в состоянии принимать события. Оно может скрываться за фаерволлами, жить во внутренней сети и т.д. В этом случае используется механизм офлайн-событий, когда приложение подписывается на события, но не указывает URL обработчика. Вместо этого приложение указывает, чтобы события копились в базе, пока оно само их не заберет.

Механизм офлайн события используется для работы со сторонними информационными системами. Например, текущая интеграция продукта с 1С целиком построена на офлайн событиях.

Преимущества офлайн событий:

1. Простота использования - работа механизм очень проста;
2. Надежность - при необходимости можно дополнительно контролировать факт получения и обработки данных во внешних системах;
3. Универсальность - подходит для любой внешней системы или сервиса (не только для 1С);
4. Возможность получения данных в режиме реального времени.

Отличительная особенность офлайн событий от обычных: если событие ещё не обработано, то его копии не создаются. Например: сделка изменена 5 раз. При использовании обычных событий - вызов обработчика выполнится 5 раз, а офлайн событий - оставит 1 запись в журнале об изменении сделки.

Записи в очереди аккумулируются по данным событий. Например, если в очереди уже ожидает событие ONCRMLEADUPDATE для лида с ID=10, то следующее обновление лида 10 не добавит новую запись, а только изменит дату существующей.

Схема работы

В общем виде работы схемы очень проста. Офлайн событие попадает в очередь офлайн событий. Потом внешняя система забирает их из очереди и обрабатывает.

Есть две схемы работы этого механизма - простая и усложнённая. В простой схеме приложение просто подписывается на события и по мере надобности забирает "верхнюю" часть очереди. В усложнённой схеме приложение имеет возможность управлять разбором очереди, самостоятельно разделять записи на отработанные и требующие разрешения конфликта и т.д.

Полезные видеоматериалы:

Технологический поток 21.05.2021: Преимущества офлайн-событий, или как использовать REST правильно

Регистрация офлайн события

Для регистрации офлайн события используется метод /rest/event.bind со значением event_type=offline. В этом случае параметр handler становится не обязательным, а параметр auth_type - бессмысленным.

Пример вызова:

https://myportal.bitrix24.com/rest/event.bind
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36 // ключ авторизации
	&event=ONCRMLEADUPDATE // название события
	&event_type=offline // тип события
	&auth_connector=OneC // ключ источника

HTTP/1.1 200 OK

{
	"result": true 
}

Параметр &auth_connector

&auth_connector=OneC - ключ источника. Этот важный параметр отличает офлайн события от онлайн, т.к. позволяет исключать ложные срабатывания событий.

Что такое ложное срабатывание события?. Рассмотрим на примере:

Пусть у нас есть Битрикс24 и 1С. В Битрикс24 зарегистрировано 2 события:

• событие на добавление компании;
• событие на обновление компании.

Создали компанию. Сработало событие, по которому компания попала в 1С. Затем в 1С компания была изменена посредством Rest и изменения попали в Битрикс24. В теории, должно сработать офлайн событие на обновление компании и снова попасть в 1С, что нелогично.

Для того, чтобы такие события не регистрировались используется параметр &auth_connector. Этот параметр нужно указывать не только при таком Rest запросе при регистрации офлайн события, но так же в любом Rest запросе, который выходит из учетной системы.

Таким образом это обязательный параметр для rest запросов из внешних систем:

Правильно

Неправильно

Список событий

После вызова установки обработчика метод /rest/event.get выдает нам вот такую картину (обычный обработчик события добавлен для сравнения):

https://myportal.bitrix24.com/rest/event.get
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36

HTTP/1.1 200 OK

{
	"result": [
	{
		"connector_id": "", 
		"event": "ONCRMLEADUPDATE", 
		"offline": 1
	}, 
	{
		"auth_type": "0", 
		"event": "ONCRMLEADUPDATE", 
		"handler": "http://apphost.com/handler/", 
		"offline": 0
	}
	]
}

Для отписки от события используется тот же самый метод /rest/event.unbind, вызываемый с теми же параметрами, что и event.bind.

Далее происходит разбор очереди событий.

Простая схема

Если приложение вызывает метод /rest/event.offline.get, то портал отдаст первые 50 событий, удовлетворяющих фильтру и в заданном порядке сортировки, и сразу вычистит их из базы.

https://myportal.bitrix24.com/rest/event.offline.get
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36

HTTP/1.1 200 OK

{
	"result": {
		"events": [
			{
				"EVENT_ADDITIONAL": {
					"user_id": "1"
				}, 
			"EVENT_DATA": {
				"FIELDS": {
					"ID": 28
				}
			}, 
			"EVENT_NAME": "ONCRMLEADUPDATE", 
			"ID": "40", 
			"MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
			"TIMESTAMP_X": "2018-02-14T14:20:19+02:00"
			}
		], 
		"process_id": null
	}
}

Метод event.offline.get поддерживает многопоточный разбор. То есть допускается несколько параллельных запросов к методу (с соблюдением ограничений на количество запросов в единицу времени), и каждый из них получит разные наборы записей.

Усложнённая схема

Основное отличие этой схемы от простой в том, что выбранные записи не удаляются из базы, а помечаются как обрабатываемые. Они продолжают оставаться в базе, пока приложение не оповестит об окончании их обработки. Если за время обработки появятся новые срабатывания события, то они будут добавлены в очередь как обычно, даже если запись о таком событии уже есть среди обрабатываемых. Другой поток обработки сможет получить сообщение об изменении.

Получение записей

Включается эта схема добавлением параметра clear=0 к вызову event.offline.get.

https://myportal.bitrix24.com/rest/event.offline.get
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36
	&clear=0

HTTP/1.1 200 OK

{
	"result": {
		"events": [
			{
				"EVENT_ADDITIONAL": {
					"user_id": "1"
				}, 
				"EVENT_DATA": {
					"FIELDS": {
						"ID": 28
					}
				}, 
				"EVENT_NAME": "ONCRMLEADUPDATE", 
				"ID": "45", 
				"MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
				"TIMESTAMP_X": "2018-02-14T14:43:13+02:00"
			}
		], 
		"process_id": "5xcvetmo5zm5li73qxnj8qu72e2qrxw8"
	}
}

Обратите внимание на поле process_id в ответе. После такого вызова записи остаются в базе, но помечаются как обрабатываемые процессом с этим идентификатором. И далее не учитываются ни при каких последующих выборках и при добавлении новых событий.

После того, как записи выбраны, помечены как обрабатываемые и отданы приложению, приложение может какие-то из них удалить, какие-то пометить как ошибочные, какие-то оставить на потом.

Очистка записей

Очистка производится вызовом метода /rest/event.offline.clear, который принимает на вход process_id и массив идентификаторов записей, которые нужно удалить.

https://myportal.bitrix24.com/rest/event.offline.clear
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36
	&process_id=5xcvetmo5zm5li73qxnj8qu72e2qrxw8

HTTP/1.1 200 OK

{
	"result": true
}

Обработка ошибок

При создании сложных интеграций, для которых и предназначена усложнённая схема, вполне возможна ситуация, когда возникает конфликт данных различных систем. В этом случает требуется человеческий контроль или использование какого-то другого способа разрешения конфликтов. Чтобы при этом не стопорить процесс и не копить ошибки, некоторые записи о событиях можно оставлять в базе с пометкой об их ошибочности. Для этого используется метод /rest/event.offline.error.

https://myportal.bitrix24.com/rest/event.offline.error
	?auth=4742845a0000cd7a0000cd5d0000000100000386a97f24a7f515e9ec5e242fed727af4
	&process_id=cal3dm2qg31gb3g8uatca6huqjdtdn6u
	&message_id[]=438d4ec3d329464c4bb9909db4c7a19b

HTTP/1.1 200 OK

{
	"result": true
}

После выставления флага об ошибке, помеченные записи перестанут отдаваться приложению при вызове event.offline.get. Перестают отдаваться как сама помеченная запись, так и все последующие срабатывания события с этими данными. Иными словами, изменения этой сущности на стороне Битрикс24 перестанут передаваться в приложение, пока приложение не даст разрешение на передачу. Также запись отвяжется от текущего процесса и не будет удалена при вызове event.offline.clear. Если за время обработки были срабатывания события с такими данными, они также передаются приложению, даже если уже были захвачены другим процессом.

Разрешение ошибок

Чтобы снять пометку об ошибке с записи, нужно вычистить ее из базы при помощи event.offline.get с указанием параметра error=1. И при необходимости, с дополнительным фильтром, если нужно обработать только часть ошибок. Сразу после вызова ошибочные записи будут вычищены из базы (если указать clear=1), либо помечены как обрабатываемые (если указать clear=0). В обоих случаях новые события с такими данными снова начнут регистрироваться и отдаваться приложению.

Простое получение состояния очереди

Иногда может потребоваться считать текущую очередь, не внося изменений в ее состояние, как это делает event.offline.get, и не завися от сложной логики пометки ошибочных событий или раскидывания событий по процессам. Для этого сделан простой списочный метод /rest/event.offline.list:

https://myportal.bitrix24.com/rest/event.offline.list
	?auth=4742845a0000cd7a0000cd5d0000000100000386a97f24a7f515e9ec5e242fed727af4

HTTP/1.1 200 OK

{
	"result": [
		{
			"ERROR": "0", 
			"EVENT_ADDITIONAL": {
				"user_id": "1"
			}, 
			"EVENT_DATA": {
				"FIELDS": {
					"ID": 28
				}
			}, 
			"EVENT_NAME": "ONCRMLEADUPDATE", 
			"ID": "60", 
			"MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
			"PROCESS_ID": "", 
			"TIMESTAMP_X": "2018-02-14T15:34:34+02:00"
		}, 
		{
			"ERROR": "0", 
			"EVENT_ADDITIONAL": {
				"user_id": "1"
			}, 
			"EVENT_DATA": {
				"FIELDS": {
					"ID": 27
				}
			}, 
			"EVENT_NAME": "ONCRMLEADUPDATE", 
			"ID": "65", 
			"MESSAGE_ID": "7bf367ea2e4c9b6a8c3adac4a416627c", 
			"PROCESS_ID": "", 
			"TIMESTAMP_X": "2018-02-14T15:34:55+02:00"
		}
	]
}

Обработчик (handler)

Для работы через обработчики нужно зарегистрировать онлайн событие на добавление офлайн событий. Простыми словами: есть событие, которое сообщает о том, что в журнале офлайновых событий появились новые записи.

На примере интеграции с 1С это работает так: есть определенное приложение Битрикс24, которое дает токен и там же есть определенная страничка обработчика. Из 1С регистрируется событие на офлайн событие onOfflineEvent и когда появляется новая запись, это обрабатывает handler и он стучится в 1С. 1С понимает, что появились новые данные и выполняет event.offline.get, получает записи и обрабатывает их.

Пример вызова:

https://myportal.bitrix24.com/rest/event.bind
	?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36 // ключ авторизации
	&event=onOfflineEvent // добавление офлайн события
	&handler==http%3A%2F%2Fwww.my-domain.com%2Fhandler%2F // адрес обработчика

Минус такого способа: внешняя система (например, 1С) должна быть доступна снаружи, иначе обработчик не сможет до неё достучаться.

Push&Pull сервер

В случаях, когда безопасность критична, есть другой способ, через Push&Pull сервер.

Реализацию способа рассмотрим на примере интеграции с 1С, т.к. он разработан специально для неё.

Для получения информации о новых офлайн событиях используется открытый канал Push&Pull сервера, который всегда есть в каждом приложении Битрикс24. В таком варианте внешняя система сама подключается к Битрикс24 и ждёт от него сообщений. Как только приходит сообщение о новой записи, внешняя система забирает данные из очереди.

Для того, чтобы 1С могла подключиться, сначала она отправляет запрос методом pull.application.config.get. В результате получается ответ, из которого ей нужны: адрес до Push сервера, clientId (уникальный идентификатор портала на облачном push-сервере) и id открытого канала.

Пример ответа:

https://my.bitrix24.ru/rest/pull.application.config.get

{
	"result":{
		"server":{
			"version": 4,
			"long_polling": "http://rt.bitrix24.com/sub/",
			"long_polling_secure": "https://rt.bitrix24.com/sub/",
			"clientId": "43253464643",
			...........
		},
		"channels":{
			"shared":{
			"id":"0d875ab13a17a97fc2f5",
			"start":"2017-06-28T12:04:00+02:00",
			"end":"2017-06-29T00:04:00+02:00",
			...........
		}
		"private":{
			...........
		}
	}
}

И после 1C подключается с этими данными и ожидает сообщения от push сервера:

https://rt.bitrix24.com/sub/ // адрес подключения к push серверу
	?CHANNEL_ID=0d875ab13a17a97fc2f5 // идентификатор канала
	&clientId=43253464643 // идентификатор портала на облачном push сервере

Когда срабатывает какое-то офлайн событие и попадает в очередь, в push передается сообщение в формате json с указанием, что это офлайн событие и параметром connector_id, в котором указано для какой внешней системы предназначено сообщение.

#!NGINXNMS#{
	......
	"text":{
		"module_id":"rest",
		"command":"event_offline",
		"params":[
			{
				"connector_id":"OneC",
				"count":1
			}
		],
		......
	}
}

  Рекомендации

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

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

Для избежания блокировки приложения разработчикам рекомендуется:

• Контролировать и регулировать частоту выполнения запросов;
• Производить превалидацию запросов и не допускать запросов с априори некорректными данными;
• Контролировать и обрабатывать ошибки взаимодействия с API и не отсылать повторно некорректно сформированные запросы;
• Использовать механизм пакетного выполнения запросов batch для снижения количества запросов;
• Кешировать данные и не совершать повторных запросов, результат которых не может измениться за сессию работы пользователя с приложением;
• Отключать постраничную выборку с подсчетом количества элементов в списочных методах;
• Использовать фильтрацию с точным сравнением.

Если решение создает аномальную нагрузку на портале и уходит в блокировку, то при очередном запросе отдается 503 ошибка или ошибка такого вида: 'error' => 'OVERLOAD_LIMIT', 'error_description' => 'REST API is blocked due to overload.'

Для решения проблемы с постраничными выборками с подсчетом количества в выборках данных разделов CRM, USERS и т.д. используется параметр start -1. Подробное решение проблемы описано в документации.

Для решения подобной проблемы в задачах параметр start -1 не работает, вместо него используется $params['COUNT_TOTAL']='N'

При частых выборках одних и тех же данных рекомендуем партнеру кешировать данные на своей стороне.

  Вебинары по теме

• Разработка REST-приложений. Полезное. Сергей Востриков, Владислав Бажанов, «1С-Битрикс».

  Вебинар от 21 мая 2021 г.

• Приложения24. Вопросы производительности решений на REST для «Битрикс24».

  Вебинар от 22 мая 2017 г.

  Архив с примером кода

Немного теории

На рисунке показано, как работает самая нагруженная точка приложения - входящие события от Битрикс24:

• Все облачные порталы отправляют свои запросы в [dw]OAuth[/dw][di]OAuth - открытый протокол авторизации, который позволяет предоставить третьей стороне ограниченный доступ к защищенным ресурсам пользователя без необходимости передавать ей (третьей стороне) логин и пароль.
  Подробнее... [/di]-сервер.
• OAuth-сервер добавляет туда токены от вашего приложения и отправляет их на сервер очередей.
• Сервер очередей все запросы отправляет по адресам, которые вы указали в обработчиках, подписываясь на события.

И основная проблема в том, что если вы подпишетесь на очень много событий, то одновременно их может прийти слишком большое количество. Если сервер не успевает ответить (например, он завис или подвергся DDoS-атаке), то через 3 секунды вы попадете на красный сервер очередей, в котором собираются медленные приложения с низким приоритетом, и работа вашего приложения ухудшится. Поэтому нужно отвечать быстро и четко.

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

• Гарантия обработки - приложение не должно терять данных
• Автомасштабируемость - чтобы переносить пиковые нагрузки
• Быстрый ответ < 3 сек.

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

[
'error' => 'OVERLOAD_LIMIT',
'error_description' => 'REST API is blocked due to overload.'
]

SDK CRest

Для реализации микросервисной архитектуры разработана новая версия SDK CRest на Python. Она может работать как с тиражными, так и с локальными приложениями.

Как работает данная версия SDK:

• Все входящие события, которые создают основную нагрузку, принимает первая Cloud Functions. Эта [dw]функция[/dw][di] [/di] обрабатывает события, переформатируя их для [dw]SQS[/dw][di]Amazon Simple Queue Service (англ. Amazon SQS) — сервис принимает очереди сообщений для хранения. При использовании Amazon SQS, разработчики могут просто переместить данные, распределённые между компонентами своих приложений, которые выполняют различные задачи, не теряя при этом сообщения. При этом достигается высокая масштабируемость и надёжность.
  Подробнее...[/di], и сохраняет их в SQS. Тем самым она может ответить даже меньше чем за 1 сек, т.к. количество действий у нее минимальное.
• После такой быстрой обработки входящих событий приложения, другой [dw]функцией[/dw][di][/di] на триггерах из SQS автоматически разбирается каждое событие и отправляется в Базу данных. Тут важно, что событие или данные не потеряются и не пропадут незамеченными, т.к., если даже База данных подвисла, на триггерах из SQS можно повторить попытку несколько раз.
• Далее включается [dw]функция[/dw][di]
  [/di], которая сохраняет в Базу данных. И если у нее не получилось сохранить, то она возвращает ошибку и сообщение возвращается в SQS, чтобы обработаться еще раз.

Таким образом можно снизить нагрузку для таких критически важных частей, как База данных.

Бизнес-логика приложения

Рассмотрим простой сценарий работы приложения:

Приложение может быть написано на любом удобном языке.

Порядок работы может быть таким:

• подключиться к Базе данных, в которой хранятся все пришедшие в приложение события;
• забрать из таблицы события и обработать их на своей бизнес-логике в соответствии с задачами, решаемыми приложением;
• из бизнес-логики отправлять в Битрикс24 запросы не нужно;
• нужно просто сложить в соседнюю таблицу в той же Базе данных запросы в определенном формате;
• перейти к обработке следующего события.

Как видите, не требуется никаких дополнительных действий. В таблице запросов к Базе данных предусмотрена ячейка Callback`a и возможность отправки событий под определенным пользователем. Если, например, в событии мы сохранили токены, которые пришли с запросом, то мы можем отправить их в таблицу запросов в Битрикс24 и ответ уйдет именно с токеном текущего пользователя, который вам необходим.

Менеджер очереди

Как же уходят запросы к Битрикс24?

Есть функция Менеджер очереди:

[/di].

Она забирает из Базы данных порталы, к которым должны отправляться запросы. После получения списка порталов для каждого из них запускается отдельная функция, именно она и отправляет запросы. Каждая такая функция работает в контексте текущего портала. То есть порядок такой:

1. Менеджер очереди поднимает функцию с контекстом портала.
2. Из Базы данных функция забирает все запросы к текущему порталу.
3. Функция отправляет запросы к Битрикс24.
4. После того, как Битрикс24 вернет ответы на запросы, функция сохранит их в Базу данных.
5. Через Callback можно реализовать доступ к таблице запросов и необходимую доработку.

Пример - если подписаться на событие Добавление лида, то всё, что придет - ID лида. Можно сделать в приложении запрос в таблицу Базы данных об этом лиде и добавить в ячейку таблицы Callback-функцию, которая будет запускаться после того, как придет дополнительная информация по лиду. Функция обработает информацию, сохранит результат и на следующем шаге можно доработать всё, что необходимо сделать с этим лидом.

Логика и код Менеджера очереди

Он выбирает порталы по группировке и создает новые функции: Код Отправки запросов (скрыты некоторые моменты) Логика такая: функция собирает N-e количество запросов из Базе данных; запросы собираются в batch, чтобыс количество хитов было минимальным для запроса в Битрикс24 и не превышало лимиты; batch забираются, отправляются. Функция получает результаты и сохраняет их в таблицу в Базе данных. Этот не слишком сложный код работает как отдельный микросервис. Если событий мало, а запросов много, нужно поднять количество функций отправки запросов и всё будет работать быстро. Код доступен на портале для разработчиков по адресу https://dev.bitrix24.ru/workgroups/group/51/ (Нужно будет авторизоваться). Там же подробная инструкция о том, как настроить работу с облаком - добавить функции, какие методы вызывать, на какие триггеры эти функции добавить. Там же прикреплен архив с первой версией этого SDK.

  Выводы

Выводы о новой SDK CRest Python:

• Облачная структура – плата только за использование.
• Бесконечное масштабирование архитектуры.
• Обработка ответов сервера, автоматическое продление токенов администратора.
• Запросы собираются автоматически в batch.
• Приложения на одном Битрикс24 - пойдут в одном потоке и будут иметь общие лимиты.
• Open-source.

Выводы о работе облачной архитектуры под высокими нагрузками:

• Гарантия обработки.
• Бесконечное масштабирование архитектуры.
• Быстрый ответ <3 сек.
• Автомасштабируемость.
• Минимальное количество усилий для поддержания системы.

  Статистика использования REST

Если приложение на портале посылает избыточные REST-запросы, это может привести к слишком высокой нагрузке на ваш Битрикс24, а значит, и работа будет значительно более медленной.

Начиная с версии модуля REST 20.5.0, доступен инструмент Статистика использования REST (Приложения > Разработчикам > [dw]Статистика[/dw][di] [/di]), с помощью которого можно отследить общее число ежедневных REST-запросов вашего портала, а также просмотреть детальную статистику по каждому из приложений, по вебхукам и по событиям.

• Вот так выглядит статистика на портале, приложения которого используют REST рационально:

  

• А так выглядит статистика портала, у которого в один из дней был аномальный всплеск числа запросов, повысивший нагрузку и замедливший работу портала:

  

  Возможности фильтра

Для получения более детальной статистики используйте фильтр:

С помощью фильтра можно просмотреть статистику запросов по следующим критериям:

• по [dw]приложению[/dw][di] [/di]
• по [dw]по методу или событию REST[/dw][di] [/di]
• по [dw]вебхуку[/dw][di] [/di]

Таким образом, с помощью нового инструмента Статистика использования REST вы можете отследить избыточные REST-запросы и в дальнейшем оптимизировать ваше приложение.