2.9. Работа с RPC API
Назначение
Служба RPC API позволяет пользователю настраивать и контролировать коммутатор посредством протокола удаленных вызовов процедур (RPC) используя стороннее ПО. В настоящее время служба поддерживает протокол JSON-RPC через HTTP вместе с базовой HTTP-аутентификацией.
Описание
Служба RPC API использует стандартный протокол JSON-RPC через HTTP для связи коммутатора и Вашего ПО. Пользователь может выполнять команды для CLI с помощью метода JSON-RPC: “executeCmds”. По умолчанию режим CLI находится в привилегированном режиме EXEC (#). Пользователь может отправить запрос JSON-RPC через запрос HTTP POST на URL-адрес: http://:/command-api. Подробные примеры запроса и ответа JSON-RPC показаны ниже.
JSON-RPC запрос
{
"params":[ Parameters for command
{
"format":"text", Expected response format, can be "text" or "json" ,
the default format is "text"
"version":1, The API version
"cmds":[ List of CLI commands
"show run", CLI command 1
"config t", CLI command 2
"vlan database", CLI command 3
"vlan 1-8", CLI command 4
"interface eth-0-1", CLI command 5
"switchport mode trunk", CLI command 6
"switchport trunk allowed vlan add 2", CLI command 7
"shutdown", CLI command 8
"end", CLI command 9
"show interface switchport" CLI command 10
]
}
],
"jsonrpc":"2.0", JSON RPC protocol version. Always 2.0.
"method":"executeCmds", Method to run the switch CLI commands
"id":"bb294ac9-d086-405f-a131-0cc84ad94493" JSON RPC unique identifier
}
JSON-RPC ответ
{
"jsonrpc":"2.0", JSON RPC protocol version. Always 2.0.
"id":"dba66eca-3930-4c61-8b41-98bedfabd3c7", JSON RPC unique identifier
"result":[ Result list of objects from each CLI command executed.
{
"sourceDetails":"version 7.0.6.fcs\n!\n... ", Output information of CLI Command 1.
The Original ASCII output information returned from CLI command if this command is successfully executed.
"errorCode":-1003, Error code if it is available.
"errorDesc":"unsupported command...", Error description if it is available.
"warnings":"% Invalid...", Warnings if it is available.
Formatted JSON object will also be returned if it is available.
},
{ }, Output information of CLI Command 2.
{ }, Output information of CLI Command 3.
{ }, Output information of CLI Command 4.
{ }, Output information of CLI Command 5.
{ }, Output information of CLI Command 6.
{ }, Output information of CLI Command 7.
{ }, Output information of CLI Command 8.
{ }, Output information of CLI Command 9.
{
"sourceDetails":" Interface name : eth-0-1\n Switchport mode : trunk\n ... \n"
} Output information of CLI Command 10.
]
}
Пример кода Python-клиента
Пример кода с использованием библиотеки “pyjsonrpc”:
import json, requests
url = "http:// 10.10.10.64:80/command-api"
username = "admin"
password = "admin"
cmd_list = ["show run", "config t", "vlan database", "vlan 111", "end", "show interface switchport interface eth-0-1"]
cmds = {
"method":"executeCmds",
"jsonrpc":"2.0",
"params": [{
"format":"text",
"version":1,
"cmds": cmd_list
}]
}
result = requests.post(url=url, data=json.dumps(cmds), auth=(username, password))
if result.status_code == 200:
for res in json.loads(result.content)['result']:
if 'sourceDetails' in res:
print(f"Reply:\n\n{res['sourceDetails']}")
else:
print(f"Error: {result.reason} \nCode: {result.status_code}")
Коды ошибок
Таблица 2.1 - коды ошибок для JSON-RPC 2.0
Код ошибки |
Описание |
---|---|
-32700 |
Ошибка парсинга |
-32600 |
Неверный запрос |
-32601 |
Метод не найден |
-32602 |
Неверный параметр |
-32603 |
Внутренняя ошибка |
Таблица 2.2 - коды ошибок для RPC API
Код ошибки |
Описание |
---|---|
-1000 |
Общая ошибка |
-2001 |
Ошибка JSON RPC API: версия API не поддерживается |
-2002 |
Ошибка JSON RPC API: необходимо указать “params” с помощью “cmds” в JSON RPC |
-2003 |
Ошибка JSON RPC API: формат ответа на команду не поддерживается |
-3001 |
Ошибка выполнения команды: время ожидания истекло |
-3002 |
Ошибка выполнения команды: команда не поддерживается |
-3003 |
Ошибка выполнения команды: несанкционированная команда |
-3004 |
Ошибка выполнения команды: строка не соответствует ни одной команде в текущем режиме |
-3005 |
Ошибка выполнения команды: ошибка конвертирования в JSON |
-3006 |
Ошибка выполнения команды: список команд слишком короткий |
-3007 |
Ошибка выполнения команды: список команд слишком длинный |
Настройка
Настройка службы RPC API
Шаг 1: Вход в режим “Global config”
Switch# configure terminal
Шаг 2: Включение службы RPC API
Switch(config)# service rpc-api enable
Шаг 3: Выход из режима “Global config”
Switch(config)# end
Дополнительно
Для отключения службы RPC API используется следующая команда:
Switch(config)# service rpc-api disable
Примечание
Порт по умолчанию - 80.
Настройка службы RPC API с HTTP-аутентификацией
Можно настроить режим HTTP-аутентификации службы RPC API. В настоящее время поддерживается только базовая HTTP-аутентификация.
При вводе неверного имя пользователя или пароля пользователь получит код состояния “401” (Несанкционированный доступ).
Шаг 1: Вход в режим “Global config”
Switch# configure terminal
Шаг 2: Имя пользователя и пароль, включение аутентификации RPC API
Switch(config)# username myuser password mypass privilege 4
Switch(config)# service rpc-api auth-mode basic
Шаг 3: Выход из режима “Global config”
Switch(config)# end
Шаг 4: Проверка
Switch# show services rpc-api
RPC API service configuration:
Server State : enable
Port : 80
Authentication Mode : basic
VRF : default
Примечание
Настройки HTTP-аутентификации службы RPC API вступят в силу после перезапуска этой службы или перезагрузки коммутатора.
Дополнительно
Для отключения аутентификации используется следующая команда:
Switch(config)# no service rpc-api auth-mode