1PYTHON-OVH(1) Python-OVH PYTHON-OVH(1)
2
6 python-ovh - Python-OVH Documentation
7 Thin wrapper around OVH's APIs. Handles all the hard work including
9 credential creation and requests signing.
10 import ovh
12 # Instantiate. Visit https://api.ovh.com/createToken/index.cgi?GET=/me
14 # to get your credentials
15 client = ovh.Client(
16 endpoint='ovh-eu',
17 application_key='<application key>',
18 application_secret='<application secret>',
19 consumer_key='<consumer key>',
20 )
21 # Print nice welcome message
23 print("Welcome", client.get('/me')['firstname'])
24 The easiest way to get the latest stable release is to grab it from
26 pypi using pip.
27 pip install ovh
29 Alternatively, you may get latest development version directly from
31 Git.
32 pip install -e git+https://github.com/ovh/python-ovh.git#egg=ovh
34
36 Constructor
37 __init__
38 High level helpers
39 request_consumerkey
40 Helpers to generate a consumer key. See new_consumer_key_request below
41 for a full working example or ConsumerKeyRequest for detailed implemen‐
42 tation.
43 The basic idea of ConsumerKeyRequest is to generate appropriate autho‐
45 rization requests from human readable function calls. In short: use it!
46 get/post/put/delete
48 Shortcuts around Client.call(). This is the recommended way to use the
49 wrapper.
50 For example, requesting the list of all bills would look like:
52 bills = client.get('/me/bills')
54 In a similar fashion, enabling network burst on a specific server would
56 look like:
57 client.put('/dedicated/server/%s/burst' % server_name, status='active')
59 param str target
61 Rest Method as shown in API's console.
62 param boolean need_auth
64 When False, bypass the signature process. This is interesting
65 when calling authentication related method. Defaults to True
66 param dict kwargs
68 (Client.post() and Client.put() only) all extra keyword argu‐
69 ments are passed as data dict to call. This is a syntaxic sugar
70 to call API entrypoints using a regular method syntax.
71 Low level API
73 call
74 time_delta
76 Methods
77 __init__
78 get
79 Globals
81 Constructor
82 __init__
83 Helpers
84 Generate rules
85 Trigger request
88 1. Create an application
89 To interact with the APIs, the SDK needs to identify itself using an
90 application_key and an application_secret. To get them, you need to
91 register your application. Depending the API you plan yo use, visit:
92 • OVH Europe
94 • OVH North-America
96 Once created, you will obtain an application key (AK) and an applica‐
98 tion secret (AS).
99 2. Configure your application
101 The easiest and safest way to use your application's credentials is
102 create an ovh.conf configuration file in application's working direc‐
103 tory. Here is how it looks like:
104 [default]
106 ; general configuration: default endpoint
107 endpoint=ovh-eu
108 [ovh-eu]
110 ; configuration specific to 'ovh-eu' endpoint
111 application_key=my_app_key
112 application_secret=my_application_secret
113 ; uncomment following line when writing a script application
114 ; with a single consumer key.
115 ;consumer_key=my_consumer_key
116 Depending on the API you want to use, you may set the endpoint to:
118 • ovh-eu for OVH Europe API
120 • ovh-ca for OVH North-America API
122 See Configuration for more informations on available configuration
124 mechanisms.
125 NOTE:
127 When using a versioning system, make sure to add ovh.conf to ignored
128 files. It contains confidential/security-sensitive information!
129 3. Authorize your application to access a customer account
131 To allow your application to access a customer account using the API on
132 your behalf, you need a consumer key (CK).
133 try:
135 input = raw_input
136 except NameError:
137 pass
138 import ovh
140 # create a client using configuration
142 client = ovh.Client()
143 # Request RO, /me API access
145 access_rules = [
146 {'method': 'GET', 'path': '/me'},
147 ]
148 # Request token
150 validation = client.request_consumerkey(access_rules)
151 print("Please visit %s to authenticate" % validation['validationUrl'])
153 input("and press Enter to continue...")
154 # Print nice welcome message
156 print("Welcome", client.get('/me')['firstname'])
157 print("Btw, your 'consumerKey' is '%s'" % validation['consumerKey'])
158 Returned consumerKey should then be kept to avoid re-authenticating
160 your end-user on each use.
161 NOTE:
163 To request full and unlimited access to the API, you may use wild‐
164 cards:
165 access_rules = [
167 {'method': 'GET', 'path': '/*'},
168 {'method': 'POST', 'path': '/*'},
169 {'method': 'PUT', 'path': '/*'},
170 {'method': 'DELETE', 'path': '/*'}
171 ]
172
174 e-mail redirections may be freely configured on domains and DNS zones
175 hosted by OVH to an arbitrary destination e-mail using API call POST
176 /email/domain/{domain}/redirection.
177 For this call, the api specifies that the source address shall be given
179 under the from keyword. Which is a problem as this is also a reserved
180 Python keyword. In this case, simply prefix it with a '_', the wrapper
181 will automatically detect it as being a prefixed reserved keyword and
182 will substitute it. Such aliasing is only supported with reserved key‐
183 words.
184 import ovh
186 DOMAIN = "example.com"
188 SOURCE = "sales@example.com"
189 DESTINATION = "contact@example.com"
190 # create a client
192 client = ovh.Client()
193 # Create a new alias
195 client.post('/email/domain/%s/redirection' % DOMAIN,
196 _from=SOURCE,
197 to=DESTINATION
198 localCopy=False
199 )
200 print("Installed new mail redirection from %s to %s" % (SOURCE, DESTINATION))
201
203 Let's say you want to integrate OVH bills into your own billing system,
204 you could just script around the /me/bills endpoints and even get the
205 details of each bill lines using /me/bill/{billId}/details/{billDe‐
206 tailId}.
207 This example assumes an existing Configuration with valid applica‐
209 tion_key, application_secret and consumer_key.
210 import ovh
212 # create a client without a consumerKey
214 client = ovh.Client()
215 # Grab bill list
217 bills = client.get('/me/bill')
218 for bill in bills:
219 details = client.get('/me/bill/%s' % bill)
220 print("%12s (%s): %10s --> %s" % (
221 bill,
222 details['date'],
223 details['priceWithTax']['text'],
224 details['pdfUrl'],
225 ))
226
228 'Network burst' is a free service but is opt-in. What if you have, say,
229 10 servers in SBG-1 datacenter? You certainly don't want to activate it
230 manually for each servers. You could take advantage of a code like
231 this.
232 This example assumes an existing Configuration with valid applica‐
234 tion_key, application_secret and consumer_key.
235 import ovh
237 # create a client
239 client = ovh.Client()
240 # get list of all server names
242 servers = client.get('/dedicated/server/')
243 # find all servers in SBG-1 datacenter
245 for server in servers:
246 details = client.get('/dedicated/server/%s' % server)
247 if details['datacenter'] == 'sbg1':
248 # enable burst on server
249 client.put('/dedicated/server/%s/burst' % server, status='active')
250 print("Enabled burst for %s server located in SBG-1" % server)
251
253 Thanks to the application key / consumer key mechanism, it is possible
254 to finely track applications having access to your data and revoke this
255 access. This examples lists validated applications. It could easily be
256 adapted to manage revocation too.
257 This example assumes an existing Configuration with valid applica‐
259 tion_key, application_secret and consumer_key.
260 import ovh
262 from tabulate import tabulate
263 # create a client
265 client = ovh.Client()
266 credentials = client.get('/me/api/credential', status='validated')
268 # pretty print credentials status
270 table = []
271 for credential_id in credentials:
272 credential_method = '/me/api/credential/'+str(credential_id)
273 credential = client.get(credential_method)
274 application = client.get(credential_method+'/application')
275 table.append([
277 credential_id,
278 '[%s] %s' % (application['status'], application['name']),
279 application['description'],
280 credential['creation'],
281 credential['expiration'],
282 credential['lastUse'],
283 ])
284 print(tabulate(table, headers=['ID', 'App Name', 'Description',
285 'Token Creation', 'Token Expiration', 'Token Last Use']))
286 Before running this example, make sure you have the tabulate library
288 installed. It's a pretty cool library to pretty print tabular data in a
289 clean and easy way.
290 >>> pip install tabulate
292 The straightforward way to use OVH's API keys is to embed them directly
294 in the application code. While this is very convenient, it lacks of el‐
295 egance and flexibility.
296 Alternatively it is suggested to use configuration files or environment
298 variables so that the same code may run seamlessly in multiple environ‐
299 ments. Production and development for instance.
300 This wrapper will first look for direct instantiation parameters then
302 OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET and OVH_CON‐
303 SUMER_KEY environment variables. If either of these parameter is not
304 provided, it will look for a configuration file of the form:
305 [default]
307 ; general configuration: default endpoint
308 endpoint=ovh-eu
309 [ovh-eu]
311 ; configuration specific to 'ovh-eu' endpoint
312 application_key=my_app_key
313 application_secret=my_application_secret
314 consumer_key=my_consumer_key
315 The client will successively attempt to locate this configuration file
317 in
318 1. Current working directory: ./ovh.conf
320 2. Current user's home directory ~/.ovh.conf
322 3. System wide configuration /etc/ovh.conf
324 This lookup mechanism makes it easy to overload credentials for a spe‐
326 cific project or user.
327 You can call all the methods of the API with the necessary arguments.
329 If an API needs an argument colliding with a Python reserved keyword,
331 it can be prefixed with an underscore. For example, from argument of
332 POST /email/domain/{domain}/redirection may be replaced by _from.
333 With characters invalid in python argument name like a dot, you can:
335 import ovh
337 params = {}
339 params['date.from'] = '2014-01-01'
340 params['date.to'] = '2015-01-01'
341 # create a client
343 client = ovh.Client()
344 # pass parameters using **
346 client.post('/me/bills', **params)
347
349 If the user has not authenticated yet (ie, there is no valid Consumer
350 Key), you may force python-ovh to issue the call by passing
351 _need_auth=True to the high level get(), post(), put() and delete()
352 helpers or need_auth=True to the low level method Client.call() and
353 Client.raw_call().
354 This is needed when calling POST /auth/credential and GET /auth/time
356 which are used internally for authentication and can optionally be done
357 for most of the /order calls.
358
360 The high level get(), post(), put() and delete() helpers as well as the
361 lower level call() will returned a parsed json response or raise in
362 case of error.
363 In some rare scenario, advanced setups, you may need to perform cus‐
365 tomer processing on the raw request response. It may be accessed via
366 raw_call(). This is the lowest level call in python-ovh. See the
367 source for more information.
368 This wrapper uses standard Python tools, so you should feel at home
370 with it. Here is a quick outline of what it may look like. A good
371 practice is to run this from a virtualenv.
372
374 git clone https://github.com/ovh/python-ovh.git
375 cd python-ovh
376 python setup.py develop
377 You've developed a new cool feature ? Fixed an annoying bug ? We'd be
379 happy to hear from you !
380
382 Simply run nosetests. It will automatically load its configuration from
383 setup.cfg and output full coverage status. Since we all love quality,
384 please note that we do not accept contributions with test coverage un‐
385 der 100%.
386 pip install -e .[dev]
388 nosetests # 100% coverage is a hard minimum
389
391 Documentation is managed using the excellent Sphinx system. For exam‐
392 ple, to build HTML documentation:
393 cd python-ovh/docs
395 make html
396
398 • Documentation: https://eu.api.ovh.com/
399 • Community support: api-subscribe@ml.ovh.net
401 • Console: https://eu.api.ovh.com/console
403 • Create application credentials: https://eu.api.ovh.com/createApp/
405
407 • Documentation: https://ca.api.ovh.com/
408 • Community support: api-subscribe@ml.ovh.net
410 • Console: https://ca.api.ovh.com/console
412 • Create application credentials: https://ca.api.ovh.com/createApp/
414 • Contribute: https://github.com/ovh/python-ovh
416 • Report bugs: https://github.com/ovh/python-ovh/issues
418 • Download: http://pypi.python.org/pypi/ovh
420
422 Jean-Tiare Le Bigot
423
425 2013-2023, OVH SAS
4260.3 Jul 21, 2023 PYTHON-OVH(1)