NAME

DigitalOcean - An OO interface to the Digital Ocean API (v2).

VERSION

version 0.17

METHODS

ratelimit_limit

Returns the number of requests that can be made per hour. See here for more details.

ratelimit_remaining

Returns the number of requests that remain before you hit your request limit. See here for more details.

ratelimit_reset

This returns the time when the oldest request will expire. The value is given in Unix epoch time. See here for more details.

die_pretty

This method controls how DigitalOcean will die when it receives an error from the Digital Ocean API. If it is set to 1, then DigitalOcean will die with a string representation of a DigitalOcean::Error object. This is useful for debugging and seeing immediately what caused the error. If it is set to undef, then DigitalOcean will die with a DigitalOcean::Error object instead of its string representation. This is useful if you want to handle the returned error programmatically. The default is 1.

$do->die_pretty(undef); #when a Digital Ocean API error is received, will die with DigitalOcean::Error object

$do->die_pretty(1); #when a Digital Ocean API error is received, will die with the string representation of the DigitalOcean::Error object

my $droplets;
try { 
    $droplets = $do->droplets;
}
catch { 
    my $do_error = $_;

    if($do_error->status_code >= 400 and $do_error->status_code < 500) { 
        print "probably an issue with the request...\n";
    }
    elsif($do_error->status_code >= 500) {
        print "probably an issue with the Digital Ocean API...\n"; 
    }
    if($do_error->status_code >= 200 and $do_error->status_code < 300) { 
        print "this should not have been an error...\n";
    }
    else { 
        print "not sure what the error means...\n";
    }

    print "id: " . $do_error->id . "\n";
    print "message: " . $do_error->message . "\n";
    print "status_code: " . $do_error->status_code . "\n";
    print "status_message: " . $do_error->status_message . "\n";
    print "status_line: " . $do_error->status_line . "\n";
}

last_response

This method returns the last DigitalOcean::Response from the most recent API request. This contains useful information about the request, such as the DigitalOcean::Response's status_code or the DigitalOcean::Meta object. It returns undef if no API requests have been made yet.

my $last_response = $do->last_response;

my $status_code = $do->status_code;
print "Status code from last response $status_code\n";

my $status_message = $do->status_message;
print "Status message from last response $status_message\n";

my $total = $do->meta->total;
print "Total objects returned in last response $total\n";

per_page

This method can force pagination to a certain value instead of the default value of 25 when requesting collections.

#now 2 items will be returned per page for collections
$do->per_page(2);

The default is undef, which just means that the Digital Ocean API's default will be used.

get_user_information

Returns a DigitalOcean::Account object.

my $account = $do->get_user_information;

print "Droplet limit: " . $account->droplet_limit . "\n";
print "Email: " . $account->email . "\n";
print "uuid: " . $account->uuid . "\n";
print "Email Verified: " . $account->email_verified . "\n";

actions

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Action objects of the actions collection.

my $actions_collection = $do->actions;
my $obj;

