|
| 1 | +Python-OVH: lightweight wrapper around OVH's APIs |
| 2 | +================================================= |
| 3 | + |
| 4 | +Thin wrapper around OVH's APIs. Handles all the hard work including credential |
| 5 | +creation and requests signing. |
| 6 | + |
| 7 | +A note on authentication |
| 8 | +------------------------ |
| 9 | + |
| 10 | +OVH's APIs relies on an OAuth based mechanism for authentication. OAuth is a |
| 11 | +standard protocol allowing to securely authenticate both an application and a |
| 12 | +user within an application. It also supports specific access restrictions. This |
| 13 | +is accomplished using a set of 3 Keys: |
| 14 | + |
| 15 | +- ``application_key``: Uniquely identifies an application. It can be seen as an |
| 16 | + application "login" and is attached to an account. This key may safely be |
| 17 | + shared. |
| 18 | +- ``application_secret``: Authenticates application identified by |
| 19 | + ``application_key``. It can be seen as an application "password" and should be |
| 20 | + protected as such ! |
| 21 | +- ``consumer_key``: Each application's user has it's own ``consumer_key`` |
| 22 | + specific to the this application. A ``consumer_key`` may only be valid for a |
| 23 | + subset of the API and a restricted amount of time. |
| 24 | + |
| 25 | +``application_key`` and ``application_secret`` are defined once for each |
| 26 | +application (see "Supported APIs" bellow) and ``consumer_key`` are granted once |
| 27 | +for each application's and-user. |
| 28 | + |
| 29 | + |
| 30 | +Installation |
| 31 | +============ |
| 32 | + |
| 33 | +The easiest way to get the latest stable release is to grab it from `pypi |
| 34 | +<https://pypi.python.org/pypi/ovh>`_ using ``pip``. |
| 35 | + |
| 36 | +.. code:: bash |
| 37 | +
|
| 38 | + pip install ovh |
| 39 | +
|
| 40 | +Alternatively, you may get latest development version directly from Git. |
| 41 | + |
| 42 | +.. code:: bash |
| 43 | +
|
| 44 | + pip install -e git+https://github.com/ovh/python-ovh.git#egg=ovh |
| 45 | +
|
| 46 | +
|
| 47 | +Hacking |
| 48 | +======= |
| 49 | + |
| 50 | +This wrapper uses standard Python tools, so you should feel familiar with it. |
| 51 | +Here is a quick outline of what it may look like. A good practice is to run |
| 52 | +this from a ``virtualenv``. |
| 53 | + |
| 54 | +.. code:: bash |
| 55 | +
|
| 56 | + git clone https://github.com/ovh/python-ovh.git |
| 57 | + cd python-ovh |
| 58 | + python setup.py develop |
| 59 | + pip install -r requirements-dev.txt |
| 60 | + nostests # 100% coverage is a hard minimum |
| 61 | +
|
| 62 | +
|
| 63 | +You've developed a new cool feature ? Fixed an annoying bug ? We'd be happy |
| 64 | +to here from you ! |
| 65 | + |
| 66 | +Building documentation |
| 67 | +====================== |
| 68 | + |
| 69 | +Documentation is managed using the excelent ``Sphinx`` system. For example, to |
| 70 | +build HTML documentation: |
| 71 | + |
| 72 | +.. code:: bash |
| 73 | +
|
| 74 | + cd python-ovh/docs |
| 75 | + make html |
| 76 | +
|
| 77 | +Example Usage |
| 78 | +============= |
| 79 | + |
| 80 | +Login as a user |
| 81 | +--------------- |
| 82 | + |
| 83 | +To communicate with APIs, the SDK uses a token on each request to identify the |
| 84 | +user. This token is called ``consumer_key``. Getting a ``consumer_key`` is done |
| 85 | +in 3 steps: |
| 86 | + |
| 87 | +1. application requests a new consumer key and specifies requested access permissions. |
| 88 | +2. application redirects user to a specific validation URL. |
| 89 | +3. end-user authenticates himself using his OVH credentials to validate it. |
| 90 | + |
| 91 | +Example: |
| 92 | + |
| 93 | +.. code:: python |
| 94 | +
|
| 95 | + # -*- encoding: utf-8 -*- |
| 96 | +
|
| 97 | + import ovh |
| 98 | +
|
| 99 | + # visit https://api.ovh.com/createApp/ to create your application's credentials |
| 100 | + APPLICATION_KEY = '<application key>' |
| 101 | + APPLICATION_SECRET = '<application secret>' |
| 102 | +
|
| 103 | + # create a client without a consumerKey |
| 104 | + client = ovh.Client( |
| 105 | + endpoint='ovh-eu', |
| 106 | + application_key=APPLICATION_KEY, |
| 107 | + application_secret=APPLICATION_SECRET, |
| 108 | + ) |
| 109 | +
|
| 110 | + # Request RO, /me API access |
| 111 | + access_rules = [ |
| 112 | + {'method': 'GET', 'path': '/me'}, |
| 113 | + ] |
| 114 | +
|
| 115 | + # Request token |
| 116 | + validation = client.request_consumerkey(access_rules) |
| 117 | +
|
| 118 | + print "Please visit %s to authenticate" % validation['validationUrl'] |
| 119 | + raw_input("and press Enter to continue...") |
| 120 | +
|
| 121 | + # Print nice welcome message |
| 122 | + print "Welcome", client.get('/me')['firstname'] |
| 123 | + print "Btw, your 'consumerKey' is '%s'" % validation['consumerKey'] |
| 124 | +
|
| 125 | +
|
| 126 | +Returned ``consumerKey`` should then be kept to avoid re-authenticating your |
| 127 | +end-user on each use. |
| 128 | + |
| 129 | +Note: to request full and unlimited access to the API, you may use wildcards: |
| 130 | + |
| 131 | +.. code:: python |
| 132 | +
|
| 133 | + access_rules = [ |
| 134 | + {'method': 'GET', 'path': '/*'}, |
| 135 | + {'method': 'POST', 'path': '/*'}, |
| 136 | + {'method': 'PUT', 'path': '/*'}, |
| 137 | + {'method': 'DELETE', 'path': '/*'} |
| 138 | + ] |
| 139 | +
|
| 140 | +
|
| 141 | +Grab bill list |
| 142 | +-------------- |
| 143 | + |
| 144 | +.. code:: python |
| 145 | +
|
| 146 | + # -*- encoding: utf-8 -*- |
| 147 | +
|
| 148 | + import ovh |
| 149 | +
|
| 150 | + APPLICATION_KEY = '<application key>' |
| 151 | + APPLICATION_SECRET = '<application secret>' |
| 152 | +
|
| 153 | + # create a client without a consumerKey |
| 154 | + client = ovh.Client( |
| 155 | + endpoint='ovh-eu', |
| 156 | + application_key=APPLICATION_KEY, |
| 157 | + application_secret=APPLICATION_SECRET, |
| 158 | + ) |
| 159 | +
|
| 160 | + # Request RO, /me/bill API access |
| 161 | + access_rules = [ |
| 162 | + {'method': 'GET', 'path': '/me/bill'}, |
| 163 | + {'method': 'GET', 'path': '/me/bill/*'}, |
| 164 | + ] |
| 165 | +
|
| 166 | + # Request token |
| 167 | + validation = client.request_consumerkey(access_rules) |
| 168 | +
|
| 169 | + print "Please visit", validation['validationUrl'], "to authenticate" |
| 170 | + raw_input("and press Enter to continue...") |
| 171 | +
|
| 172 | + # Grab bill list |
| 173 | + bills = client.get('/me/bill') |
| 174 | + for bill in bills: |
| 175 | + details = client.get('/me/bill/%s' % bill) |
| 176 | + print "%12s (%s): %10s --> %s" % ( |
| 177 | + bill, |
| 178 | + details['date'], |
| 179 | + details['priceWithTax']['text'], |
| 180 | + details['pdfUrl'], |
| 181 | + ) |
| 182 | +
|
| 183 | +Enable network burst in SBG1 |
| 184 | +---------------------------- |
| 185 | + |
| 186 | +.. code:: python |
| 187 | +
|
| 188 | + # -*- encoding: utf-8 -*- |
| 189 | +
|
| 190 | + import ovh |
| 191 | +
|
| 192 | + # visit https://api.ovh.com/createApp/ to create your application's credentials |
| 193 | + APPLICATION_KEY = '<application key>' |
| 194 | + APPLICATION_SECRET = '<application secret>' |
| 195 | + CONSUMER_KEY = '<consumer key (see above)>' |
| 196 | +
|
| 197 | + # create a client |
| 198 | + client = ovh.Client( |
| 199 | + endpoint='ovh-eu', |
| 200 | + application_key=APPLICATION_KEY, |
| 201 | + application_secret=APPLICATION_SECRET, |
| 202 | + consumer_key=CONSUMER_KEY, |
| 203 | + ) |
| 204 | +
|
| 205 | + # get list of all server names |
| 206 | + servers = client.get('/dedicated/server/') |
| 207 | +
|
| 208 | + # find all servers in SBG-1 datacenter |
| 209 | + for server in servers: |
| 210 | + details = client.get('/dedicated/server/%s' % server) |
| 211 | + if details['datacenter'] == 'sbg1': |
| 212 | + # enable burst on server |
| 213 | + client.put('/dedicated/server/%s/burst' % server, status='active') |
| 214 | + print "Enabled burst for %s server located in SBG-1" % server |
| 215 | +
|
| 216 | +List Runabove's instance |
| 217 | +------------------------ |
| 218 | + |
| 219 | +.. code:: python |
| 220 | +
|
| 221 | + # -*- encoding: utf-8 -*- |
| 222 | +
|
| 223 | + import ovh |
| 224 | + from tabulate import tabulate |
| 225 | +
|
| 226 | + # visit https://api.runabove.com/createApp/ to create your application's credentials |
| 227 | + APPLICATION_KEY = '<application key>' |
| 228 | + APPLICATION_SECRET = '<application secret>' |
| 229 | + CONSUMER_KEY = '<consumer key (see above)>' |
| 230 | +
|
| 231 | + # create a client |
| 232 | + client = ovh.Client( |
| 233 | + endpoint='runabove-ca', |
| 234 | + application_key=APPLICATION_KEY, |
| 235 | + application_secret=APPLICATION_SECRET, |
| 236 | + consumer_key=CONSUMER_KEY, |
| 237 | + ) |
| 238 | +
|
| 239 | + # get list of all instances |
| 240 | + instances = client.get('/instance') |
| 241 | +
|
| 242 | + # pretty print instances status |
| 243 | + table = [] |
| 244 | + for instance in instances: |
| 245 | + table.append([ |
| 246 | + instance['name'], |
| 247 | + instance['ip'], |
| 248 | + instance['region'], |
| 249 | + instance['status'], |
| 250 | + ]) |
| 251 | + print tabulate(table, headers=['Name', 'IP', 'Region', 'Status']) |
| 252 | +
|
| 253 | +Before running this example, make sure you have the |
| 254 | +`tabulate <https://pypi.python.org/pypi/tabulate>`_ library installed. It's a |
| 255 | +pretty cool library to pretty print tabular data. |
| 256 | + |
| 257 | +>>> pip install tabulate |
| 258 | + |
| 259 | +Supported APIs |
| 260 | +============== |
| 261 | + |
| 262 | +OVH |
| 263 | +--- |
| 264 | + |
| 265 | + - **documentation**: https://api.ovh.com/ |
| 266 | + - **community support**: api-subscribe@ml.ovh.net |
| 267 | + - **console**: https://api.ovh.com/console |
| 268 | + - **get application credentials**: https://api.ovh.com/createApp/ |
| 269 | + |
| 270 | +Runabove |
| 271 | +-------- |
| 272 | + |
| 273 | + - **console**: https://api.runabove.com/console/ |
| 274 | + - **get application credentials**: https://api.runabove.com/createApp/ |
| 275 | + - **high level SDK**: https://github.com/runabove/python-runabove |
| 276 | + |
| 277 | +Related links |
| 278 | +============= |
| 279 | + |
| 280 | +- **contribute**: https://github.com/ovh/python-ovh |
| 281 | +- **Report bugs**: https://github.com/ovh/python-ovh/issues |
| 282 | +- **Download**: http://pypi.python.org/pypi/ovh |
0 commit comments