Paws - A Perl SDK for AWS (Amazon Web Services) APIs
use Paws; my $obj = Paws->service('...'); my $res = $obj->MethodCall(Arg1 => $val1, Arg2 => $val2); print $res->AttributeFromResult;
Paws is an attempt to develop an always up-to-date SDK that covers all possible AWS services.
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
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::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
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.
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
->service
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
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::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
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 => '' } ])
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;
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:
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.
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.
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');
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->...
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);
If you are going to consume a service behind a VPC Endpoint, you can use the endpoint and the region attributes to configure Paws appropiately
endpoint
region
my $svc = $paws->service('...', endpoint => 'https://endpointaddress', region => 'eu-west-1');
Credential classes need to have the Role Paws::Credential applied. This obliges them to implement access_key, secret_key and session_token methods. The obtention of this data can be customized to be retrieved whereever the developer considers useful (files, environment, other services, etc). Take a look at the Paws::Credential::XXXX namespace to find already implemented credential providers.
The credential objects' access_key, secret_key and session_token methods will be called each time an API call has to be signed.
Caller classes need to have the Role Paws::Net::CallerRole applied. This obliges them to implement the do_call method. Tests use this interface to mock calls and responses to the APIs (without using the network).
The caller instance is responsable for doing the network Input/Output with some type of HTTP request library, and returning the Result from the API.
These callers are included and supported in Paws:
Paws::Net::Caller: Uses HTTP::Tiny. It's the default caller for Paws
Paws::Net::MojoAsyncCaller: Experimental asyncronous IO caller. Paws method calls return futures instead of results
Paws::Net::LWPCaller: Uses LWP. LWP supports HTTPS proxies, so Paws can call AWS from behind an HTTPS proxy.
Paws::Net::FurlCaller: Uses Furl: a lightning fast HTTP client
Paws->preload_service($service) Paws->preload_service($service, @methods)
Paws manages a lot of objects that are loaded dynamically as needed. This causes high memory consumption if you do operations with Paws in a forked environment because each child loads a separate copy of all the classes it needs to do the calls. Paws provides the preload_service operation. Call it with the name of the service before forking off so your server can benefit from copy on write memory sharing. The parent class will load all the classes needed so that child processes don't need to load them.
Some classes have lot's of calls, so preloading them can be quite expensive. If you call preload_service with a list of the methods you will call, it will only load classes needed for those calls. This is specially useful for Paws::EC2, for example.
Preloading doesn't change the usage of Paws. That means that all services and methods still work without any change, just that if they're not preloaded they'll be loaded at runtime.
Paws objects are programmed with Moose (the Modern Perl Object Framework). Moose objects can be immutibilized so that method calls perform better, at the cost of startup time. If you deem your usage of Paws to be long-lived, you can call
Paws->default_config->immutable(1);
as early as possible in the code. Very important that the immutable flag be activated before calling preload_service.
Jose Luis Martinez CPAN ID: JLMARTIN CAPSiDE jlmartinez@capside.com
http://aws.amazon.com/documentation/
https://github.com/pplu/aws-sdk-perl
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 (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.
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
To install Paws, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Paws
CPAN shell
perl -MCPAN -e shell install Paws
For more information on module installation, please visit the detailed CPAN module installation guide.