АЛГО RESTful API

Информация о продукте: Руководство по RESTful API

API-интерфейс Algo RESTful позволяет пользователям получать доступ, манипулировать и запускать действия на конечных точках Algo IP в своей сети посредством запросов HTTP/HTTPS. Этот документ предоставляет единообразный и предопределенный набор операций без сохранения состояния, которые можно использовать для взаимодействия с устройствами Algo. API поддерживает запросы HTTP/HTTPS GET, POST и PUT с полезными нагрузками JSON.

Аутентификация

В Algo RESTful API доступны три типа аутентификации:

• Стандартная аутентификация (включена по умолчанию)
• Базовая аутентификация (необязательно)
• Нет метода аутентификации (не рекомендуется; только в целях тестирования)

Инструкции по использованию продукта: RESTful API

Предпосылки

Прежде чем включать RESTful API, убедитесь, что устройство имеет подключение к Интернету для доступа к предварительно настроенным серверам NTP. Если подключение к Интернету отсутствует, настройте локальный NTP-сервер и введите его IP-адрес.

Включение RESTful API

1. Войдите в web интерфейса и перейдите на вкладку «Дополнительные настройки администратора».
2. Прокрутите вниз до раздела «Поддержка API» и включите RESTful API.
3. Установите желаемый пароль (пароль по умолчанию: algo). Обратите внимание, что стандартная проверка подлинности включена по умолчанию.

Включение базовой аутентификации (необязательно)

1. В web интерфейс, перейдите на вкладку «Обслуживание системы» и загрузите конфигурацию file.
2. Откройте конфигурацию file в любом текстовом редакторе и добавьте следующую строку: api.auth.basic = 1
3. Сохраните и загрузите измененную конфигурацию file вернуться к устройству с помощью Restore Configuration File на вкладке «Обслуживание системы».

Включение метода без аутентификации (необязательно)

Чтобы включить метод без аутентификации, оставьте поле Пароль RESTful API пустым. Этот метод не рекомендуется и должен использоваться только в целях тестирования, поскольку он не обеспечивает безопасности.

Включение простого интерфейса управления (необязательно)

1. На web интерфейс, перейдите на вкладку «Обслуживание системы» и загрузите конфигурацию file.
2. Откройте конфигурацию file с помощью текстового редактора и добавьте две строки. Измените пароль по вашему желанию.
3. Админ.web.sci = 1
4. Sci.admin.pwd =
5. Сохраните и загрузите измененную конфигурацию file вернуться к устройству с помощью Restore Configuration File на вкладке «Обслуживание системы».

Аутентификация Sampкод

Пожалуйста, отправьте электронное письмо support@algosolutions.com если вам нужна стандартная или базовая аутентификацияampкод.
Для получения дополнительной поддержки звоните 604-454-3792 или электронная почта support@algosolutions.com

Информационные сообщения

Примечание
В примечании указаны полезные обновления, информация и инструкции, которым следует следовать.

Отказ от ответственности

Информация, содержащаяся в этом документе, считается точной во всех отношениях, но Algo не гарантирует ее. Информация может быть изменена без предварительного уведомления и не должна быть истолкована каким-либо образом как обязательство Algo или любого из ее филиалов или дочерних компаний. Algo, ее филиалы и дочерние компании не несут ответственности за любые ошибки или упущения в этом документе. Пересмотры этого документа или новые его редакции могут быть выпущены с учетом таких изменений. Algo не несет ответственности за ущерб или претензии, возникшие в результате любого использования данного руководства или таких продуктов, программного обеспечения, встроенного ПО и/или аппаратного обеспечения. Никакая часть этого документа не может быть воспроизведена или передана в любой форме и любыми средствами – электронными или механическими – для каких-либо целей без письменного разрешения Algo.
Для получения дополнительной информации или технической помощи в Северной Америке обратитесь в службу поддержки Algo:

Техническая поддержка Алго
1-604-454-3792
support@algosolutions.com

©2022 Algo — зарегистрированная торговая марка Algo Communication Products Ltd.
Все права защищены. Все остальные товарные знаки являются собственностью соответствующих владельцев. Все характеристики могут быть изменены без предварительного уведомления.

 ОБЩИЙ

Введение

В этом документе описывается, как можно использовать API-интерфейс Algo RESTful для доступа, управления и запуска действий на конечных точках Algo IP в вашей сети посредством запросов HTTP/HTTPS, а также несколько различных методов аутентификации с различными уровнями безопасности. Запрашивающие системы могут взаимодействовать с устройствами Algo посредством единообразного и предопределенного набора операций без сохранения состояния, определенных в этом документе. Запросы выполняются к URI ресурса с полезной нагрузкой JSON и вызывают ответ JSON. Запросы HTTP/HTTPS GET, POST и PUT отправляются к URI ресурса вместе с полезными данными JSON (список полезных данных см. в разделе команд).

 Аутентификация

