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

Paws::AccessAnalyzer

Paws::ACM

Paws::ACMPCA

Paws::AlexaForBusiness

Paws::Amplify

Paws::AmplifyBackend

Paws::ApiGateway

Paws::ApiGatewayManagement

Paws::ApiGatewayV2

Paws::AppConfig

Paws::Appflow

Paws::AppIntegrations

Paws::ApplicationAutoScaling

Paws::ApplicationCostProfiler

Paws::ApplicationInsights

Paws::ApplicationMigration

Paws::AppMesh

Paws::AppRunner

Paws::AppStream

Paws::AppSync

Paws::Athena

Paws::AuditManager

Paws::AutoScaling

Paws::AutoScalingPlans

Paws::Backup

Paws::Batch

Paws::Braket

Paws::Budgets

Paws::Chime

Paws::Cloud9

Paws::CloudDirectory

Paws::CloudFormation

Paws::CloudFront

Paws::CloudHSM

Paws::CloudHSMv2

Paws::CloudSearch

Paws::CloudSearchDomain

Paws::CloudTrail

Paws::CloudWatch

Paws::CloudWatchEvents

Paws::CloudWatchLogs

Paws::CodeArtifact

Paws::CodeBuild

Paws::CodeCommit

Paws::CodeDeploy

Paws::CodeGuruProfiler

Paws::CodeGuruReviewer

Paws::CodePipeline

Paws::CodeStar

Paws::CodeStarConnections

Paws::CodeStarNotifications

Paws::CognitoIdentity

Paws::CognitoIdp

Paws::CognitoSync

Paws::Comprehend

Paws::ComprehendMedical

Paws::ComputeOptimizer

Paws::Config

Paws::Connect

Paws::ConnectContactLens

Paws::ConnectParticipant

Paws::CostExplorer

Paws::CUR

Paws::CustomerProfiles

Paws::DataExchange

Paws::DataPipeline

Paws::Datasync

Paws::DAX

Paws::Detective

Paws::DeviceFarm

Paws::DevOpsGuru

Paws::DirectConnect

Paws::Discovery

Paws::DLM

Paws::DMS

Paws::DocDB

Paws::DS

Paws::DynamoDB

Paws::DynamoDBStreams

Paws::EBS

Paws::EC2

Paws::EC2InstanceConnect

Paws::ECR

Paws::ECRPublic

Paws::ECS

Paws::EFS

Paws::EKS

Paws::ElastiCache

Paws::ElasticBeanstalk

Paws::ElasticInference

Paws::ElasticTranscoder

Paws::ELB

Paws::ELBv2

Paws::EMR

Paws::EMRContainers

Paws::ES

Paws::Finspace

Paws::FinspaceData

Paws::Firehose

Paws::FIS

Paws::FMS

Paws::Forecast

Paws::ForecastQuery

Paws::FraudDetector

Paws::FSX

Paws::GameLift

Paws::Glacier

Paws::GlobalAccelerator

Paws::Glue

Paws::GlueDataBrew

Paws::Greengrass

Paws::GreengrassV2

Paws::GroundStation

Paws::GuardDuty

Paws::Health

Paws::HealthLake

Paws::Honeycode

Paws::IAM

Paws::ImageBuilder

Paws::ImportExport

Paws::Inspector

Paws::IoT

Paws::IoT1ClickDevices

Paws::IoT1ClickProjects

Paws::IoTAnalytics

Paws::IoTData

Paws::IoTDeviceAdvisor

Paws::IoTEvents

Paws::IoTEventsData

Paws::IoTFleetHub

Paws::IoTJobsData

Paws::IoTSecureTunneling

Paws::IoTSiteWise

Paws::IoTThingsGraph

Paws::IoTWireless

Paws::IVS

Paws::Kafka

Paws::Kendra

Paws::Kinesis

Paws::KinesisAnalytics

Paws::KinesisAnalyticsV2

Paws::KinesisVideo

Paws::KinesisVideoArchivedMedia

Paws::KinesisVideoMedia

Paws::KinesisVideoSignaling

Paws::KMS

Paws::LakeFormation

Paws::Lambda

Paws::LexModels

Paws::LexModelsV2

Paws::LexRuntime

Paws::LexRuntimeV2

Paws::LicenseManager

Paws::Lightsail

Paws::LocationService

Paws::LookoutEquipment

Paws::LookoutMetrics

Paws::LookoutVision

Paws::MachineLearning

Paws::Macie

Paws::Macie2

Paws::ManagedBlockchain

Paws::MarketplaceCatalog

Paws::MarketplaceCommerceAnalytics

Paws::MarketplaceEntitlement

Paws::MarketplaceMetering

Paws::MediaConnect

Paws::MediaConvert

Paws::MediaLive

Paws::MediaPackage

Paws::MediaPackageVod

Paws::MediaStore

Paws::MediaStoreData

Paws::MediaTailor

Paws::MigrationHub

Paws::MigrationHubConfig

Paws::MobileHub

Paws::MQ

Paws::MTurk

Paws::MWAA

Paws::Neptune

Paws::NetworkFirewall

Paws::NetworkManager

Paws::NimbleStudio

Paws::OpsWorks

Paws::OpsWorksCM

Paws::Organizations

Paws::Outposts

Paws::PerformanceInsights

Paws::Personalize

Paws::PersonalizeEvents

Paws::PersonalizeRuntime

Paws::Pinpoint

Paws::PinpointEmail

Paws::PinpointSMSVoice

Paws::PinpointSMSVoice

Paws::Polly

Paws::Pricing

Paws::Prometheus

Paws::Proton

Paws::QLDB

Paws::QLDBSession

Paws::Quicksight

Paws::RAM

Paws::RDS

Paws::RDSData

Paws::RedShift

Paws::RedshiftData

Paws::Rekognition

Paws::ResourceGroups

Paws::ResourceTagging

Paws::Robomaker

Paws::Route53

Paws::Route53Domains

Paws::Route53Resolver

Paws::S3

Paws::S3Control

Paws::S3Outposts

Paws::SageMaker

Paws::SageMakerA2IRuntime

Paws::SageMakerEdge

Paws::SageMakerFeatureStoreRuntime

Paws::SageMakerRuntime

Paws::SavingsPlans

Paws::Schemas

Paws::SDB

Paws::SecretsManager

Paws::SecurityHub

Paws::ServerlessRepo

Paws::ServiceCatalog

Paws::ServiceCatalogAppRegistry

Paws::ServiceDiscovery

Paws::ServiceQuotas

Paws::SES

Paws::SESv2

Paws::Shield

Paws::Signer

Paws::SimpleWorkflow

Paws::SMS

Paws::Snowball

Paws::SNS

Paws::SQS

Paws::SSM

Paws::SSMContacts

Paws::SSMIncidents

Paws::SSO

Paws::SSOAdmin

Paws::SSOIdentityStore

Paws::SSOOidc

Paws::StepFunctions

Paws::StorageGateway

Paws::STS

Paws::Support

Paws::Synthetics

Paws::Textract

Paws::TimestreamQuery

Paws::TimestreamWrite

Paws::Transcribe

Paws::Transfer

Paws::Translate

Paws::WAF

Paws::WAFRegional

Paws::WAFV2

Paws::WellArchitected

Paws::WorkDocs

Paws::WorkLink

Paws::WorkMail

Paws::WorkMailMessageFlow

Paws::WorkSpaces

Paws::XRay

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 instantiated 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 authenticator. The chained authenticator tries to first find credentials in your environment 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 or the file in AWS_CONFIG_FILE env variable (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, instantiating 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 instantiating 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.

Paws bundles some pre-baked credential providers:

Paws::Credential::ProviderChain - Gets credentials from a list of providers, returning the first provider to return credentials

Paws::Credential::Environment - Gets credentials from environment variables

Paws::Credential::File - Gets credentials from AWS SDK config files

Paws::Credential::InstanceProfile - Gets credentials from the InstanceProfile (Role) of the running instance

Paws::Credential::InstanceProfileV2 - Gets credentials from the InstanceProfile (Role) of the running instance using IMDSv2 approach

Paws::Credential::STS - Gets temporary credentials from the Secure Token Service

Paws::Credential::AssumeRole - Gets temporary credentials with AssumeRole

Paws::Credential::AssumeRoleWithSAML - Gets temporary credentials with AssumeRoleWithSAML

Paws::Credential::Explicit - Gets credentials specified in the code

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;

CONFIGURATION

Paws instances have a configuration. The configuration is basically a specification of values that will be passed to the service method each time it's called

  # the credentials and the caller keys accept an instance or the name of a class as a 
  # string (the class will be loaded and the constructor of that class will be automatically called
  my $paws1 = Paws->new(config => { credentials => MyCredProvider->new, region => 'eu-west-1' });
  my $paws2 = Paws->new(config => { caller => 'MyCustomCaller' });
  
  # EC2 service with MyCredProvider in eu-west-1
  my $ec2 = $paws1->service('EC2');
  # DynamoDB service with MyCustomCaller in us-east-1. region is needed because it's not in the config
  my $ddb = $paws2->service('DynamoDB', region => 'us-east-1');
  # DynamoDB in eu-west-1 with MyCredProvider
  my $other_ddb = $paws1->service('DynamoDB');

The attributes that can be configured are:

credentials

Accepts a string which value is the name of a class, or an already instantiated object. If a string is passed, the class will be loaded, and the constructor called (without parameters). Also, the resulting instance or the already instantiated object has to have the Paws::Credential role.

caller

Accepts a string which value is the name of a class, or an already instantiated object. If a string is passed, the class will be loaded, and the constructor called (without parameters). Also, the resulting instance or the already instantiated object has to have the Paws::Net::CallerRole role.

region

A string representing the region that service objects will be instantiated with. Most services need a region specified, meaning that you will have to specify the desired region every time you call the service method.

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

Some services (like IAM) are global, so they don't need their region specified:

  my $iam = Paws->service('IAM');

A special service is STS, which by default has a global endpoint, but you can also specify regional endpoints

  my $global_sts = Paws->service('STS');
  my $regional_sts = Paws->service('STS', region => 'eu-west-1');

endpoint

Paws needs to send HTTP requests to different URLS (endpoints) depending on the service and the region. URLs are normally automatically derived by specifying the region, but for special cases, like pointing to "fake-sqs" or "fake-s3" services, you can:

  Paws->service('SQS', endpoint => 'http://localhost:3000', region => 'eu-west-1');

Some services, like the MachineLearning predictor API want you to specify a custom endpoint:

  my $model = $ml->GetMLModel(MLModelId => $model_id);
  my $predictor = Paws->service('ML', endpoint => $model->EndpointInfo->EndpointUrl, region => 'eu-west-1');
  $predictor->...

max_attempts

Sets the total number of request attempts to make per API call, by retrying after failures. For most services the value defaults to 5 - that is, after a failure, up to 4 retries will be made, making a total of up to 5 attempts.

  my $sms = Paws->service('SMS', max_attempts => 10);

  my $svc = $paws->service('...', endpoint => 'https://endpointaddress', region => 'eu-west-1');

Pluggability

Optimization

  Paws->preload_service($service)
  Paws->preload_service($service, @methods)

  Paws->default_config->immutable(1);

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 SOURCE

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>

COPYRIGHT and LICENSE

Copyright (c) 2015 by Jose Luis Martinez Torres

This code is distributed under the Apache 2 License. The full text of the license can be found in the LICENSE file included with this module.

CONTRIBUITIONS

CAPSiDE (https://www.capside.com) for letting Paws be contributed in an open source model and giving me time to build and maintain it regularly.

ZipRecruiter (https://www.ziprecruiter.com/) for sponsoring development of Paws. Lots of work from ZipRecruiter has been done via Shadowcat Systems (https://shadow.cat/).

castaway for contributing to fixing documentation problems
- taking the reigns of Paws, become part of the core team that pushes it forward
- properly providing backlinks between related pages
- making TOCs render correctly on search.cpan.org
- generating helpful copy-paste ready scenarios in the synopsis of each method call

Luis Alberto Gimenez (@agimenez) for
- The git-fu cleaning up the "pull other sdks" code
- Credential Providers code
- Fixes for users that have no HOME env variable
- FileCaller to fully mock responses

Srinvas (@kidambisrinivas) for testing, bug reporting and fixing

juair10 for corrections and testing

CHORNY for CPAN and cpanfile packaging corrections

Iñigo Tejedor for service endpoint resolution based on rules

codehead for helping fix SQS Queue Maps

mbartold for helping fix SQS MessageBatch functionality

coreymayer for reporting bug in RestXmlCaller

arc (Aaron Crane) for documentation patches

dtikhonov for LWP Caller and bug reporting/fixing

vivus-ignis for DynamoDB bug reporting and test scripts for DynamoDB

karenetheridge for bug reporting, pull requests and help

ioanrogers for fixing unicode issues in tests

ilmari for fixing issues with timestamps in Date and X-Amz-Date headers, test fixes and 5.10 support fixes, documentation issue fixes for S3, CloudFront and Route53, help with number stringification

stevecaldwell77 for
- contributing support for temporary credentials in S3
- Fixing test suite failure scenarios

Ryan Olson (BeerBikesBBQ) for contributing documentation fixes

Roger Pettett for testing and contributing fixes for tests on MacOSX

Henri Yandell for help with licensing issues

Oriol Soriano (@ureesoriano) for contributions to API builders and better documentation generation

H. Daniel Cesario (@maneta) for devel setup instructions on RH and MacOSX

Glen van Ginkel for contributions to get S3 working

Javier Arellano for discovering Tagging bug

Ioan Rogers for contributing AssumeRoleWithSAML with ADFS auth example

Miquel Soriano for reporting a bug with DescribeAutoScalingGroups

Albert Bendicho (wiof) for contributing better retry logic

Brian Hartsock for better handling of XMLResponse exceptions

rpcme for reporting various bugs in the SDK

glenveegee for lots of work sorting out the S3 implementation

Grinzz
- many bugs, suggestions and fixes
- Installation speedup with Module::Builder::Tiny

Dakkar for solving issues with parameter passing

Arthur Axel fREW Schmidt for speeding up credential refreshing

PopeFelix for solving issues around S3 and MojoAsyncCaller

meis for (between others):
- contributing Paws::Credential::Explicit
- enabling unstable warnings to be silenced

sven-schubert for contributing fixes to RestXML services, working on fixing S3 to work correctly.

SeptamusNonovant for fixing paginators in non-callback mode

gadgetjunkie for contributing the ECS credential provider

mla for contributing a fix to correct dependencies

autarch for correcting signature generation for a bunch of services

piratefinn for linking calls to documentation AWS URLs

slobo for fixing S3 behaviour

bork1n for fixes to MojoAsynCaller

atoomic for:
- tweaking CPAN packaging
- improving paws CLI

leonerd for (between others)
- documenting retry logic
- fixing retry sleep of MojoAsyncCaller

campus-explorer for contributing to test suite

byterock for:
- testing and fixing PinPoint
- standing up as comaint, and releasing 0.43
- improving S3 support

torrentale for fixing QueryCaller to correctly signal empty arrays

Jess Robinson and shadowcat.co.uk for:
- doing lots of comaint work
- working hard on new features

shogo82148 for migrating our Travis pipelines to GitHub Actions (and improving them)

aeruder for contributing
- Fixing DynamoDB retry fixes
- Completing speedups and benchmarking code
- Substituting Config::INI for Config::AWS
- Parrallelizing and fixing generation inconsistencies of the SDK

dheffx for making ContainerProfile credential provider more robust

0leksii for building support for Instance Metadata Service v2 (IMDSv2)