while($obj = $actions_collection->next) { 
    print $obj->id . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $actions_collection = $do->actions(2);
my $obj;

while($obj = $actions_collection->next) { 
    print $obj->id . "\n";
}

action

This will retrieve an action by id and return a DigitalOcean::Action object.

my $action = $do->action(56789);

domains

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Domain objects of the domains collection.

my $domains_collection = $do->domains;
my $obj;

while($obj = $domains_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $domains_collection = $do->domains(2);
my $obj;

while($obj = $domains_collection->next) { 
    print $obj->name . "\n";
}

create_domain

This will create a new domain and return a DigitalOcean::Domain object. The parameters are:

name Required, String, The domain name to add to the DigitalOcean DNS management interface. The name must be unique in DigitalOcean's DNS system. The request will fail if the name has already been taken.
ip_address Required, String, This attribute contains the IP address you want the domain to point to.

my $domain = $do->create_domain(
    name => 'example.com',
    ip_address => '127.0.0.1',
);

Keep in mind that, upon creation, the zone_file field will have a value of null until a zone file is generated and propagated through an automatic process on the DigitalOcean servers.

domain

This will retrieve a domain by name and return a DigitalOcean::Domain object.

my $domain = $do->domain('example.com');

create_droplet

This will create a new droplet and return a DigitalOcean::Droplet object. The parameters are:

name Required, String, The human-readable string you wish to use when displaying the Droplet name. The name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. The name set during creation will also determine the hostname for the Droplet in its internal configuration.
```
=item 
```
region Required, String, The unique slug identifier for the region that you wish to deploy in.
size Required, String, The unique slug identifier for the size that you wish to select for this Droplet.
image Required, number (if using an image ID), or String (if using a public image slug), The image ID of a public or private image, or the unique slug identifier for a public image. This image will be the base image for your Droplet.
ssh_keys Optional, Array Reference, An array reference containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation.
backups Optional, Boolean, A boolean indicating whether automated backups should be enabled for the Droplet. Automated backups can only be enabled when the Droplet is created.
ipv6 Optional, Boolean, A boolean indicating whether IPv6 is enabled on the Droplet.
private_networking Optional, Boolean, A boolean indicating whether private networking is enabled for the Droplet. Private networking is currently only available in certain regions.
user_data Optional, String, A string of the desired User Data for the Droplet. User Data is currently only available in regions with metadata listed in their features.

   my $new_droplet = $do->create_droplet(
       name => 'new_droplet',
       region => $region,
       size => $size,
       image => $image,
   );


   Even though this method does not return a L<DigitalOcean::Action>, it can still be used with L</wait_on_action> and L</wait_on_actions>.

droplet

This will retrieve a droplet by id and return a DigitalOcean::Droplet object.

my $droplet = $do->droplet(56789);

droplets

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Droplet objects of the droplets collection.

my $droplets_collection = $do->droplets;
my $obj;

while($obj = $droplets_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $droplets_collection = $do->droplets(2);
my $obj;

while($obj = $droplets_collection->next) { 
    print $obj->name . "\n";
}

droplet_upgrades

This method retrieves a list of droplets that are scheduled to be upgraded as DigitalOcean::Droplet::Upgrade objects and returns them as an array reference.

my $droplet_upgrades = $do->droplet_upgrades;

for my $upgrade (@$droplet_upgrades) { 
    print "ID: " . $upgrade->droplet_id . "\n";
    print "Date of migration: " . $upgrade->date_of_migration . "\n";
    print "url " . $upgrade->url . "\n";
    print "\n";
}

images

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Image objects of the images collection.

my $images_collection = $do->images;
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $images_collection = $do->images(2);
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

distribution_images

This method will retrieve only distribution images. It returns a DigitalOcean::Collection of DigitalOcean::Image objects.

my $images_collection = $do->distribution_images;
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $images_collection = $do->distribution_images(2);
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

application_images

This method will retrieve only application images. It returns a DigitalOcean::Collection of DigitalOcean::Image objects.

my $images_collection = $do->application_images;
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $images_collection = $do->application_images(2);
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

user_images

This method will retrieve only your private images. It returns a DigitalOcean::Collection of DigitalOcean::Image objects.

my $images_collection = $do->user_images;
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $images_collection = $do->user_images(2);
my $obj;

while($obj = $images_collection->next) { 
    print $obj->name . "\n";
}

image

This will retrieve an image by id or by slug and return a DigitalOcean::Image object.

my $image = $do->image(11836690);

#or

my $image = $do->image('ubuntu-14-04-x64');

ssh_keys

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::SSH::Key objects of the droplets collection.

my $keys_collection = $do->ssh_keys;
my $obj;

while($obj = $keys_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $keys_collection = $do->ssh_keys(2);
my $obj;

while($obj = $keys_collection->next) { 
    print $obj->name . "\n";
}

create_ssh_key

This will create a new ssh key and add it to your account and return a DigitalOcean::SSH::Key object. The parameters are:

name Required, String, The name to give the new SSH key in your account.
public_key Required, String, A string containing the entire public key.

my $ssh_key = $do->create_ssh_key(
    name => 'new_ssh_key',
    public_key => $ssh_pub_key,
);

ssh_key

This will retrieve an ssh key by id or by fingerprint and return a DigitalOcean::SSH::Key object.

my $ssh_key = $do->ssh_key(11836690);

#or

my $ssh_key = $do->ssh_key('7a:61:d4:1c:b3:b0:c6:0b:9e:e2:c9:ff:35:f0:a0:dd');

regions

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Region objects of the regions collection.

my $regions_collection = $do->regions;
my $obj;

while($obj = $regions_collection->next) { 
    print $obj->name . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $regions_collection = $do->regions(2);
my $obj;

while($obj = $regions_collection->next) { 
    print $obj->name . "\n";
}

sizes

This will return a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Size objects of the sizes collection.

my $sizes_collection = $do->sizes;
my $obj;

while($obj = $sizes_collection->next) { 
    print $obj->slug . "\n";
}

If you would like a different per_page value to be used for this collection instead of "per_page", it can be passed in as a parameter:

#set default for all collections to be 30
$do->per_page(30);

#set this collection to have 2 objects returned per page
my $sizes_collection = $do->sizes(2);
my $obj;

while($obj = $sizes_collection->next) { 
    print $obj->slug . "\n";
}

DOCUMENTATION NEEDS WORK

So I have updated the DigitalOcean module to be compatible with version 2. Unfortunately I have not had time to finish writing the documentation or tests yet. However, I have chosen to release the module anyway since as of November 1, 2015 API 1 will no longer work, which means that the older versions of this module will no longer work. I will try to update with documentation and tests as soon as I can. Until then, if something is unclear you can look at the code to help figure out how it works. You can also submit a pull request if you'd like to help with the documentation.

WAITING ON ACTIONS

wait_on_actions

For some calls in Digital Ocean's API, you need to wait for one call to finish before you can submit another request that depends on the first call. For instance, if you resize a droplet and then want to take a snapshot of the droplet, you must wait until the action of resizing the droplet is complete before you can take the snapshot of this droplet. If you set wait_on_actions to 1, then DigitalOcean will wait on every action until it is complete, so this way you do not have to worry about the synchronization of events or if you need to wait between two events. However, turning wait_on_actions on for every action can also cause your script to run much slower if you do not need to be waiting on every action.

You may wait on all events by passing in wait_on_actions when you create the DigitalOcean object:

my $do = DigitalOcean->new(oauth_token => $oauth_token, wait_on_actions => 1);

Or you can toggle it after you have created the DigitalOcean object:

$do->wait_on_actions(1);
$do->wait_on_actions(undef);

The default for wait_on_actions is that it is set to undef and does not wait on actions.

wait_on_action

A more efficient solution is to only wait on indiviudal actions that you have to wait on. You can pass in the wait_on_action flag to any subroutine that returns a L <DigitalOcean::Action> object (and also "create_droplet") and DigitalOcean will wait until that call is complete before returning.

   my $droplet = $do->create_droplet(
       name => 'new_droplet',
       size_id => $size_id,
       image_id => $image_id,
       region_id => $region_id,
       wait_on_event => 1,
   );

   $droplet->reboot(wait_on_event => 1);
   $droplet->snapshot(wait_on_event => 1);

   etc.

DigitalOcean uses DigitalOcean::Event's wait subroutine to wait on events.

time_between_requests

DigitalOcean uses DigitalOcean::Event's wait subroutine to wait on events. It does this by making requests to Digital Ocean until the event is complete. You can use time_between_requests to determine how long DigitalOcean waits between requests before making another request to Digital Ocean to see if an event is done. You can use it like so:

$do->time_between_requests(1);

my $do = DigitalOcean->new(client_id=> $client_id, api_key => $api_key, time_between_requests => 1);

An integer value must be passed in. The default is 2.

AUTHOR

Adam Hopkins <srchulo@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install DigitalOcean, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DigitalOcean

CPAN shell

perl -MCPAN -e shell
install DigitalOcean

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

METHODS

ratelimit_limit

ratelimit_remaining

ratelimit_reset

die_pretty

last_response

per_page

get_user_information

actions

action

domains

create_domain

domain

create_droplet

droplet

droplets

droplet_upgrades

images

distribution_images

application_images

user_images

image

ssh_keys

create_ssh_key

ssh_key

regions

sizes

DOCUMENTATION NEEDS WORK

WAITING ON ACTIONS

wait_on_actions

wait_on_action

time_between_requests

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions