Описание библиотеки
BOOCO REST API
Содержание:
4.1.1. Параметры класса BoocoRestApi
4.1.2. Свойства класса BoocoRestApi
4.1.3. Методы класса BoocoRestApi
4.1.4. События класса BoocoRestApi
4.2.1. Свойства класса DeviceFactory
4.2.2. Методы класса DeviceFactory
4.2.3. События класса DeviceFactory
Библиотека booco-rest-api служит для работы с методами REST API сервера BOOCO.
Библиотека позволяет работать с REST API сервера BOOCO в следующих режимах:
- Отправка http(s)-запросов: GET, POST, DELETE, PUT, PATCH;
- Подписка на обновления (через подключение к TCP-порту).
Библиотека содержит следующие классы:
- Class BoocoRestApi — это основной класс для работы с REST API. В приложении создается обычно 1 экземпляр объекта этого класса.
- class DeviceFactory — создается в виде свойства equipment в классе BoocoRestApi.
- class Logger — создается в виде свойства log в классе BoocoRestApi.
Класс BoocoRestApi наследуется от класса EventEmitter.
При инициализации экземпляра объекта класса можно указать следующие параметры:
- host — адрес хоста сервера BOOCO (по умолчанию: '127.0.0.1');
- port — порт для отправки запросов (по умолчанию: 80, если используется http и 443, если https);
- socketPort — порт для подписки tcp socket (по умолчанию: 5990);
- apiBaseUrl — базовый URL для REST API (по умолчанию: '/api/v1/');
- username — имя пользователя REST API (значение по умолчанию: 'admin');
- password — пароль пользователя REST API (значение по умолчанию: 'admin')
- secure - если true, то используется протокол https, иначе (по умолчанию) - http.
Примечание. Все указанные параметры являются необязательными.
Пример использования
Инициализация экземпляра объекта класса с указанием параметров host, port, socketPort, apiBaseUrl, username и password:
const { BoocoRestApi } = require('..');
const booco = new BoocoRestApi({
host: '127.0.0.1',
port: 3000,
socketPort: 5990,
apiBaseUrl: '/api/v1/',
username: 'admin',
password: 'admin',
secure: false
});
Класс BoocoRestApi имеет следующие свойства:
- equipment — тип DeviceFactory;
- log — тип Logger.
Свойства equipment и log создаются при инициализации экземпляра объекта класса BoocoRestApi.
Пример использования
booco.log.info(infoMessage);
await booco.equipment.setChannel('Relay', 'toggleRelay1');
Класс BoocoRestApi имеет следующие методы:
- login(callback);
- connect(callback);
- callRestApi();
- destroy().
Метод login(callback) служит для авторизации в REST API. Параметр callback является необязательным и возвращает Promise.
Если указан callback, то метод вызывает его с параметром null в случае успеха или возвращает ошибку, если авторизация не удалась. Если используется callback, то Promise всегда разрешается.
Примеры использования
- Выполняется авторизация в REST API. Если авторизация не удалась, то в логах сохраняется сообщение об ошибке. В случае успешной авторизации в логах сохраняется имя скрипта, с помощью которого была выполнена авторизация, и отправляется команда на устройство Relay для переключения на 1-ый канал:
booco.log.info(infoMessage);
booco.login((err) => {
if (err) {
console.log('authorization error');
} else {
booco.log.info('Connected from script – Welcome!');
console.log('REST API logged on');
await booco.equipment.setChannel('Relay', 'toggleRelay1');
}
});
- Выполняется авторизация в REST API, отправляется команда на устройство Relay для переключения на 1-ый канал и производится подключение к серверу BOOCO. Если подключиться не удалось, выводится сообщение об ошибке:
booco.login().then(async () => {
booco.log.info('Connected from script - Welcome!');
console.log('REST API logged on');
const feedbacks = await booco.equipment.getFeedback('Relay');
console.log(feedbacks)
await booco.equipment.setChannel('Relay', 'toggleRelay1');
booco.connect(() => {
console.log('');
});
}).catch(async () => {
console.error ('authorization error');
});
- После подключения создается подписка на состояния следующих устройств: Relay, Projector 1, Projector 2, Player 1:
booco.on('connect', () => {
booco.equipment.subscribe(['Relay', 'Projector 1', 'Projector 2']);
booco.equipment.subscribe('Player 1');
});
- Создается подписка на изменения канала устройства Relay5 с указанием старого и нового каналов:
booco.equipment.on('Relay.relay5', (value, oldValue) => {
console.log(`Relay.relay5: ${oldValue} => ${value}`);
});
- Создается подписка на все фидбеки устройств Player 1, Projector 1 и Projector 2. Полученный массив данных выводится в лог:
booco.equipment.on('Player 1', (value) => {
console.log(value);
});
booco.equipment.on('Projector 1', (value) => {
console.log(value);
});
booco.equipment.on('Projector 2', (value) => {
onsole.log(value);
});
Метод connect(callback) служит для подключения к серверу BOOCO к порту TCP. Необходимо для использования механизма подписки. Параметр callback является необязательным. После подключения отправляет строку 'ping' с периодом PING_TIMEOUT (длительность 10000 мс). В ответ ожидает 'pong'. Если 'pong' не приходит, то разрывает соединение. При разрыве соединения (по любой причине) необходимо дождаться завершения RECONNECTION_TIMEOUT (длительность 10000 мс) и затем повторить попытку подключения. При подключении отправляется событие connect и вызывается callback с параметром null (если он задан). Данный метод рекомендуется вызывать после успешного выполнения метода login().
Пример использования
Выполняется подключение к серверу BOOCO. Если подключение установить не удалось, то выводится сообщение об ошибке. В случае успешного подключения информация об этом сохраняется в журнал. После этого создается подписка на все фидбеки устройств Projector 1, Projector 2 и Player 1.
booco.connect((err) => {
if (err) {
console.error(err.message)
}else{
console.info('Connection to server was successful')
booco.equipment.subscribe(['Relay', 'Projector 1', 'Projector 2']);
booco.equipment.subscribe('Player 1');
}
});
Метод callRestApi() служит для обращения к методам REST API, для которых нет обертки в библиотеке. Данный метод используется, в основном, как внутренний, но также может использоваться и как публичный.
Метод имеет следующие параметры:
- method — 'GET' - метод запроса (GET, POST, DELETE, PUT, PATCH);
- url — URL запроса;
- data — данные;
- dataType — тип данных (по умолчанию 'json') либо готовые данные для отправки в запросе (например, строка или Buffer);
Примеры использования
Отправляет запрос на конечную точку для получения массива данных (списка оборудования и его свойств) для всех устройств с типом 'pjlink-device':
booco.callRestApi(
{
method: 'GET',
url: '/api/v1/equipment?driver=pjlink-device',
data: '',
dataType: 'json'
}, (err, data) =>{
if(err){
console.error(err.message)
}else{
console.log(data)
}
})
В ответе приходит статус об успешном выполнении запроса и массив данных (параметры id, name, host, driver):
"status": "success",
"data": [
{
"_id": "qkd4zyoz8wWoopRQN",
"name": "Projector 1",
"host": "192.168.10.10",
"driver": "pjlink-device"
},
{
"_id": "rCpgsRnX4dnXNoAQA",
"name": "Projector 2",
"host": "192.168.10.11",
"driver": "pjlink-device"
}
]
Метод destroy() предназначен для уничтожения экземпляра BoocoRestApi (отключение от порта, удаление всех таймеров и т.д.).
Подписка на события реализована через механизм EventEmitter - метод on() и др.
Класс BoocoRestApi может отправлять следующие события:
- login — отправляется при успешной авторизации в REST API;
- connect — отправляется при успешном подключении к tcp-порту;
- error — отправляется при возникновении ошибок (в качестве параметра приходит ошибка).
Примеры использования
- Выполняется авторизация, создается подписка на событие по входу в систему с callback(error). При неуспешном входе выводит сообщение об ошибке. В случае успеха выводит сообщение 'REST API logged on':
booco.on('login', (err) => {
if(err){
console.error(err.message)
} else {
console.log('REST API logged on')
}
})
- Выполняется подключение к серверу Booco, создается подписка на событие по входу в систему с callback(error). При неуспешном входе выводит сообщение об ошибке. В случае успеха выводит сообщение 'REST API logged on':
booco.on('connect', (err) => {
if(err){
console.error(err.message)
} else {
console.info(‘server connection established’)
}
})
Класс DeviceFactory наследуется от класса EventEmitter.
При инициализации BoocoRestApi создается экземпляр объекта класса DeviceFactory и передается ссылка на BoocoRestApi для доступа к функциям REST API.
У класса нет публичных свойств.
Класс DeviceFactory имеет следующие методы:
- getFeedback(name, feedback);
- setChannel(name, channel, value);
- subscribe(nameOrNames).
Метод getFeedback(name, feedback) возвращает значение обратной связи (feedback) для устройства (name). Если feedback не указан, то возвращает значения всех обратных связей. Возвращает Promise.
Пример использования
Возвращает значение всех и одного feedback устройства Relay:
const allFeedback = await booco.equipment.getFeedback('Relay');
const feedback = await booco.equipment.getFeedback('Relay', 'relay1' );
console.info(allFeedback);
console.info(feedback);
Метод setChannel(name, channel, value) отправляет команду (channel) со значением (value) на устройство (name). Возвращает Promise.
Пример использования
Отправляет команду на устройство Relay установить 1-ый канал:
await booco.equipment.setChannel('Relay', 'toggleRelay1');
Метод subscribe(nameOrNames) выполняет подписку на уведомления, которые отправляются при изменении обратной связи устройства или устройств. nameOrNames - имя устройства или список имен устройств. Метод вызывается после получения события connect в BoocoRestApi.
Пример использования
Создает подписку на получение уведомлений при изменении обратной связи устройств Relay, Projector 1, Projector 2*,* а также устройства Player 1.
booco.equipment.subscribe(['Relay', 'Projector 1', 'Projector 2']);
booco.equipment.subscribe('Player 1');
Подписка на события реализуется через механизм EventEmitter - метод on() и др.
Класс DeviceFactory может отправлять следующие события:
- <name\> - массив данных, который содержит имя устройства, параметры объекта, содержащего старые и новые значения feedback;
- <name\>.\<feedback\> - массив данных, содержащий старое и новое значения feedback для указанного канала;
Примеры использования
Создает подписку на изменение 5 канала устройства Relay и получает новое и старое значения:
booco.equipment.on('Relay.relay5', (value, oldValue) => {
console.log(`Relay.relay5: ${oldValue} => ${value}`);
});
Экземпляр объекта класса Logger создается при инициализации BoocoRestApi. При инициализации передается ссылка на BoocoRestApi для доступа к функциям REST API.
У класса нет публичных свойств.
Класс Logger имеет следующие методы:
- info(message) - сохраняет в журнале (БД для хранения сообщений) информационное событие с текстом message;
Пример использования
console.info(err.message);
- warn(message) - сохраняет в журнале предупреждение с текстом message;
Пример использования
console.warn (err.message);
- error(message) - сохраняет в журнале ошибку message;
Пример использования
console.error(err.message);
- debug(message) - сохраняет в журнале отладочное событие с текстом message.
Пример использования
console.debug(err.message);
Готовые примеры скриптов хранятся в открытом репозитории на GitHub и доступны для загрузки по следующей ссылке: https://github.com/bladerunner2020/booco-rest-api/tree/master/src