=  Команда snmpget  =

== Назначение команды ==

Команда `snmpget` служит для запроса значений переменных плат блока MC04-DSL-3U (чтения переменных). 

== Ключи запроса ==

||  '''Ключ'''  ||  '''Тип значения'''  ||  '''обязательный'''  ||  '''Назначение'''  ||
||  cmd  ||  строка  ||  да  || "snmpget" - имя команды ||
||  varlist  ||  массив  ||  да  || список OID запрашиваемых переменных ||
||  strings2data  ||  логический  ||  нет  || формат возвращаемых значений строк ||

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

Переменные плат типа "строка" не всегда содержат в себе текст. Часто их значение представляет собой просто набор байтов (например в такой форме в плату могут передаваться ее настройки). Значение таких переменных не всегда может быть представлено в форме текстовой строки (так как не является валидной последовательностью UTF-8). Значения таких переменных может быть возвращено в форме массива байтов. Для этого необходимо указать в запросе параметр `strings2data`, имеющий значение `true`. Этот параметр влияет сразу на все переменные, указанные в запросе, если они имеют тип "строка". По умолчанию (при отсутствии в запросе параметра `strings2data`) значения переменных типа "строка" возвращаются в форме строк (как если бы было указано `"strings2data":false`). Рекомендуется использовать запросы без параметра `strings2data` только в тех случаях, когда известно, что значением всех запрашиваемых переменных типа "строка" является текст. В противном случае (если возможно получение нетекстовых бинарных данных) рекомендуется добавлять в запрос параметр `"strings2data":true`.

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

Запрос названий плат, установленных в слотах 2 и 3:

 `{"cmd":"snmpget","varlist":[".4.2.2.0", ".4.3.2.0"]}` (1)

Запрос переменных `.5.4.2.0` и `.7.1.1.0` из платы в слоте 17 с возвратом их значений в виде массива байт:

 `{"cmd":"snmpget","varlist":[".4.17.5.4.2.0", ".4.17.7.1.1.0"],"strings2data":true}` (2)

== Права доступа ==

Для выполнения команды `snmpget` не требуется наличия каких-либо прав. 

== Возвращаемые данные ==

В случае успешного выполнения команда `snmpget` возвращает ключ `result`, значением которого является объект, содержащий результаты чтения переменных. Ключами объекта `result` являются OID переменных, которые были переданы в поле `varlist` запроса. Значением является объект, содержащий результат чтения запрошенной переменной, и имеющий следующий формат:

||  '''Ключ'''  ||  '''Тип значения'''  ||  '''обязательный'''  ||  '''Описание'''  ||
||  oid  ||  строка  ||  да  || OID прочитанной переменной - значение совпадает с ключом объекта `result`. ||
||  status  ||  строка  ||  да  || Индикатор успешности чтения данной переменной - см. ниже ||
||  value  ||  разный  ||  нет  || Значение, прочитанной из переменной. Присутствует только в случае успешного чтения (`status` == "OK"). ||

Возможные значения поля `status`:

||  '''значение'''  ||  '''описание'''  ||
||  "OK"  || Чтение переменной выполнено успешно. Прочитанное значение содержится в поле `value`. ||
||  "Not found"  || Запрошенная переменная отсутствует (неверный OID) ||
||  "Access denied"  || Запрошенная переменная имеет тип "только для записи" ||
||  "Timeout"  || Плата, которая содержит переменную, не ответила на запрос чтения (время ожидания ответа истекло) ||
||  "Error"  || Плата, содержащая запрошенную переменную, вернула ошибку. ||

=== Примеры ответов: ===

Пример ответа на запрос (1):

{{{
{
  "cmd":"snmpget",
  "result": {
    ".4.2.2.0": {
      "oid":".4.2.2.0",
      "status":"OK",
      "value":"ST-124"
    },
    ".4.3.2.0": {
      "oid":".4.3.2.0",
      "status":"OK",
      "value":"E1-08"
    }
  }
}
}}}

Пример ответа на запрос (2):

{{{
{
  "cmd":"snmpget",
  "result": {
    ".4.17.5.4.2.0": {
      "oid":".4.17.5.4.2.0",
      "status":"Not found"
    },
    ".4.17.7.1.1.0": {
      "oid":".4.17.7.1.1.0",
      "status":"OK",
      "value": [1, 25, 6, 45, 0, 0, 215, 43, 23, 23, 0, 1, 0, 0, 255]
    }
  }
}
}}}

== Примечания ==

При запросе большого числа переменных из одной платы может оказаться, что плата не может поместить значения всех переменных в ответное сообщение, так как размер сообщения ограничен. В этом случае ответ на запрос будет содержать только часть запрошенных переменных. В подобном случае клиенту рекомендуется исключить из списка `varlist` первоначального запроса те переменные, значения которых получены, и повторно запросить только те переменные, ответ на которые не был получен. Пример:

 Запрос: `{"cmd":"snmpget","varlist":[".4.1.5.0", ".4.1.6.0", ".4.1.7.0", ".4.1.8.0", ".4.1.9.0"]}`

 Ответ:
 {{{
{
  "cmd":"snmpget",
  "result": {
    ".4.1.5.0": {
      "oid":".4.1.5.0",
      "status":"OK",
      "value": 55
    },
    ".4.1.6.0": {
      "oid":".4.1.6.0",
      "status":"OK",
      "value": 55
    },
    ".4.1.6.0": {
      "oid":".4.1.6.0",
      "status":"OK",
      "value": 66
    },
    ".4.1.7.0": {
      "oid":".4.1.7.0",
      "status":"OK",
      "value": 77
    }
  }
}
 }}}

 Запрос: `{"cmd":"snmpget","varlist":[".4.1.8.0", ".4.1.9.0"]}`

 Ответ:
 {{{
{
  "cmd":"snmpget",
  "result": {
    ".4.1.8.0": {
      "oid":".4.1.8.0",
      "status":"OK",
      "value": 88
    },
    ".4.1.9.0": {
      "oid":".4.1.9.0",
      "status":"OK",
      "value": 99
    }
  }
}
 }}}

== См. также ==

[ApiSnmpset команда snmpset]