Changes between Initial Version and Version 1 of Mc04-3uCmd


Ignore:
Timestamp:
Oct 4, 2016, 12:02:42 PM (8 years ago)
Author:
san
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Mc04-3uCmd

    v1 v1  
     1'''Список команд мониторинга'''
     2=========================
     3
     41. Общие положения
     5
     61.1. Все команды и ответы на них передаются в виде json-объектов.
     7
     81.2. json-объект команды передается по протоколу HTTP POST или GET запросом (рекомендуется POST)
     9    в параметре json URL /api.php, например: http://192.168.0.88/api.php?json={"cmd":"board"}
     10    В некоторых случаях вместо /api.php используется другой URL, о чем особо указывается ниже.
     11
     121.3. Вид команды передается в виде строки в поле "cmd", например {"cmd":"board"}.
     13
     141.4. При возникновении ошибки в процессе выполнения команды в ответе на команду присутствует
     15     поле "error", значением которого является строка с описанием ошибки (при некоторых ошибках
     16     аутентификации вместо поля "error" может присутствовать поле "error2" - см. описание аутентификации ниже).
     17
     181.5. Признаком успешного выполнения команды является отсутствие поля "error" ("error2") в ответе.
     19
     201.6. В ответе на команду также присутствует поле "cmd" с тем же значением, что и в запросе.
     21
     221.7. Все строки, включая имена полей, используют кодировку UTF-8.
     23
     242. Аутентификация
     25
     26   Для выполнения большинства команд требуется аутентификация. Для выполнения аутентификации
     27   требуется передать запрос "login" на URL /login.php. Параметры запроса аутентификации:
     28        "login" - имя пользователя (строка);
     29        "password" - пароль пользователя (строка).
     30   Пример запроса аутентификации:
     31       http://192.168.0.88/login.php?json={"cmd":"login","login":"admin","password":"labuda"}
     32   В случае ошибки аутентификации в ответе на запрос присутствует поле "error" или "error2".
     33   При успешной аутентификации ответ сервера устанавливает cookies с данными аутентификации. Эти cookies
     34   должны присутствовать в последующих командах. Установленные данные аутентификации действительны в течение
     35   суток с момента их генерации.
     36
     37   В случае, если при передаче команды данные аутентификации отсутствуют, неверны
     38   или устарели (сгенерированы более суток назад), команда мониторинга не выполняется, и в ответе присутствует поле
     39   "error" со значением "not logged in". При получении этой ошибки необходимо повторно выполнить аутентификацию.
     40
     41   При наличии в запросе cookies с валиднми данными аутентификации в ответе на любую команду устанавливаются новые
     42   (обновленные) cookies. Таким образом, необходимость в повторной аутентификации возникает только если в течение суток
     43   блоку не передавалось ни одной команды.
     44
     453. Список команд.
     46
     473.1. Запрос списка плат
     48
     49   Список плат производится командой "board". Параметров у этой команды нет.
     50   Пример запроса:
     51        {"cmd":"board"}
     52   Ответ на команду "board" содержит поле "boards", содержащее массив хэшей, каждый из которых описывает один слот кассеты.
     53   Каждый хэш имеет следующие поля:
     54        "slot" - номер слота (число);
     55        "present" - признак присутствия платы (boolean).
     56   Если в слоте присутствует плата, хэш дополнительно содержит следующие поля:
     57        "type" - тип платы (число);
     58        "variant" - вариант исполнения платы (число);
     59        "name" - название платы (строка);
     60        "alarm" - признак общей аварии платы (число);
     61        "comment" - комментарий пользователя (строка);
     62        "last_alarm" - последняя авария платы (строка);
     63        "last_alarm_time" - сремя начала последней аварии (число - UNIX time);
     64        "required" - при значении true плата является обязательной (и при ее отсутствии генерируется авария) (boolean).
     65    Пример ответа:
     66        {"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}]}
     67
     683.2. Запрос списка текущих аварий
     69
     70   Запрос списка текущих аварий производится командой "alarms". Параметров у этой команды нет.
     71   Пример запроса:
     72        {"cmd":"alarms"}
     73   Ответ на команду "alarms" содержит поле "alarms", содержащее массив хэшей, каждый из которых описывает одну аварию.
     74   Каждый хэш содержит следующие поля:
     75        "slot" - номер слота, в котором возникла авария (число);
     76        "oid" - oid аварии (переменная платы) (строка);
     77        "start" - время начала аварии (число, UNIX time);
     78        "prio" - приоритет аварии: 1 - срочная, 2 и более - не срочная (число);
     79        "name" - имя аварии (имя переменной из MIB платы) (строка);
     80        "confirmed" - значение true означает, что авария подтверждена пользователем (boolean).
     81    Пример ответа:
     82        {"cmd":"alarms","alarms":[{"confirmed":false,"slot":2,"oid":".7.2.1.0","prio":1,"start":1367822543,"name":"port 2: LOS (Loss of signal)"}]}
     83
     843.3. Запрос счетчиков обмена с платами по внутренней шине блока
     85
     86   Запрос счетчиков обмена с платами производится командой "slotcnt". Параметров у этой команды нет.
     87   Пример запроса:
     88        {"cmd":"slotcnt"}
     89   Ответ на команду "slotcnt" содержит поле "slots", содержащее массив хэшей, каждый из которых содержит счетчики одного слота кассеты.
     90   Каждый хэш содержит следующие поля:
     91        "slot" - номер слота (число);
     92        "rx_discarded" - счетчик rx_discarded (число);
     93        "rx_short" - счетчик rx_short (число);
     94        "rx_big" - счетчик rx_big (число);
     95        "rx_ok" - счетчик rx_ok (число);
     96        "rx_bad" - счетчик rx_bad (число);
     97        "tx_ok" - счетчик tx_ok (число);
     98        "tx_dropped" - счетчик tx_dropped (число);
     99        "rx_bytes" - счетчик rx_bytes (число);
     100        "tx_bytes" - счетчик tx_bytes (число);
     101        "un_requests" - счетчик un_requests (число).
     102    Пример ответа:
     103        {"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}]}
     104
     1053.4. Запрос (чтение) переменной платы
     106
     107   Запрос (чтение) переменной платы производится командой "snmpget". Этой команде требуется параметр "varlist", содержащий
     108   массив строк, каждая из которых представляет собой OID запрашиваемой переменной. OID состоит из элементов, представляющих собой
     109   число от 0 до 255 с точкой перед ним. При обращении к переменной платы первый элемент OID должен быть равен 4,
     110   второй элемент - номеру слота. Элементы OID начиная с третьего являются идентификатором переменной внутри платы.
     111   OID должен завершаться элементом 0.
     112   Пример запроса имени платы, установленной в слоте 9:
     113        {"cmd":"snmpget","varlist":![".4.9.2.0"]}
     114   Отвер на команду "snmpget" содержит поле "result", хэш. Ключами хэша являются OID запрошенных переменных, значением - хэши
     115   с результатом запроса переменной. Каждый хэш результата имеет следующие поля:
     116        "oid" - OID переменной (строка);
     117        "status" - признак успешности операции чтения (строка). Может принимать следующие значения:
     118                "OK" - операция выполнена успешно;
     119                "Not found" - запрошенная переменная отсутствует (также этот статус возвращается в случае таймаута);
     120                "Error" - какая-то ошибка в процессе обработки запроса.
     121   Если поле "status" имеет значение "OK", то в хэше также присутствует поле "value", содержащее прочитанное значение переменной.
     122   Пример ответа на запрос переменной .4.9.2.0:
     123        {"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":"SW-01"}}}
     124   Команда snmpget может содержать параметр "strings2data" типа boolean. В случае, если его значение равно true,
     125   значения переменных типа строка преобразуются в массив чисел, по одному на каждый байт строки. Пример запроса и ответа
     126   переменной .4.9.2.0 с параметром "strings2data":
     127        {"cmd":"snmpget","varlist":![".4.9.2.0"],"strings2data":true}
     128        {"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":![83,87,45,48,49]}}}
     129
     1303.5 Запрос (запись) переменной платы
     131   
     132    Запрос (запись) переменной платы производится командой "snmpset". Этой команде требуется параметр "varlist", содержащий
     133    OID записываемой переменной и ее новое значение.
     134    Пример записи переменной:
     135     {"cmd":"snmpset","varlist":{".4.14.6.0":3}}
     136    Пример ответа на данную запись:
     137     {"cmd":"snmpset","result":{".4.14.6.0":"OK"}}