ovirtsdk4 API documentation

class Connection

This class is responsible for managing an HTTP connection to the engine server. It is intended as the entry point for the SDK, and it provides access to the system service and, from there, to the rest of the services provided by the API.

Ancestors (in MRO)

Connection
__builtin__.object

Instance variables

var url

Returns a string containing the base URL used by this connection.

Methods

def __init__(

self, url=None, username=None, password=None, token=None, insecure=False, ca_file=None, debug=False, log=None, kerberos=False, timeout=0, compress=True, sso_url=None, sso_revoke_url=None, sso_token_name='access_token', headers=None, pipeline=0, connections=0)

Creates a new connection to the API server.

This method supports the following parameters:

url: A string containing the base URL of the server, usually something like https://server.example.com/ovirt-engine/api.
username: The name of the user, something like admin@internal.
password: The name password of the user.
token: : The token to be used to access API. Optionally, user can use token, instead of username and password to access API. If user don’t specify token parameter, SDK will automatically create one.
insecure: A boolean flag that indicates if the server TLS certificate and host name should be checked.
ca_file: A PEM file containing the trusted CA certificates. The certificate presented by the server will be verified using these CA certificates. If ca_file parameter is not set, system wide CA certificate store is used.
debug: A boolean flag indicating if debug output should be generated. If the value is True and the log parameter isn’t None then the data sent to and received from the server will be written to the log. Be aware that user names and passwords will also be written, so handle it with care.
log: The logger where the log messages will be written.
kerberos: A boolean flag indicating if Kerberos authentication should be used instead of the default basic authentication.
timeout: The maximum total time to wait for the response, in seconds. A value of zero (the default) means wait for ever. If the timeout expires before the response is received an exception will be raised.
compress: A boolean flag indicating if the SDK should ask the server to send compressed responses. The default is True. Note that this is a hint for the server, and that it may return uncompressed data even when this parameter is set to True. Note that compression will be disabled if user pass debug parameter set to true, so the debug messages are in plain text.
sso_url: A string containing the base SSO URL of the serve. Default SSO url is computed from the url if no sso_url is provided.
sso_revoke_url: A string containing the base URL of the SSO revoke service. This needs to be specified only when using an external authentication service. By default this URL is automatically calculated from the value of the url parameter, so that SSO token revoke will be performed using the SSO service that is part of the engine.
sso_token_name: The token name in the JSON SSO response returned from the SSO server. Default value is access_token.
headers: A dictionary with headers which should be send with every request.
connections: The maximum number of connections to open to the host. If the value is 0 (the default) then the number of connections will be unlimited.
pipeline: The maximum number of request to put in an HTTP pipeline without waiting for the response. If the value is 0 (the default) then pipelining is disabled.

def authenticate(

self)

Return token which can be used for authentication instead of credentials. It will be created, if it not exists, yet. By default the token will be revoked when the connection is closed, unless the logout parameter of the close method is False.

def check_json_content_type(

self, response)

Checks that the content type of the given response is JSON. If it is JSON then it does nothing. If it isn’t JSON then it raises an exception.

response: The HTTP response to check.

def check_xml_content_type(

self, response)

Checks that the content type of the given response is XML. If it is XML then it does nothing. If it isn’t XML then it raises an exception.

response: The HTTP response to check.

def close(

self, logout=True)

Releases the resources used by this connection.

logout: A boolean, which specify if token should be revoked, and so user should be logged out.

def follow_link(

self, obj)

Follows the href attribute of this object, retrieves the object and returns it.

def is_link(

self, obj)

Indicates if the given object is a link. An object is a link if it has an href attribute.

def send(

self, request)

Sends an HTTP request and waits for the response.

This method is intended for internal use by other components of the SDK. Refrain from using it directly, as backwards compatibility isn’t guaranteed.

This method supports the following parameters.

request: The Request object containing the details of the HTTP request to send.

The returned value is a Request object containing the details of the HTTP response received.

def service(

self, path)

Returns a reference to the service corresponding to the given path. For example, if the path parameter is vms/123/diskattachments then it will return a reference to the service that manages the disk attachments for the virtual machine with identifier 123.

If there is no service corresponding to the given path an exception will be raised.

def system_service(

self)

Returns the reference to the root of the services tree.

The returned value is an instance of the SystemService class.

def test(

self, raise_exception=False)

Tests the connectivity with the server. If connectivity works correctly it returns True. If there is any connectivy problem it will either return False or raise an exception if the raise_exception parameter is True.

def wait(

self, context, failed_auth=False)

class ConnectionBuilder

This class is a mechanism to simplify the repeated creation of multiple connections. It stores the connection parameters given in its constructor, and has a single build method that is equivalent to calling the constructor of the Connection class. Typical use will be like this:

# Create the builder once:
builder = ConnectionBuilder(
    url='https://enginer40.example.com/ovirt-engine/api',
    username='admin@internal',
    password='redhat123',
    ca_file='ca.pem',
)

# Create and use first connection:
with builder.build() as connection:
   ...

# Create and use a second connection:
with builder.build() as connection:
   ...

Ancestors (in MRO)

ConnectionBuilder
__builtin__.object

Methods

def __init__(

self, **kwargs)

Creates a new connection builder. The parameters are the same accepted by the constructor of the Connnection class.

def build(

self)

Creates a new connection using the parameters passed to the constructor, and returns it.

class Error

General exception which is thrown by SDK, indicates that some exception happened in SDK.

Ancestors (in MRO)

Error
exceptions.Exception
exceptions.BaseException
__builtin__.object

Class variables

var args

var message

Instance variables

var code

var fault

Methods

def __init__(

self, message, code=None, fault=None)

Creates an instance of Error class.

message: The exception message.
code: An error code associated to the error. For HTTP related errors, this will be the HTTP response code returned by the server. For example, if retrieving of a virtual machine fails because it doesn’t exist this attribute will contain the integer value 404. Note that this may be nil if the error is not HTTP related.
fault: The Fault object associated to the error.