class Rbeapi::Eapilib::EapiConnection
The EapiConnection
provides a base class for building eAPI connection instances with a specific transport for connecting to Arista EOS devices. This class handles sending and receiving eAPI calls using JSON-RPC. This class should not need to be directly instantiated.
Attributes
Public Class Methods
The connection contains the transport.
@param transport [Net::HTTP] The HTTP transport to use for sending
and receive eAPI request and response messages.
# File lib/rbeapi/eapilib.rb, line 136 def initialize(transport) @transport = transport @error = nil end
Public Instance Methods
Configures the connection authentication values (username and password). The authentication values are used to authenticate the eAPI connection. Using authentication is only required for connections that use Http or Https transports.
@param opts [Hash] The authentication parameters.
@option opts username [String] The username to use to
authenticate with eAPI. Default is 'admin'.
@option opts password [String] The password to use to
authenticate with eAPI. Default is ''.
# File lib/rbeapi/eapilib.rb, line 154 def authentication(opts = {}) @username = opts.fetch(:username, 'admin') @password = opts.fetch(:password, '') end
Executes the commands on the destination node and returns the response from the node.
@param commands [Array] The ordered list of commands to execute
on the destination node.
@param opts [Hash] Optional keyword arguments.
@option opts encoding [String] Used to specify the encoding to be
used for the response. Valid encoding values are json or text.
@option opts open_timeout
[Float] Number of seconds to wait for the
eAPI connection to open.
@option opts read_timeout
[Float] Number of seconds to wait for one
block of eAPI results to be read (via one read(2) call).
@return [Array<Hash>] This method will return the array of responses
for each command executed on the node.
@raise [CommandError] Raises a CommandError
if rescued from the
send method and adds the list of commands to the exception message.
@raise [ConnectionError] Raises a ConnectionError
if rescued and
adds the list of commands to the exception message.
# File lib/rbeapi/eapilib.rb, line 321 def execute(commands, opts = {}) @error = nil request = request(commands, opts) response = send(request, opts) return response['result'] rescue ConnectionError, CommandError => exc exc.commands = commands @error = exc raise end
Generates the eAPI JSON request message.
@example eAPI Request
{ "jsonrpc": "2.0", "method": "runCmds", "params": { "version": 1, "cmds": [ <commands> ], "format": [json, text], } "id": <reqid> }
@param commands [Array] The ordered set of commands that should
be included in the eAPI request.
@param opts [Hash] Optional keyword arguments.
@option opts id [String] The value to use for the eAPI request
id. If not provided,the object_id for the connection instance will be used.
@option opts format [String] The encoding formation to pass in
the eAPI request. Valid values are json or text. The default value is json.
@return [Hash] Returns a Ruby hash of the request message that is
suitable to be JSON encoded and sent to the destination node.
# File lib/rbeapi/eapilib.rb, line 207 def request(commands, opts = {}) id = opts.fetch(:reqid, object_id) format = opts.fetch(:format, 'json') cmds = [*commands] params = { 'version' => 1, 'cmds' => cmds, 'format' => format } { 'jsonrpc' => '2.0', 'method' => 'runCmds', 'params' => params, 'id' => id } end
This method will send the request to the node over the specified transport and return a response message with the contents from the eAPI response. eAPI responds to request messages with either a success message or failure message.
@example eAPI Response - success
{ "jsonrpc": "2.0", "result": [ {}, {}, { "warnings": [ <message> ] }, ], "id": <reqid> }
@example eAPI Response - failure
{ "jsonrpc": "2.0", "error": { "code": <int>, "message": <string>, "data": [ {}, {}, { "errors": [ <message> ] } ] }, "id": <reqid> }
@param data [Hash] A hash containing the body of the request
message. This should be a valid eAPI request message.
@option opts open_timeout
[Float] Number of seconds to wait for the
eAPI connection to open.
@option opts read_timeout
[Float] Number of seconds to wait for one
block of eAPI results to be read (via one read(2) call).
@return [Hash] Returns the response message as a Ruby hash object.
@raise [CommandError] Raised if an eAPI failure response is return
from the destination node.
# File lib/rbeapi/eapilib.rb, line 269 def send(data, opts) request = Net::HTTP::Post.new('/command-api') request.body = JSON.dump(data) request.basic_auth @username, @password open_timeout = opts.fetch(:open_timeout, @open_timeout) read_timeout = opts.fetch(:read_timeout, @read_timeout) begin @transport.open_timeout = open_timeout @transport.read_timeout = read_timeout response = @transport.request(request) decoded = JSON(response.body) if decoded.include?('error') code = decoded['error']['code'] msg = decoded['error']['message'] raise CommandError.new(msg, code) end rescue Timeout::Error raise ConnectionError, 'unable to connect to eAPI' end decoded end
Configures the connection timeout values (open_timeout
and read_timeout
). The timeout values are used for the eAPI connection.
@option opts open_timeout
[Float] Number of seconds to wait for the
eAPI connection to open. Default is DEFAULT_HTTP_OPEN_TIMEOUT.
@option opts read_timeout
[Float] Number of seconds to wait for one
block of eAPI results to be read (via one read(2) call). Default is DEFAULT_HTTP_READ_TIMEOUT.
# File lib/rbeapi/eapilib.rb, line 170 def timeouts(opts = {}) @open_timeout = opts.fetch(:open_timeout, DEFAULT_HTTP_OPEN_TIMEOUT) @read_timeout = opts.fetch(:read_timeout, DEFAULT_HTTP_READ_TIMEOUT) end