"API «Битрикс24» — разбор с пристрастием". Александр Сербул, 1С-Битрикс

API Битрикс24 -‐ изнутри, с пристрастием

Сербул Александр руководитель направления контроля качества

интеграции и внедрений 1С-‐Битрикс

AlexSerbul

Битрикс24 – с чем будем общаться через API

Рабочие инструменты в «социальном» формате – в облаке

Битрикс – Маркетплейс. С чего все началось.

С 2010 года. Более 1000 решений в каталоге.

Битрикс24 – Маркетплейс -‐ развитие C лета 2013 партнеры и разработчики активно создают приложения.

Scrum + SMS = крепкий сон менеджера обеспечен! ;-)

Битрикс24 -‐ Маркетплейс

Установка и запуск приложения в iframe

Битрикс24 -‐ Маркетплейс

Объекты в REST API Битрикс24: ü  пользователи и их иерархия, структура компании ü  отправка уведомлений – email, push на моб. устройства, desktop app. ü  работа с задачами ü  CRM ü  календари ü  работа с абстрактными древовидными данными (инфоблоками)

Битрикс24 – REST API

RFC 6749 -‐ философия на тему редиректов J Написали свой OAuth2.0 веб-‐сервис на PHP. Поддержали самый полный flow – «4.1. AuthorizaDon Code Grant». «1.3.1. Authorizaqon Code» – время жизни 30 сек. «3.3. Access Token Scope» – поддерживаем уровни, не мельче модуля «6. Refreshing an Access Token» – обновляем Access Token, время жизни – 1 час «7.1. Access Token Types» – простой токен пока (строка), думаем про MAC и подписи

OAuth 2.0 – детали поддержки протокола

1)  «Внутреннее» – архив html+js+ресурсы загружается в облако Битрикс24

2)  «Встраиваемое» -‐ через iframe на портале пользователи; контроллер iframe -‐ на сайте партнера/разработчика

3)  «Внешнее» -‐ доступ только к API Битрикс24

Типов может быть больше, думаем как их классифицировать.

Типы приложений

Все настраивается в «личном кабинете» разработчика: •  URI приложения – для контроля адреса

приложения и iframe •  Список прав (scope) – ограничение доступа

приложения к API •  Пароль приложения – для получения Access

Token

Настройка прав OAuth 2.0 – Access Token Scope

1. h�ps://my.bitrix24.ru/oauth/authorize/? client_id=First_APP& response_type=code& redirect_uri= h"ps://test.com/bitrix/oauth/oauth_test.php 2. h�ps://test.com/bitrix/oauth/oauth_test.php? code=xxxxxxxxxxxxxxxxxxxxxxxxxxx 3. h�ps://my.bitrix24.ru/oauth/token/? client_id=First_APP& grant_type=authorizaqon_code& client_secret=#secret_key#& redirect_uri= h"ps://test.com/bitrix/oauth/oauth_test.php & code= xxxxxxxxxxxxxxxxxxxxxxxxxxx& scope=user 4. h�ps://test.com/bitrix/oauth/oauth_test.php? access_token=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy 5. h�ps://my.bitrix24.ru/rest/methods.json? auth=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&full=true {"result":["methods","batch","calendar.event.get", …]}

Алгоритм авторизации -‐ Authorizaqon Code Grant

h�ps://имя_портала.bitrix24.ru/oauth/token/? grant_type=authorizaqon_code& client_id=код_приложения& client_secret=секретный_код_приложения& code=код авторизации клиента& scope=набор_разрешений_приложения& redirect_uri=URL_приложения { "access_token":"код_авторизации","expires_in":3600, "scope":"набор_разрешений","refresh_token":"код_обновления_авторизации", "domain":"имя_портала","member_id":"идентификатор_портала“ } h�ps://имя_портала.bitrix24.ru/oauth/token/? grant_type=refresh_token& client_id=код_приложения& client_secret=секретный_код_приложения& refresh_token=код_обновления_авторизации& scope=набор_разрешений_приложения& redirect_uri=URL_приложения

Обновление Access Token

https://домен_Б24.bitrix24.{ru|en|de}/rest/имя_метода.транспорт? параметры_метода& auth=ключ_авторизации https://my.bitrix24.ru/rest/methods.xml?auth=d161f25928c3184678924ec127edd29a - получить список доступных методов в формате xml. https://my.bitrix24.ru/rest/entity.item.get.json?ENTITY=menu&auth=d161f25928c3184678924ec127edd29a - получить в формате json список всех элементов сущности menu.

{

"result": результат выполнения метода, "error": ошибка выполнения метода, "total": общее количество записей в ответе списочного метода, "next": число, которое нужно послать для получение следующей страницы

данных списочного метода } {

"result": массив результатов запросов пакета, "result_error": массив ошибок запросов пакета, "result_total": массив количеств записей в ответах списочных методов, "result_next": массив чисел, возвращенных в полях next запросов.

}

Структура запросов/ответов REST API

ü  Прячет детали авторизации ü  «Постраничка» ü  Пакетные запросы с макроязыком

подстановки ü  Полезные callbacks ü  Доступ к АПИ модулей и сущностей <script src="//api.bitrix24.com/api/v1/"> </script>

JS библиотека-‐клиент API Битрикс24