Существует три типа аутентификации:

•  Стандартный (рекомендуется)
•  Базовый
•  Нет (не рекомендуется)

Стандартная аутентификация использует код аутентификации сообщения на основе хэша (HMAC) с дайджестом, закодированным SHA-256. Базовая аутентификация использует кодировку Base64 и должна использоваться только через HTTPS. Отказ от аутентификации следует использовать только с особой осторожностью, поскольку он не обеспечивает аутентификацию. Дополнительные сведения см. в разделе «Требования к аутентификации».

НАСТРОЙКА И КОНФИГУРАЦИЯ

Предпосылки

•  В этом документе предполагается, что на конечной точке Algo установлена ​​прошивка версии 3.3 или выше.
•  Для использования стандартной аутентификации разница во времени между запросчиком и устройствами Algo должна составлять менее 30 секунд.
• Убедитесь, что используется NTP (протокол сетевого времени). Адреса пользовательских NTP-серверов можно настроить на вкладке «Дополнительные настройки» → «Время».

Примечание
Предварительно настроенные NTP-серверы размещаются публично, поэтому для доступа к ним требуется подключение к Интернету. Если подключение к Интернету отсутствует, настройте локальный NTP-сервер и введите его IP-адрес.

• Убедитесь, что системное время устройства Algo настроено на правильный часовой пояс. Это можно сделать, перейдя на вкладку «Дополнительные настройки» → «Время».

 Включение RESTful API

1. Войти в систему web интерфейс и перейдите на вкладку «Дополнительные настройки» → «Администратор».
2. Прокрутите вниз до раздела «Поддержка API», включите RESTful API и установите желаемый пароль (пароль по умолчанию: algo).
   Примечание
   Стандартная аутентификация включена по умолчанию.

Включить базовую аутентификацию (необязательно)

1. В web интерфейсе, перейдите на вкладку «Система» → «Обслуживание» и загрузите конфигурацию. file.
2. Откройте конфигурацию file в любом текстовом редакторе и добавьте следующую строку: api.auth.basic = 1
3.  Сохраните и загрузите измененную конфигурацию file вернуться к устройству с помощью Restore Configuration File функция на вкладке Система → Обслуживание.

Нет метода аутентификации (необязательно)

Чтобы включить метод без аутентификации, оставьте поле Пароль RESTful API пустым. Этот метод не рекомендуется и должен использоваться только в целях тестирования, поскольку он не обеспечивает безопасности.

Включение простого интерфейса управления (необязательно)

1. На web интерфейсе, перейдите на вкладку «Система» → «Обслуживание» и загрузите конфигурацию. file.
2.  Откройте конфигурацию file с помощью текстового редактора и добавьте две строки. Изменить по вашему желанию пароль. Админ.web.sci = 1
   Sci.admin.pwd =
3.  Сохраните и загрузите измененную конфигурацию file вернуться к устройству с помощью Restore Configuration File функция на вкладке Система → Обслуживание.

ТРЕБОВАНИЯ К АУТЕНТИФИКАЦИИ

Пожалуйста, отправьте электронное письмо support@algosolutions.com если вам нужна стандартная или базовая аутентификацияampкод.

Стандартный запрос аутентификации с полезной нагрузкой JSON

Обязательные заголовки в HTTP/HTTPS-запросе
> Тип контента: «приложение/json»
> Content-MD5: [content_md5] Примерample
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Авторизация: hmac admin:[nonce]:[hmac_output]
Заголовки авторизации состоят из:

1. Строка «hmac admin», за которой следует двоеточие «:».
2. Nonce — случайное или неповторяющееся значение, за которым следует двоеточие «:».
3. Hmac_output — генерируется паролем RESTful API (секретным ключом), настроенным на вашем устройстве, и входом HMAC, как показано ниже:
   [метод_запроса]:[request_uri]:[content_md5]:[тип_контента]:[времяamp]:[одноразовый номер]

Вход HMACample: (используя «алгоритм» в качестве секретного ключа)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Сгенерируйте HMAC с паролем и входной строкой HMAC в виде дайджеста с использованием SHA-256:
Выход HMAC example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Дата: день, число месяц, год час:мин:сек GMT
Example
Дата: четверг, 22 сентября 2022 г., 02:33:07 по Гринвичу
Стандартная аутентификация с использованием полезной нагрузкиampль:

 Стандартный запрос аутентификации без полезных данных JSON

