Операции с устройствами (device)

Содержание

Обзор
Запросы
- Отправка команды устройствам
Коды ошибок

Обзор

Производит управление зарегистрированными SIP-устройствами путем отправки соответствующих SIP-запросов.

Запросы

HTTP verb Endpoint Описание

HTTP verb	Endpoint	Описание
`POST`	`/rest/v1/uc/sipusers/<id>/device`	Отправка команды устройствам

POST

/rest/v1/uc/sipusers/<id>/device

Отправка команды устройствам

Выполняется администратором домена.

Инициация отправки команды на устройства, зарегистрированные под учетной записью.

Каждому зарегистрированному устройству отправляется SIP-запрос: для info и message - SIP INFO и SIP MESSAGE, в остальных случаях - SIP NOTIFY, значение заголовка Event которого определяется полем operation либо задаётся напрямую полем event.

Поддерживаемые операции (operation):

sync - принудительная синхронизация настроек autoprovision (Event: check-sync; reboot=false).
restart - перезагрузка устройства (Event: check-sync; reboot=true).
resync - повторная синхронизация (Event: resync).
info - отправка SIP INFO с телом content.
message - отправка SIP MESSAGE с телом content.

Для sync и restart используется расширение Broadworks. Некоторые виды устройств не поддерживают синхронизацию без перезагрузки, тем самым эти команды неразличимы.

Table 1. Поля запроса
Поле	Тип	Описание
`operation`	str	`sync`, `restart`, `resync`, `info` или `message`. Обязательно, если не задано `event`.
`event`	str	Произвольное значение заголовка `Event` SIP NOTIFY. Используется вместо `operation`.
`headers`	str, [str]	Дополнительные SIP-заголовки в виде `Имя: значение`. Список объединяется построчно.
`content`	str	Тело запроса. Передаётся только вместе с `contentType`.
`contentType`	str	Значение заголовка `Content-Type` тела. Передаётся только вместе с `content`.

Ожидание ответа устройств - до 10 секунд.

Запрос

Пример запроса

POST /rest/v1/uc/sipusers/abcdabcd-abcd-abcd-abcd-abcdabcdabcd/device HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "operation": "sync"
}

Ответ

Пример успешного ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "true"
}

Поле result: "true" - получен ответ хотя бы от одного устройства; "false" - нет зарегистрированных устройств или ни одно не ответило; "error" - ошибка выполнения, описание в поле errormsg.

Пример запроса с произвольным событием

POST /rest/v1/uc/sipusers/abcdabcd-abcd-abcd-abcd-abcdabcdabcd/device HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "event": "check-sync",
  "headers": ["X-Custom: 1"],
  "content": "hello",
  "contentType": "text/plain"
}

Примеры неудачного ответа

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error_code": 1506,
  "error_message": "Access denied. Only administrator is allowed to perform request.",
  "error_details": {
     "msg_code":"10038"
  }
}

{
  "error_code":1413,
  "error_message":"Invalid params. Sipuser not found: 'abcdabcd-abcd-abcd-abcd-abcdabcdabcd'"
}

Коды ошибок

Описание структуры сообщения об ошибке.