root / docs / developers / clients-api.rst @ 0ea31480
History | View | Annotate | Download (4.2 kB)
1 |
Creating applications with kamaki API |
---|---|
2 |
===================================== |
3 |
|
4 |
|
5 |
Kamaki features a clients API for building third-party client applications that communicate with OpenStack and / or Synnefo cloud services. The package is called kamaki.clients and contains a number of |
6 |
|
7 |
A good example of an application build on kamaki.clients is kamaki.cli, the command line interface of kamaki. |
8 |
|
9 |
Since synnefo services are build as OpenStack extensions, an inheritance approach has been chosen for implementing clients for both. In specific, the *compute*, *storage* and *image* modules are clients of the OS compute, OS storage, respectively. On the contrary, all the other modules are Synnefo extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api* extent *storage*) or novel synnefo services (e.g. *astakos* for IM, *image* for *plankton*). |
10 |
|
11 |
Setup a client instance |
12 |
----------------------- |
13 |
|
14 |
External applications may instantiate one or more kamaki clients. |
15 |
|
16 |
.. code-block:: python |
17 |
:emphasize-lines: 1 |
18 |
|
19 |
Example 1.1: Instantiate Cyclades and Pithos client |
20 |
|
21 |
|
22 |
from kamaki.clients.cyclades import CycladesClient |
23 |
from kamaki.clients.pithos import PithosClient |
24 |
|
25 |
my_cyclades_client = CycladesClient(base_url, token) |
26 |
my_pithos_client = PithosClient(base_url, token, account, container) |
27 |
|
28 |
.. note:: *cyclades* and *pithos* clients inherit all methods of *compute* and *storage* clients respectively. Separate compute or storage objects should be used only when implementing applications for strict OS Compute or OS Storage services. |
29 |
|
30 |
.. note:: *account* variable is usually acquired by the following user call |
31 |
|
32 |
.. code-block:: python |
33 |
|
34 |
from kamaki.clients.astakos import AstakosClient |
35 |
astakos = AstakosClient(astakos_base_url, token) |
36 |
account = astakos.term('uuid') |
37 |
|
38 |
Use client methods |
39 |
------------------ |
40 |
|
41 |
Client methods can now be called. Developers are advised to consult :ref:`the-client-api-ref` for details on the available methods and how to use them. |
42 |
|
43 |
In the following example, the *cyclades* and *pithos* clients of example 1.1 are used to extract some information, that is then printed to the standard output. |
44 |
|
45 |
|
46 |
.. code-block:: python |
47 |
:emphasize-lines: 1,2 |
48 |
|
49 |
Example 1.2: Print server name and OS for server with server_id |
50 |
Print objects in container mycont |
51 |
|
52 |
|
53 |
srv = my_cyclades_client.get_server_info(server_id) |
54 |
print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
55 |
|
56 |
obj_list = my_pithos_client.list_objects(mycont) |
57 |
for obj in obj_list: |
58 |
print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
59 |
|
60 |
.. code-block:: console |
61 |
:emphasize-lines: 1 |
62 |
|
63 |
Run of examples 1.1 + 1.2 |
64 |
|
65 |
|
66 |
$ python test_script.py |
67 |
Server Name: A Debian Server (with OS Debian Base) |
68 |
lala.txt of 34 bytes |
69 |
test.txt of 1232 bytes |
70 |
testDir/ of 0 bytes |
71 |
$ |
72 |
|
73 |
Error handling |
74 |
-------------- |
75 |
|
76 |
The kamaki.clients standard error is ClientError. A ClientError is raised for any kind of kamaki.clients errors (errors reported by servers, type errors in arguments, etc.). |
77 |
|
78 |
A ClientError contains:: |
79 |
|
80 |
message The error message. |
81 |
status An optional error code, e.g. after a server error. |
82 |
details Optional list of messages with error details. |
83 |
|
84 |
The following example concatenates examples 1.1 and 1.2 plus error handling |
85 |
|
86 |
.. code-block:: python |
87 |
|
88 |
Example 1.3: Error handling |
89 |
|
90 |
|
91 |
from kamaki.clients.cyclades import CycladesClient |
92 |
from kamaki.clients.pithos import PithosClient |
93 |
|
94 |
try: |
95 |
my_cyclades_client = CycladesClient(base_url, token) |
96 |
except ClientError: |
97 |
print('Failed to initialize Cyclades client') |
98 |
|
99 |
try: |
100 |
my_pithos_client = PithosClient(base_url, token, account, container) |
101 |
except ClientError: |
102 |
print('Failed to initialize Pithos+ client') |
103 |
|
104 |
try: |
105 |
srv = my_cyclades_client.get_server_info(server_id) |
106 |
print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
107 |
|
108 |
obj_list = my_pithos_client.list_objects(mycont) |
109 |
for obj in obj_list: |
110 |
print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
111 |
except ClientError as e: |
112 |
print('Error: %s' % e) |
113 |
if e.status: |
114 |
print('- error code: %s' % e.status) |
115 |
if e.details: |
116 |
for detail in e.details: |
117 |
print('- %s' % detail) |