Идентичен версии 3.1, за исключением заголовков, связанных с содержимым, и ввода hmac.
Ввод HMAC: [метод_запроса]:[ури_запроса]:[времяamp]:[nonce] Ввод HMAC, напримерample: (используя «алгоритм» в качестве секретного ключа)
ПОЛУЧИТЬ:/api/settings/audio.page.vol:1601312252:49936
Сгенерируйте HMAC с паролем и входной строкой HMAC, используя SHA-256:
Выход HMAC example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Стандартная аутентификация без полезной нагрузкиampль:

 Базовый запрос аутентификации

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

Авторизация: базовая [base64]
Exampль:
Авторизация: Базовая YWRtaW46YWxnbwo=
Базовая аутентификацияampль:

КОМАНДЫ

 Команды RESTful API

Ниже приведен список всех поддерживаемых API-команд.

Примечание
Запрос PUT изменяет или создает постоянный ресурс, который выдерживает перезагрузку, тогда как запрос POST управляет устройством только для текущего сеанса.

Описание	Метод	URI	Полезная нагрузка Параметры	Возвращаться Example	Продукт	FW
Получить значение определенного параметра.	ПОЛУЧАТЬ	/api/settings/[key-name] Например,/api/settings/audio.page.vol	Н/Д	{"audio.page.vol": "-18дБ"}	Все	> 3.3
Возвращает уровень окружающего шума, измеренный в децибелах. Компенсацию окружающего шума необходимо включить на вкладке «Основные настройки» -> «Функции».	ПОЛУЧАТЬ	/api/info/audio.noise.level	Н/Д	{"audio.noise.level": 72}	Динамики Дисплеи Динамики	> 3.3
Извлеките состояние релейной входной клеммы.	ПОЛУЧАТЬ	/api/info/input.relay.status	Н/Д	{“input.relay.status”: “idle”} или {“input.relay.status”: “active”}	Все продукты с релейным входом, кроме 8063. См. ниже.	> 4.1
Извлеките состояние клемм входа 1 или входа 2.	ПОЛУЧАТЬ	/api/info/input.relay1.status или /api/info/input.relay2.status	Н/Д	{"input.relay1.status": "ожидание"} или {"input.relay1.status": "активно"}	8063	> 4.1
Получить список тонов files в настоящее время установлен.	ПОЛУЧАТЬ	/API/информация/тональный список	Н/Д	{"tonelist":["bell-na.wav",bell uk.wav",",buzzer.wav",…]}	Все	> 5.0
Получите информацию об устройстве, отображаемую на странице состояния.	ПОЛУЧАТЬ	/API/информация/статус	Н/Д	Полный список информации на вкладке Статус.	Все	> 5.4

Получите информацию о продукте, которая отображается на странице «О программе».	ПОЛУЧАТЬ	/api/информация/о	Н/Д	Вся информация представлена ​​на вкладке «О программе».	Все	> 5.4
Активируйте стробоскоп с желаемыми параметрами цвета и рисунка.	ПОЧТА	/API/элементы управления/строб/старт	шаблон: {0–15} color1: {синий, красный, янтарный, зеленый} color2: {синий, красный, янтарный, зеленый}ledlvl: {1 – 255} удержание: {правда, ложь}	Н/Д	8128(Г2) 8138 8190С	> 3.3
Остановите стробоскоп.	ПОЧТА	/API/элементы управления/строб/стоп	Н/Д	Н/Д	8128(Г2) 8138 8190С	> 3.3
Воспроизведите тон один раз или зациклите его.	ПОЧТА	/API/элементы управления/тон/старт	путь: {tone} т.е. перезвон.wav цикл: {true, false} или {0, 1} например {"путь":"chime.wav", "петля":true}	Н/Д	Колонки 8301 8373 8028(Г2) 8201 8039	> 3.3
Остановите тон.	ПОЧТА	/API/элементы управления/тон/стоп	Н/Д	Н/Д	Колонки 8301 8373 8028(Г2) 8201 8039	> 3.3
Позвоните на внутренний номер телефона с помощью заранее записанного сообщения.	ПОЧТА	/апи/управление/вызов/старт	{"расширение":"2099", «tone»:»gong.wav», «interval»:»0″, «maxdur»:»10″}	Н/Д	Колонки 8301 8410 8420	> 3.3
Завершите вызов.	ПОЧТА	/апи/управление/вызов/стоп	Н/Д	Н/Д	Колонки 8301 8410 8420	> 3.3

Инициировать односторонний пейджинговый вызов. Устройство будет получать аудиопоток от целевого расширения.	ПОЧТА	/api/controls/вызов/страница	{"расширение":" ”}	Н/Д	Колонки 8410 8420	> 5.3.4
Перезагрузите целевую конечную точку.	ПОЧТА	/api/controls/перезагрузка	Н/Д	Н/Д	Все	> 3.3
Откройте дверь. «local» управляет локальным реле «netdc1» управляет удаленным сетевым дверным контроллером (8063)	ПОЧТА	/api/controls/дверь/разблокировать	DoorID: {local, netdc1} *По желанию	Н/Д	8039 8028(Г2) 8201 8063	> 3.3
Закрыть дверь.	ПОЧТА	/api/управление/дверь/замок	DoorID: {local, netdc1} *По желанию	Н/Д	8039 8028(Г2) 8201 8063	> 3.3
Включите реле вспомогательного выхода 24 В.	ПОЧТА	API/контроля/24В/включить	Н/Д	Н/Д	8063	> 5.0
Отключите реле вспомогательного выхода 24 В.	ПОЧТА	API/контроля/24В/отключить	Н/Д	Н/Д	8063	> 5.0
Включите выходное реле.	ПОЧТА	/api/controls/реле/включить	Н/Д	Н/Д	8063	> 5.0
Отключите выходное реле.	ПОЧТА	/api/controls/реле/отключить	Н/Д	Н/Д	8063	> 5.0
Проверьте сервер прошивки Algo на наличие последней версии прошивки.	ПОЧТА	/API/управления/обновить/проверить	Н/Д	{"версия": "обновлено"} или {"версия": " ”}	Все	> 4.1
Проверьте сервер прошивки Algo на наличие последней версии прошивки и обновите ее до этой версии.	ПОЧТА	/API/элементы управления/обновление/начало	Н/Д	{“статус”: “обновлено”} или {“статус”: “обновление », «url”: url>} или {"положение дел": " ”}	Все	> 4.1
Отображение изображения или узора на экране.	ПОЧТА	/api/controls/screen/start	Видеть ниже	Н/Д	8410 8420	> 5.3.4
Остановите шаблон экрана и вернитесь к экрану по умолчанию.	ПОЧТА	/api/controls/экран/стоп	Н/Д	Н/Д	8410 8420	> 5.3.4

Перезапустите основное приложение.	ПОЧТА	/api/controls/перезагрузка	Н/Д	Н/Д	Все	> 5.3.4
Начните слушать прямой аудиопоток. Настройте номер порта, на который отправляется поток.	ПОЧТА	/api/controls/rx/start	{"порт": }	Н/Д	Все	> 5.3.4
Перестаньте слушать прямой аудиопоток.	ПОЧТА	/api/controls/rx/stop	Н/Д	Н/Д	Все	> 5.3.4
Установите многоадресный режим.	ПОМЕЩАТЬ	/API/состояние/mcast/обновление/	{"режим":"отправитель", "адрес": , «порт»: , «type»:»rtp»} или {»mode»:»sender», «address»: , «порт»: , «тип»: «поли», «группа»:1} **Примечание**: Если перед этой командой используется control/tone/start, тон будет воспроизводиться с использованием текущих настроек на web UI.	Н/Д	8301	> 5.0
Вставьте значение в определенный параметр из полезных данных JSON.	ПОМЕЩАТЬ	/апи/настройки	параметр: {значение} например {"audio.page.vol": "-3дБ"}	Н/Д	8180(Г2) 8186 8190 8190С 8301 8373	> 3.3

 Команды простого интерфейса управления (SCI)

Все SCI-команды являются GET-запросами и имеют общие параметры «usi» и «admin» для аутентификации.
Exampль:
ПОЛУЧИТЬ http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Описание	URI	Дополнительный Полезная нагрузка Параметры	Продукция	FW
Открой дверь. «local» управляет локальным реле «netdc1» управляет удаленным сетевым дверным контроллером (8063)	/sci/controls/сделать или/разблокировать	DoorID: {local, netdc1} *По желанию	8039 8028(Г2) 8201 8063	> 3.3
Закрыть дверь.	/sci/controls/сделать или/заблокировать	DoorID: {local, netdc1} *По желанию	8039 8028(Г2) 8201 8063	> 3.3
Воспроизведите тон один раз или зациклите его.	/sci/controls/to ne/start	путь: {tone} т.е. перезвон.wav цикл: {true, false} или {0, 1}	Все	> 3.3
Остановите тон.	/sci/controls/чтобы не/стоп	Н/Д	Все	> 3.3
Активируйте стробоскоп с желаемыми параметрами цвета и рисунка.	/sci/controls/strobe/start	узор: {0 – 15} цвет 1: {синий, красный, янтарный, зеленый} color2: {синий, красный, янтарный, зеленый} ledlvl: {1 – 255} удержание: {true, false}	8128(Г2) 8138 8190С	> 3.3
Остановите стробоскоп.	/sci/controls/стробоскоп/стоп	Н/Д	8128(Г2) 8138 8190С	> 3.3

Документы/Ресурсы

	АЛГО RESTful API [pdf] Руководство пользователя AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	АЛГО RESTful API [pdf] Руководство пользователя AL061-GU-CP000API-230717, RESTful API, RESTful, API

Ссылки

• Руководство пользователя