Skip to content

Latest commit

 

History

History
282 lines (215 loc) · 8.4 KB

README.md

File metadata and controls

282 lines (215 loc) · 8.4 KB
Raw

perl-ovh

Perl wrapper around OVHcloud's APIs. Handles all the hard work including credential creation and requests signing.

Synopsis

#!/usr/bin/env perl
use strict;
use warnings;

use OvhApi;

my $ApiOvh = OvhApi->new(
    timeout             => 10,
);

my $identity = $ApiOvh->get(path => "/me");
if (!$identity)
{
    printf("Failed to retrieve identity: %s\n", $identity);
    return 0;
}
$identity = $identity->content();

printf("Welcome %s\n", $identity->{'firstname'});

Installation

perl Makefile.PL
make
make test
make install

Register your app

OVHcloud's API, like most modern APIs, is designed to authenticate both an application and a user, without requiring the user to provide a password. Your application will be identified by its "application secret" and "application key" tokens.

Hence, to use the API, you must first register your application and then ask your user to authenticate on a specific URL. Once authenticated, you'll have a valid "consumer key" which will grant your application on specific APIs.

The user may choose the validity period of its authorization. The default period is 24h. He may also revoke an authorization at any time. Hence, your application should be prepared to receive 403 HTTP errors and prompt the user to re-authenticate.

This process is detailed in the following section. Alternatively, you may only need to build an application for a single user. In this case you may generate all credentials at once. See below.

Use the API on behalf of a user

Visit https://eu.api.ovh.com/createApp and create your app You'll get an application key and an application secret. To use the API you'll need a consumer key.

The consumer key has two types of restriction:

  • path: eg. only the GET method on /me
  • time: eg. expire in 1 day

Then, get a consumer key.

Use the API for a single user

Alternatively, you may generate all credentials at once, including the consumer key. You will typically want to do this when writing automation scripts for a single project.

If this case, you may want to directly go to https://eu.api.ovh.com/createToken/ to generate the 3 tokens at once.

Configuration

The straightforward way to use OVHcloud's API keys is to embed them directly in the application code. While this is very convenient, it lacks of elegance and flexibility. You might also need to add your scripts into some source control systems, and adding credentials into source control is not the best way to manage your credentials.

perl-ovh will look for a configuration file of the form:

[default]
; general configuration: default endpoint
endpoint=ovh-eu

[ovh-eu]
; configuration specific to 'ovh-eu' endpoint
application_key=my_app_key
application_secret=my_application_secret
consumer_key=my_consumer_key

Depending on the API you want to use, you may set the endpoint to:

  • ovh-eu for OVHcloud Europe API
  • ovh-us for OVHcloud US API
  • ovh-ca for OVHcloud Canada API
  • soyoustart-eu for So you Start Europe API
  • soyoustart-ca for So you Start Canada API
  • kimsufi-eu for Kimsufi Europe API
  • kimsufi-ca for Kimsufi Canada API

The client will successively attempt to locate this configuration file in

  1. Current working directory: ./ovh.conf
  2. Current user's home directory ~/.ovh.conf
  3. System wide configuration /etc/ovh.conf

This lookup mechanism makes it easy to overload credentials for a specific project or user.

Usage

#!/usr/bin/env perl
use strict;
use warnings;
use 5.010;

use OvhApi;

sub main
{
    my $ApiOvh = OvhApi->new(
        timeout             => 10,
    );

    if (not $ApiOvh->{consumerKey})
    {
        my $validation = $ApiOvh->requestCredentials(
            accessRules => [
                {
                    method  => "ALL",
                    path    => "/hosting/web*",
                },
                {
                    method  => "GET",
                    path    => "/me",
                },
            ]
        );
        if (not $validation)
        {
            printf("Failed to request new credentials: %s\n", $validation);
            return 0;
        }

        $validation = $validation->content();
        printf("Please visit %s to authenticate,\nand press Enter to continue...", $validation->{'validationUrl'});
        <STDIN> // die "Abort.\n";
        $ApiOvh->{consumerKey} = $validation->{'consumerKey'};
        printf("Your 'consumerKey' is '%s', you can save it to use it next time you want to use this script!\n", $ApiOvh->{'consumerKey'});
    }

    my $identity = $ApiOvh->get(path => "/me");
    if (!$identity)
    {
        printf("Failed to retrieve identity: %s\n", $identity);
        return 0;
    }
    $identity = $identity->content();

    printf("Welcome %s\n", $identity->{'firstname'});

    print("Listing all web hosting products...\n");
    my $hostingWebList = $ApiOvh->get(
        path => '/hosting/web',
    );
    if (not $hostingWebList)
    {
        printf("Error: %s\n", $hostingWebList);
        return 0;
    }

    $hostingWebList = $hostingWebList->content;
    if (not @$hostingWebList)
    {
        print("You don't have any web hosting on your account!\n");
        return 0;
    }

    print("Available web hosting:\n");
    foreach my $hostingWeb (@$hostingWebList)
    {
        printf("- %s\n", $hostingWeb);
    }

    printf("\nRenaming %s\nEnter a new name: ", $hostingWebList->[0]);
    my $newName = <STDIN> // die "Abort.\n";
    chomp $newName;

    my $renamingOperation = $ApiOvh->put(
        path => "/hosting/web/".$hostingWebList->[0],
        body => {
            displayName => $newName,
        },
    );
    if (not $renamingOperation)
    {
        printf("Error while renaming: %s\n", $renamingOperation);
        return 0;
    }
    print("Renamed successfully!\n");
}

main();

Hacking

This wrapper uses standard Perl tools, so you should feel at home with it.

You've developed a new cool feature? Fixed an annoying bug? We'd be happy to hear from you! See CONTRIBUTING.md for more information.

Supported APIs

OVHcloud Europe

OVHcloud US

OVHcloud Canada

So you Start Europe

So you Start Canada

Kimsufi Europe

Kimsufi Canada

License

3-Clause BSD