NAME

Paws - A Perl SDK for AWS (Amazon Web Services) APIs

SYNOPSIS

  use Paws;
  my $obj = Paws->service('...');
  my $res = $obj->MethodCall(Arg1 => $val1, Arg2 => $val2);
  print $res->AttributeFromResult;

DESCRIPTION

Paws is an attempt to develop an always up-to-date SDK that covers all possible AWS services.

STATUS

Please consider the SDK is beta quality. The intention of publishing to CPAN is having the community find the SDK, try it, give feedback, etc. Some services are still not working, and some heavy refactoring will still be done to the internals. The external interface to SDK users will try to be kept stable, and changes to it should be notified via ChangeLog

SUPPORTED SERVICES

Please take a look at classes in the Paws::XXX namespace

SERVICES CLASSES

Each service in AWS (EC2, CloudFormation, SQS, SNS, etc) has a service class. The service class represents the properties that a web service has (how to call it, what methods it has, how to authenticate, etc). When a service class is instanced with the right properties (region, if needed, credentials, caller, etc), it will be able to make calls to the service.

Service classes are obtained through

  my $service_class = Paws->class_for_service('Service');
  my $service_object = $service_class->new(region => '...', caller => ...)

Although they are seldom needed. 99% of the time you want service objects directly obtained with the ->service method (read next section) since you have to write less code.

SERVICE OBJECTS

Each Service Object represents the ability to call methods on a service endpoint. Those endpoints are either global, or bound to a region depending on the service. Also, each object can be customized with a credential provider, that tells the object where to obtain credentials for the call (you can get them from the environment, from the filesystem, from the AWS Instance Profile, STS, etc.

To obtain a service object, call the ->service method

  use Paws;
  my $service = Paws->service('Service');

You can pass extra parameters if the service is bound to a region:

  my $service = Paws->service('Service', region => 'us-east-1');

These parameters are basically passed to the service class constructor

AUTHENTICATION

Service classes by default try to authenticate with a chained autheticator. The chained authenticator tries to first find credentials in your enviroinment variables AWS_ACCESS_KEY and AWS_SECRET_KEY (note that AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are also scanned for compatibility with the official SDKs). Second, it will look for credentials in the default profile of the ~/.aws/credentials (an ini-formatted file). Last, if no environment variables are found, then a call to retrieve Role credentials is done. If your instance is running on an AWS instance, and has a Role assigned, the SDK will automatically retrieve credentials to call any services that the instances Role permits.

Please never burn credentials into your code. That's why the methods for passing an explicit access key and secret key are not documented.

So, instancing a service with

  my $ec2 = Paws->service('EC2', region => 'eu-west-1');

we get an service object that will try to authenticate with environment, credential file, or an instance role.

When instancing a service object, you can also pass a custom credential provider:

  use Paws::Credential::STS;

  my $cred_provider = Paws::Credential::STS->new(
    Name => 'MyName',
    DurationSeconds => 900,
    Policy => '{"Version":"2012-10-17","Statement":[{"Effect": "Allow","Action":["ec2:DescribeInstances"],"Resource":"*"}]}'
  );
  my $ec2 = Paws->service('EC2', credentials => $cred_provider, region => 'eu-west-1');

In this example we instance a service object that uses the STS service to create temporary credentials that only let the service object call DescribeInstances.

Using Service objects (Calling APIs)

Each API call is represented as a method call with the same name as the API call. The arguments to the call are passed as lists (named parameters) to the call. So, to call DescribeInstances on the EC2 service:

  my $result = $ec2->DescribeInstances;

The DescribeInstances call has no required parameters, but if needed, we can pass them in (you can look them up in Paws::EC2 and see detail in Paws::EC2::DescribeInstances

  my $result = $ec2->DescribeInstances(MaxResults => 5);

If the parameter is an Array:

  my $result = $ec2->DescribeInstances(InstanceIds => [ 'i-....' ]);

If the parameter to be passed in is a complex value (an object)

  my $result = $ec2->DescribeInstances(Filters => [ { Name => '', Value => '' } ])

RETURN VALUES

The AWS APIs return nested datastructures in various formats. The SDK converts these datastructures into objects that can then be used as wanted.

  my $private_dns = $result->Reservations->[0]->Instances->[0]->PrivateDnsName;

AUTHOR

    Jose Luis Martinez
    CPAN ID: JLMARTIN
    CAPSiDE
    jlmartinez@capside.com

SEE ALSO

http://aws.amazon.com/documentation/

https://github.com/pplu/aws-sdk-perl

BUGS and CONTRIBUTIONS

The source code is located here: https://github.com/pplu/aws-sdk-perl

Please report bugs to: https://github.com/pplu/aws-sdk-perl/issues

cpanm Paws::SDK::Config

perl -MCPAN -e shell
install Paws::SDK::Config