OpenStack::Client - A cute little client to OpenStack services
# # First, connect to an API endpoint via the Keystone # authorization service # use OpenStack::Client::Auth (); my $endpoint = 'http://openstack.foo.bar:5000/v2.0'; my $auth = OpenStack::Client::Auth->new($endpoint, 'tenant' => $ENV{'OS_TENANT_NAME'}, 'username' => $ENV{'OS_USERNAME'}, 'password' => $ENV{'OS_PASSWORD'} ); my $glance = $auth->service('image', 'region' => $ENV{'OS_REGION_NAME'} ); my @images = $glance->all('/v2/images', 'images'); # # Or, connect directly to an API endpoint by URI # use OpenStack::Client (); my $endpoint = 'http://glance.foo.bar:9292'; my $glance = OpenStack::Client->new($endpoint, 'token' => { 'id' => 'foo' } ); my @images = $glance->all('/v2/images', 'images');
OpenStack::Client is a no-frills OpenStack API client which provides generic access to OpenStack APIs with minimal remote service discovery facilities; with a minimal client, the key understanding of the remote services are primarily predicated on an understanding of the authoritative OpenStack API documentation:
OpenStack::Client
http://developer.openstack.org/api-ref.html
Authorization, authentication, and access to OpenStack services such as the OpenStack Compute and Networking APIs is made convenient by OpenStack::Client::Auth. Further, some small handling of response body data such as obtaining the full resultset of a paginated response is handled for convenience.
Ordinarily, a client can be obtained conveniently by using the services() method on a OpenStack::Client::Auth object.
services()
OpenStack::Client->new($endpoint, %opts)
Create a new OpenStack::Client object connected to the specified $endpoint. The following values may be specified in %opts:
token
A token obtained from a OpenStack::Client::Auth object.
These methods are useful for identifying key attributes of an OpenStack service endpoint client.
$client->endpoint()
Return the absolute HTTP URI to the endpoint this client provides access to.
$client->token()
If a token object was specified when creating $client, then return it.
$client
$client->call($args)
Perform a call to the service endpoint using named arguments in the hash. The following arguments are required:
method
path
The following arguments are optional:
headers
Headers are case insensitive; if duplicate header values are declared under different cases, it is undefined which headers shall take precedence. The following headers are sent by default:
Defaults to application/json, text/plain.
application/json, text/plain
Defaults to identity, gzip, deflate, compress.
identity, gzip, deflate, compress
Defaults to application/json, although some API calls (e.g., a PATCH) expect a different type; the case of an image update, the expected type is application/openstack-images-v2.1-json-patch or some version thereof.
application/json
application/openstack-images-v2.1-json-patch
Except for X-Auth-Token, any additional token will be added to the request.
X-Auth-Token
body
This may be a scalar reference to a data structure to be encoded to JSON, or a CODE reference to a subroutine which, when called, will return a chunk of data to be supplied to the API endpoint; the stream is ended when the supplied subroutine returns an empty string or undef.
handler
When specified, this function will be called with two arguments; the first argument is a scalar value containing a chunk of data in the response body, and the second is a scalar reference to a HTTP::Response object representing the current response. This is useful for retrieving very large resources without having to store the entire response body in memory at once for parsing.
All forms of this method may return the following:
For application/json: A decoded JSON object
For other response types: The unmodified response body
In exceptional conditions (such as when the service returns a 4xx or 5xx HTTP response), the client will die with the raw text response from the HTTP service, indicating the nature of the service-side failure to service the current call.
$client->call($method, $path, $body)
Perform a call to the service endpoint using the HTTP method $method, accessing the resource $path (relative to the absolute endpoint URI), passing an arbitrary value in $body.
$client->call($method, $headers, $path, $body)
Perform a call to the service endpoint using the HTTP method $method, accessing the resource $path (relative to the absolute endpoint URI), specifying the headers in $headers, passing an arbitrary value in $body.
The following shows how one may update image metadata using the PATCH method supported by version 2 of the Image API. @image_updates is an array of hash references of the structure defined by the PATCH RFC (6902) governing "JavaScript Object Notation (JSON) Patch"; i.e., operations consisting of add, replace, or delete.
@image_updates
add
replace
delete
my $headers = { 'Content-Type' => 'application/openstack-images-v2.1-json-patch' }; my $response = $glance->call({ 'method' => 'PATCH', 'headers' => $headers, 'path' => qq[/v2/images/$image->{id}], 'body' => \@image_updates );
$client->get($path, %opts)
Issue an HTTP GET request for resource $path. The keys and values specified in %opts will be URL encoded and appended to $path when forming the request. Response bodies are decoded as per $client->call().
$client->call()
$client->each($path, $opts, $callback)
$client->each($path, $callback)
Issue an HTTP GET request for the resource $path, while passing each decoded response object to $callback in a single argument. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.
$client->every($path, $attribute, $opts, $callback)
$client->every($path, $attribute, $callback)
Perform a series of HTTP GET request for the resource $path, decoding the result set and passing each value within each physical JSON response object's attribute named $attribute, to the callback $callback as a single argument. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.
$client->all($path, $attribute, $opts)
$client->all($path, $attribute)
Perform a series of HTTP GET requests for the resource $path, decoding the result set and returning a list of all items found within each response body's attribute named $attribute. $opts is taken to be a HASH reference containing zero or more key-value pairs to be URL encoded as parameters to each GET request made.
$client->put($path, $body)
Issue an HTTP PUT request to the resource at $path, in the form of a JSON encoding of the contents of $body.
$client->post($path, $body)
Issue an HTTP POST request to the resource at $path, in the form of a JSON encoding of the contents of $body.
$client->delete($path)
Issue an HTTP DELETE request of the resource at $path.
The OpenStack Keystone authentication and authorization interface
Written by Alexandra Hrefna Maheu <xan@cpanel.net>
Copyright (c) 2019 cPanel, L.L.C. Released under the terms of the MIT license. See LICENSE for further details.
To install OpenStack::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenStack::Client
CPAN shell
perl -MCPAN -e shell install OpenStack::Client
For more information on module installation, please visit the detailed CPAN module installation guide.