Краткий список команд мониторинга

Подробное описание API оборудования MC04-3U находится здесь: ​sw:wiki:Api

=========================

1. Общие положения

1.1. Все команды и ответы на них передаются в виде json-объектов.

1.2. json-объект команды передается по протоколу HTTP POST или GET запросом (рекомендуется POST)

в параметре json URL /api.php, например: ​http://192.168.0.88/api.php?json={"cmd":"board"} В некоторых случаях вместо /api.php используется другой URL, о чем особо указывается ниже.

1.3. Вид команды передается в виде строки в поле "cmd", например {"cmd":"board"}.

1.4. При возникновении ошибки в процессе выполнения команды в ответе на команду присутствует

поле "error", значением которого является строка с описанием ошибки (при некоторых ошибках аутентификации вместо поля "error" может присутствовать поле "error2" - см. описание аутентификации ниже).

1.5. Признаком успешного выполнения команды является отсутствие поля "error" ("error2") в ответе.

1.6. В ответе на команду также присутствует поле "cmd" с тем же значением, что и в запросе.

1.7. Все строки, включая имена полей, используют кодировку UTF-8.

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

Для выполнения большинства команд требуется аутентификация. Для выполнения аутентификации требуется передать запрос "login" на URL /login.php. Параметры запроса аутентификации:

"login" - имя пользователя (строка); "password" - пароль пользователя (строка).

Пример запроса аутентификации:

​http://192.168.0.88/login.php?json={"cmd":"login","login":"admin","password":"labuda"}

В случае ошибки аутентификации в ответе на запрос присутствует поле "error" или "error2". При успешной аутентификации ответ сервера устанавливает cookies с данными аутентификации. Эти cookies должны присутствовать в последующих командах. Установленные данные аутентификации действительны в течение суток с момента их генерации.

В случае, если при передаче команды данные аутентификации отсутствуют, неверны или устарели (сгенерированы более суток назад), команда мониторинга не выполняется, и в ответе присутствует поле "error" со значением "not logged in". При получении этой ошибки необходимо повторно выполнить аутентификацию.

При наличии в запросе cookies с валиднми данными аутентификации в ответе на любую команду устанавливаются новые (обновленные) cookies. Таким образом, необходимость в повторной аутентификации возникает только если в течение суток блоку не передавалось ни одной команды.

3. Список команд.

3.1. Запрос списка плат

Список плат производится командой "board". Параметров у этой команды нет. Пример запроса:

{"cmd":"board"}

Ответ на команду "board" содержит поле "boards", содержащее массив хэшей, каждый из которых описывает один слот кассеты. Каждый хэш имеет следующие поля:

"slot" - номер слота (число);

"present" - признак присутствия платы (boolean).

Если в слоте присутствует плата, хэш дополнительно содержит следующие поля:

"type" - тип платы (число);

"variant" - вариант исполнения платы (число); "name" - название платы (строка); "alarm" - признак общей аварии платы (число); "comment" - комментарий пользователя (строка); "last_alarm" - последняя авария платы (строка); "last_alarm_time" - сремя начала последней аварии (число - UNIX time); "required" - при значении true плата является обязательной (и при ее отсутствии генерируется авария) (boolean).

Пример ответа:

{"cmd":"board","boards":[{"slot":1,"present":false},{"slot":9,"present":true,"required":false,"type":1,"variant":1,"name":"SW-01","alarm":0,"comment":"","last_alarm":"","last_alarm_time":0}]}

3.2. Запрос списка текущих аварий

Запрос списка текущих аварий производится командой "alarms". Параметров у этой команды нет. Пример запроса:

{"cmd":"alarms"}

Ответ на команду "alarms" содержит поле "alarms", содержащее массив хэшей, каждый из которых описывает одну аварию. Каждый хэш содержит следующие поля:

"slot" - номер слота, в котором возникла авария (число);