•  Вызов методов API: BX24.callMethod('user.get', {ID: 10}, function(res){

if(res.data()) { var user = res.data()[0]; if(user) alert('Пользователя №' + user.ID +

' зовут ' + user.NAME); }

});


•  Batch: BX24.callBatch({

get_user: ['user.current', {}], get_department: { method: 'department.get', params: { ID: '$result[get_user]

[UF_DEPARTMENT]' } }

}, function(result) {

var l = result.get_department.data().length; var str = 'Текущий пользователь ' +

result.get_user.data().NAME + ' ' + result.get_user.data().LAST_NAME + ' приписан к подразделени' + (l > 1 ? 'ям ' : 'ю ');

for(var i = 0; i < l; i++) { str += i == 0 ? '' : ', '; str += result.get_department.data()[i].NAME; }

alert(str);

});

•  Загрузка файлов – имя и содержимое в base64 <input type="file" id="testfile"><br /> <span onclick="sendInputFile()">send file from input</span><br /> <span onclick="sendStaticFile()">send static file</span><br /> <script type="text/javascript"> function sendInputFile() { BX24.callMethod('entity.item.add', { 'ENTITY': 'menu', 'NAME': Math.random(), 'DETAIL_PICTURE': document.getElementById('testfile') }, function(){ alert('Finished!'); }); } POST https://my.bitrix24.com/rest/entity.item.add.json HTTP/1.1 Host: my.bitrix24.com Content-Length: 186 Content-Type: text/plain; charset=UTF-8 Origin: http://app.makssidorenko.bx auth=6a8c365cb010ba42bd5b0f6ae803f47c&ENTITY=menu&NAME=0.2630483947652045&DETAIL_PICTURE[0]=1.gif&DETAIL_PICTURE[1]=R0lGODlhAQABAIAAAP%2F%2F%2FwAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw%3D%3D


Полезные плюшки для iframe: void BX24.resizeWindow(Integer width, Integer height[, Function callback]) void BX24.fitWindow([Function callback]) void BX24.reloadWindow() void BX24.setTitle(String title[, Function callback])

Системные диалоги: void BX24.selectUser(Function callback) void BX24.selectAccess(Function callback)

Сохранение настроек: void BX24.userOption.set(String name, String value) void BX24.userOption.get(String name) void BX24.appOption.set(String name, String value[, Function callback]) void BX24.appOption.get(String name)


Дерево Сортировка, фильтрация Разные типы свойств BX24.callMethod('entity.add', {'ENTITY': 'dish', 'NAME': 'Dishes', 'ACCESS': {U1:'W',AU:'R'}}); BX24.callMethod('entity.get'); {"result":[{"ENTITY":"dish","NAME":"Dishes"},{"ENTITY":"menu","NAME":"Menu"}]} BX24.callMethod('entity.update', {'ENTITY': 'dish', 'ACCESS': {U1:'W',AU:'R'}}); BX24.callMethod('entity.delete', {'ENTITY': ‘dish'}}); 'ENTITY': 'dish‘ – созданный клиентом и уникальный в рамках приложения ID хранилища. Для обеспечения идемпотентности. Планируем добавить в другие методы.

Хранилище данных

Строим дерево из разделов, добавляем элементы BX24.callMethod('entity.section.add', {ENTITY: 'menu_new', 'NAME': 'Тестовый раздел', 'SECTION': 34}); BX24.callMethod('entity.item.add', {

ENTITY: 'menu_new', DATE_ACTIVE_FROM: new Date(), DETAIL_PICTURE: '', NAME: 'Hello, world!, PROPERTY_VALUES: { test: 11, test1: 22, test_file: '' }, SECTION: 219

});


Строим дерево из разделов, добавляем элементы, выборка BX24.callMethod('entity.item.property.add', {ENTITY: 'menu_new', PROPERTY: 'new_prop', NAME: 'Новое свойство', TYPE: 'S'}); BX24.callMethod('entity.item.get', {

ENTITY: 'menu', SORT: {DATE_ACTIVE_FROM: 'ASC', ID: 'ASC'}, FILTER: { '>=DATE_ACTIVE_FROM': dateStart, '<DATE_ACTIVE_FROM': dateFinish }

}, $.proxy(this.buildData, this));


Нотификация на email и push-‐уведомления пользователям на устройства Android, iOS. Инфраструктура Bitrix Cloud Messaging (BCM): BX24.selectUser(function(user){

if(user) { BX24.callMethod('im.notify', {to: user.id, message: 'Привет, '+user.name+'!'}); }

});

Нотификация пользователей

Календари, встречи

Архитектура Битрикс24

Elas7c Load Balancing

Web 1

Elas7c Load Balancing

Dynamic

Web N … CloudWatch + AutoScaling

Web 1 Web 2 Web N … CloudWatch + AutoScaling

S3

management, monitoring, backup

Staqc

CDN

js, css

Dynamic Staqc

CDN

js, css

images (clients)

images (clients)

local cache

local cache

local cache

local cache

local cache

control cache: memcached

mysqld mysqld mysqld


master-‐master replicaqon

master-‐master replicaqon

master-‐master replicaqon mysqld mysqld mysqld









Web 2

local cache

Спасибо за внимание! Вопросы?

Александр Сербул serbul@1c-‐bitrix.ru AlexSerbul

Technology

"API «Битрикс24» — разбор с пристрастием". Александр Сербул, 1С-Битрикс