The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Amazon-Glacier-0.13
River stage one • 1 direct dependent • 1 total dependent
++
/ Net::Amazon::Glacier

NAME

Net::Amazon::Glacier - An implementation of the Amazon Glacier RESTful API.

VERSION

Version 0.13

SYNOPSIS

This module implements the Amazon Glacier RESTful API, version 2012-06-01 (current at writing). It can be used to manage Glacier vaults and upload archives to them. Amazon Glacier is Amazon's long-term storage service.

Perhaps a little code snippet.

        use Net::Amazon::Glacier;

        my $glacier = Net::Amazon::Glacier->new(
                'eu-west-1',
                'AKIMYACCOUNTID',
                'MYSECRET',
        );
        
        my $vault = 'a_vault';
        my @vaults = $glacier->list_vaults();
        
        if ( $glacier->create_vault( $vault ) ) {

                if ( my $archive_id = $glacier->upload_archive( './archive.7z' ) ) {

                        my $job_id = $glacier->inititate_job( $vault, $archive_id );
                        
                        # Jobs generally take about 4 hours to complete
                        my $job_description = $glacier->describe_job( $vault, $job_id );
                        
                        # For a better way to wait for completion, see
                        # http://docs.aws.amazon.com/amazonglacier/latest/dev/api-initiate-job-post.html
                        while ( $job_description->{'StatusCode'} ne 'Succeeded' ) {
                                sleep 15 * 60 * 60;
                                $job_description = $glacier->describe_job( $vault, $job_id );
                        }
                        
                        my $archive_bytes = $glacier->get_job_output( $vault, $job_id );
                        
                        # Jobs live as completed jobs for "a period", according to
                        # http://docs.aws.amazon.com/amazonglacier/latest/dev/api-jobs-get.html
                        my @jobs = $glacier->list_jobs( $vault );
                        
                        # As of 2013-02-09 jobs are blindly created even if a job for the same archive_id and Range exists.
                        # Keep $archive_ids, reuse the expensive job resource, and remember 4 hours.
                        foreach my $job ( @jobs ) {
                                next unless $job->{ArchiveId} eq $archive_id;
                                my $archive_bytes = $glacier->get_job_output( $vault, $job_id );
                        }

                }
                
        }

The functions are intended to closely reflect Amazon's Glacier API. Please see Amazon's API reference for documentation of the functions: http://docs.amazonwebservices.com/amazonglacier/latest/dev/amazon-glacier-api.html.

CONSTRUCTOR

new( $region, $access_key_id, $secret )

VAULT OPERATORS

create_vault( $vault_name )

Creates a vault with the specified name. Returns true on success, false on failure. Create Vault (PUT vault)

delete_vault( $vault_name )

Deletes the specified vault. Returns true on success, false on failure. Delete Vault (DELETE vault)

describe_vault( $vault_name )

Fetches information about the specified vault. Returns a hash reference with the keys described by http://docs.amazonwebservices.com/amazonglacier/latest/dev/api-vault-get.html. Returns false on failure. Describe Vault (GET vault)

list_vaults

Lists the vaults. Returns an array with all vaults. Amazon Glacier List Vaults (GET vaults).

A call to list_vaults can result in many calls to the the Amazon API at a rate of 1 per 1,000 vaults in existence. Calls to List Vaults in the API are free.

set_vault_notifications( $vault_name, $sns_topic, $events )

Sets vault notifications for a given vault. An SNS Topic to send notifications to must be provided. The SNS Topic must grant permission to the vault to be allowed to publish notifications to the topic. An array ref to a list of events must be provided. Valid events are ArchiveRetrievalCompleted and InventoryRetrievalCompleted upon job completion may also be supplied. Return true on success, false otherwise. Set Vault Notification Configuration (PUT notification-configuration).

get_vault_notifications( $vault_name )

Gets vault notifications status for a given vault. Return false on failure or a hash with an 'SNSTopic' and and array of 'Events' on success. Get Vault Notifications (GET notification-configuration).

delete_vault_notifications( $vault_name )

Deletes vault notifications for a given vault. Return true on success, false otherwise. Delete Vault Notifications (DELETE notification-configuration).

ARCHIVE OPERATIONS

upload_archive( $vault_name, $archive_path, [ $description ] )

Uploads an archive to the specified vault. $archive_path is the local path to any file smaller than 4GB. For larger files, see multi-part upload. An archive description of up to 1024 printable ASCII characters can be supplied. Returns the Amazon-generated archive ID on success, or false on failure. Upload Archive (POST archive)

delete_archive( $vault_name, $archive_id )

Issues a request to delete a file from Glacier. $archive_id is the ID you received either when you uploaded the file originally or from an inventory. Delete Archive (DELETE archive)

JOB OPERATIONS

initiate_archive_retrieval( $vault_name, $archive_id, [ $description, $sns_topic ] )

Initiates an archive retrieval job. $archive_id is an ID previously retrieved from Amazon Glacier. A job description of up to 1,024 printable ASCII characters may be supplied. An SNS Topic to send notifications to upon job completion may also be supplied. Initiate a Job (POST jobs).

initiate_inventory_retrieval( $vault_name, [ $format, $description, $sns_topic ] )

Initiates an inventory retrieval job. $format is either CSV or JSON (default). A job description of up to 1,024 printable ASCII characters may be supplied. An SNS Topic to send notifications to upon job completion may also be supplied. Initiate a Job (POST jobs).

initiate_job( ( $vault_name, $archive_id, [ $description, $sns_topic ] )

Effectively calls initiate_inventory_retrieval. Exists for the sole purpose or implementing the Amazon Glacier Developer Guide (API Version 2012-06-01) nomenclature. Initiate a Job (POST jobs).

describe_job( $vault_name, $job_id )

Retrieves a hashref with information about the requested JobID. Amazon Glacier Describe Job (GET JobID).

get_job_output( $vault_name, $job_id, [ $range ] )

Retrieves the output of a job, returns a binary blob. Optional range parameter is passed as an HTTP header. Amazon Glacier Get Job Output (GET output).

list_jobs( $vault_name )

Return an array with information about all recently completed jobs for the specified vault. Amazon Glacier List Jobs (GET jobs).

A call to list_jobs can result in many calls to the the Amazon API at a rate of 1 per 1,000 recently completed job in existence. Calls to List Jobs in the API are free.

NOT IMPLEMENTED

The following parts of Amazon's API have not yet been implemented. This is mainly because the author hasn't had a use for them yet. If you do implement them, feel free to send a patch.

  • Multipart upload operations

SEE ALSO

See also Victor Efimov's MT::AWS::Glacier, an application for AWS Glacier synchronization. It is available at https://github.com/vsespb/mt-aws-glacier.

AUTHORS

Maintained and originally written by Tim Nordenfur, <tim at gurka.se>. Support for job operations was contributed by Ted Reed at IMVU. Support for many operations was contributed by Gonzalo Barco.

BUGS

Please report any bugs or feature requests to bug-net-amazon-glacier at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Amazon-Glacier. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Amazon::Glacier

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2012 Tim Nordenfur.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.