"oid" - oid аварии (переменная платы) (строка); "start" - время начала аварии (число, UNIX time); "prio" - приоритет аварии: 1 - срочная, 2 и более - не срочная (число); "name" - имя аварии (имя переменной из MIB платы) (строка); "confirmed" - значение true означает, что авария подтверждена пользователем (boolean).

Пример ответа:

{"cmd":"alarms","alarms":[{"confirmed":false,"slot":2,"oid":".7.2.1.0","prio":1,"start":1367822543,"name":"port 2: LOS (Loss of signal)"}]}

3.3. Запрос счетчиков обмена с платами по внутренней шине блока

Запрос счетчиков обмена с платами производится командой "slotcnt". Параметров у этой команды нет. Пример запроса:

{"cmd":"slotcnt"}

Ответ на команду "slotcnt" содержит поле "slots", содержащее массив хэшей, каждый из которых содержит счетчики одного слота кассеты. Каждый хэш содержит следующие поля:

"slot" - номер слота (число);

"rx_discarded" - счетчик rx_discarded (число); "rx_short" - счетчик rx_short (число); "rx_big" - счетчик rx_big (число); "rx_ok" - счетчик rx_ok (число); "rx_bad" - счетчик rx_bad (число); "tx_ok" - счетчик tx_ok (число); "tx_dropped" - счетчик tx_dropped (число); "rx_bytes" - счетчик rx_bytes (число); "tx_bytes" - счетчик tx_bytes (число); "un_requests" - счетчик un_requests (число).

Пример ответа:

{"cmd":"slotcnt","slots":[{"slot":1,"rx_discarded":0,"rx_short":12,"rx_big":32,"rx_ok":12,"rx_bad":78,"tx_ok":123,"tx_dropped":0,"rx_bytes:4323,"tx_bytes":7263,"un_requests":0}]}

3.4. Запрос (чтение) переменной платы

Запрос (чтение) переменной платы производится командой "snmpget". Этой команде требуется параметр "varlist", содержащий массив строк, каждая из которых представляет собой OID запрашиваемой переменной. OID состоит из элементов, представляющих собой число от 0 до 255 с точкой перед ним. При обращении к переменной платы первый элемент OID должен быть равен 4, второй элемент - номеру слота. Элементы OID начиная с третьего являются идентификатором переменной внутри платы. OID должен завершаться элементом 0. Пример запроса имени платы, установленной в слоте 9:

{"cmd":"snmpget","varlist":[".4.9.2.0"]}

Отвер на команду "snmpget" содержит поле "result", хэш. Ключами хэша являются OID запрошенных переменных, значением - хэши с результатом запроса переменной. Каждый хэш результата имеет следующие поля:

"oid" - OID переменной (строка);

"status" - признак успешности операции чтения (строка). Может принимать следующие значения:

"OK" - операция выполнена успешно; "Not found" - запрошенная переменная отсутствует (также этот статус возвращается в случае таймаута); "Error" - какая-то ошибка в процессе обработки запроса.

Если поле "status" имеет значение "OK", то в хэше также присутствует поле "value", содержащее прочитанное значение переменной. Пример ответа на запрос переменной .4.9.2.0:

{"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":"SW-01"}}}

Команда snmpget может содержать параметр "strings2data" типа boolean. В случае, если его значение равно true, значения переменных типа строка преобразуются в массив чисел, по одному на каждый байт строки. Пример запроса и ответа переменной .4.9.2.0 с параметром "strings2data":

{"cmd":"snmpget","varlist":[".4.9.2.0"],"strings2data":true} {"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":[83,87,45,48,49]}}}

3.5 Запрос (запись) переменной платы

Запрос (запись) переменной платы производится командой "snmpset". Этой команде требуется параметр "varlist", содержащий OID записываемой переменной и ее новое значение. Пример записи переменной:

{"cmd":"snmpset","varlist":{".4.14.6.0":3}}

Пример ответа на данную запись:

{"cmd":"snmpset","result":{".4.14.6.0":"OK"}}