root / docs / developers / clients-api.rst @ d88ba587
History | View | Annotate | Download (4 kB)
1 | 9e4508df | Stavros Sachtouris | Creating applications with kamaki API |
---|---|---|---|
2 | 9e4508df | Stavros Sachtouris | ===================================== |
3 | 9e4508df | Stavros Sachtouris | |
4 | 9e4508df | Stavros Sachtouris | |
5 | 9e4508df | Stavros Sachtouris | 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 | 9e4508df | Stavros Sachtouris | |
7 | 9e4508df | Stavros Sachtouris | A good example of an application build on kamaki.clients is kamaki.cli, the command line interface of kamaki. |
8 | 9e4508df | Stavros Sachtouris | |
9 | d88ba587 | Stavros Sachtouris | 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*, *image* for *plankton*). |
10 | 9e4508df | Stavros Sachtouris | |
11 | 9e4508df | Stavros Sachtouris | Setup a client instance |
12 | 9e4508df | Stavros Sachtouris | ----------------------- |
13 | 9e4508df | Stavros Sachtouris | |
14 | 9e4508df | Stavros Sachtouris | External applications may instantiate one or more kamaki clients. |
15 | 9e4508df | Stavros Sachtouris | |
16 | 9e4508df | Stavros Sachtouris | .. code-block:: python |
17 | 9e4508df | Stavros Sachtouris | :emphasize-lines: 1 |
18 | 9e4508df | Stavros Sachtouris | |
19 | 9e4508df | Stavros Sachtouris | Example 1.1: Instantiate a Cyclades client |
20 | 9e4508df | Stavros Sachtouris | |
21 | 9e4508df | Stavros Sachtouris | |
22 | 9e4508df | Stavros Sachtouris | from kamaki.clients.cyclades import CycladesClient |
23 | 9e4508df | Stavros Sachtouris | from kamaki.clients.pithos import PithosClient |
24 | 9e4508df | Stavros Sachtouris | |
25 | 9e4508df | Stavros Sachtouris | my_cyclades_client = CycladesClient(base_url, token) |
26 | 9e4508df | Stavros Sachtouris | my_pithos_client = PithosClient(base_url, token, account, container) |
27 | 9e4508df | Stavros Sachtouris | |
28 | 9e4508df | Stavros Sachtouris | .. 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 | 9e4508df | Stavros Sachtouris | |
30 | 9e4508df | Stavros Sachtouris | Use client methods |
31 | 9e4508df | Stavros Sachtouris | ------------------ |
32 | 9e4508df | Stavros Sachtouris | |
33 | 9e4508df | Stavros Sachtouris | 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. |
34 | 9e4508df | Stavros Sachtouris | |
35 | 9e4508df | Stavros Sachtouris | 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. |
36 | 9e4508df | Stavros Sachtouris | |
37 | 9e4508df | Stavros Sachtouris | |
38 | 9e4508df | Stavros Sachtouris | .. code-block:: python |
39 | 9e4508df | Stavros Sachtouris | :emphasize-lines: 1,2 |
40 | 9e4508df | Stavros Sachtouris | |
41 | 9e4508df | Stavros Sachtouris | Example 1.2: Print server name and OS for server with server_id |
42 | 9e4508df | Stavros Sachtouris | Print objects in container mycont |
43 | 9e4508df | Stavros Sachtouris | |
44 | 9e4508df | Stavros Sachtouris | |
45 | 9e4508df | Stavros Sachtouris | srv = my_cyclades_client.get_server_info(server_id) |
46 | 9e4508df | Stavros Sachtouris | print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
47 | 9e4508df | Stavros Sachtouris | |
48 | 9e4508df | Stavros Sachtouris | obj_list = my_pithos_client.list_objects(mycont) |
49 | 9e4508df | Stavros Sachtouris | for obj in obj_list: |
50 | 9e4508df | Stavros Sachtouris | print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
51 | 9e4508df | Stavros Sachtouris | |
52 | 9e4508df | Stavros Sachtouris | .. code-block:: console |
53 | 9e4508df | Stavros Sachtouris | :emphasize-lines: 1 |
54 | 9e4508df | Stavros Sachtouris | |
55 | 9e4508df | Stavros Sachtouris | Run of examples 1.1 + 1.2 |
56 | 9e4508df | Stavros Sachtouris | |
57 | 9e4508df | Stavros Sachtouris | |
58 | 9e4508df | Stavros Sachtouris | $ python test_script.py |
59 | 9e4508df | Stavros Sachtouris | Server Name: A Debian Server (with OS Debian Base) |
60 | 9e4508df | Stavros Sachtouris | lala.txt of 34 bytes |
61 | 9e4508df | Stavros Sachtouris | test.txt of 1232 bytes |
62 | 9e4508df | Stavros Sachtouris | testDir/ of 0 bytes |
63 | 9e4508df | Stavros Sachtouris | $ |
64 | 9e4508df | Stavros Sachtouris | |
65 | 9e4508df | Stavros Sachtouris | Error handling |
66 | 9e4508df | Stavros Sachtouris | -------------- |
67 | 9e4508df | Stavros Sachtouris | |
68 | 9e4508df | Stavros Sachtouris | 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.). |
69 | 9e4508df | Stavros Sachtouris | |
70 | 9e4508df | Stavros Sachtouris | A ClientError contains:: |
71 | 9e4508df | Stavros Sachtouris | |
72 | 9e4508df | Stavros Sachtouris | message The error message. |
73 | 9e4508df | Stavros Sachtouris | status An optional error code, e.g. after a server error. |
74 | 9e4508df | Stavros Sachtouris | details Optional list of messages with error details. |
75 | 9e4508df | Stavros Sachtouris | |
76 | 9e4508df | Stavros Sachtouris | The following example concatenates examples 1.1 and 1.2 plus error handling |
77 | 9e4508df | Stavros Sachtouris | |
78 | 9e4508df | Stavros Sachtouris | .. code-block:: python |
79 | 9e4508df | Stavros Sachtouris | |
80 | 9e4508df | Stavros Sachtouris | Example 1.3: Error handling |
81 | 9e4508df | Stavros Sachtouris | |
82 | 9e4508df | Stavros Sachtouris | |
83 | 9e4508df | Stavros Sachtouris | from kamaki.clients.cyclades import CycladesClient |
84 | 9e4508df | Stavros Sachtouris | from kamaki.clients.pithos import PithosClient |
85 | 9e4508df | Stavros Sachtouris | |
86 | 9e4508df | Stavros Sachtouris | try: |
87 | 9e4508df | Stavros Sachtouris | my_cyclades_client = CycladesClient(base_url, token) |
88 | 9e4508df | Stavros Sachtouris | except ClientError: |
89 | 9e4508df | Stavros Sachtouris | print('Failed to initialize Cyclades client') |
90 | 9e4508df | Stavros Sachtouris | |
91 | 9e4508df | Stavros Sachtouris | try: |
92 | 9e4508df | Stavros Sachtouris | my_pithos_client = PithosClient(base_url, token, account, container) |
93 | 9e4508df | Stavros Sachtouris | except ClientError: |
94 | 9e4508df | Stavros Sachtouris | print('Failed to initialize Pithos+ client') |
95 | 9e4508df | Stavros Sachtouris | |
96 | 9e4508df | Stavros Sachtouris | try: |
97 | 9e4508df | Stavros Sachtouris | srv = my_cyclades_client.get_server_info(server_id) |
98 | 9e4508df | Stavros Sachtouris | print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
99 | 9e4508df | Stavros Sachtouris | |
100 | 9e4508df | Stavros Sachtouris | obj_list = my_pithos_client.list_objects(mycont) |
101 | 9e4508df | Stavros Sachtouris | for obj in obj_list: |
102 | 9e4508df | Stavros Sachtouris | print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
103 | 9e4508df | Stavros Sachtouris | except ClientError as e: |
104 | 9e4508df | Stavros Sachtouris | print('Error: %s' % e) |
105 | 9e4508df | Stavros Sachtouris | if e.status: |
106 | 9e4508df | Stavros Sachtouris | print('- error code: %s' % e.status) |
107 | 9e4508df | Stavros Sachtouris | if e.details: |
108 | 9e4508df | Stavros Sachtouris | for detail in e.details: |
109 | 9e4508df | Stavros Sachtouris | print('- %s' % detail) |