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