API Битрикс24 -‐ изнутри, с пристрастием
Сербул Александр руководитель направления контроля качества
интеграции и внедрений 1С-‐Битрикс
AlexSerbul
Битрикс24 – Маркетплейс -‐ развитие C лета 2013 партнеры и разработчики активно создают приложения.
Объекты в 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); }
});
JS библиотека-‐клиент API Битрикс24
• 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
JS библиотека-‐клиент API Битрикс24
Полезные плюшки для 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)
JS библиотека-‐клиент API Битрикс24
Дерево Сортировка, фильтрация Разные типы свойств 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
mysqld mysqld mysqld
master-‐master replicaqon
master-‐master replicaqon
master-‐master replicaqon mysqld mysqld mysqld
mysqld mysqld mysqld
mysqld mysqld mysqld
mysqld mysqld mysqld
control cache: memcached
control cache: memcached
control cache: memcached
control cache: memcached
control cache: memcached
Web 2
local cache