.\"t
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "" "" "README.md"
.hy
.SH REAMDE.md for Amazon::API Examples
.PP
This directory contains examples demonstrating how you can create a
simple Perl module for various flavors of the Amazon APIs using the
\f[C]Amazon::API\f[R] module as a base class.
.PP
In order to exercise these examples:
.IP \[bu] 2
you must have an Amazon account and credentials with sufficient
privileges to invoke the various APIs.
You can also exercise \f[I]some\f[R] of these examples using API
compatible services like LocalStack (https://localstack.cloud/).
.IP \[bu] 2
Your credentials should be accessible in one of:
.RS 2
.IP \[bu] 2
the environment
.IP \[bu] 2
the role assumed by the EC2 or container your are running in
.IP \[bu] 2
your credentials files configured with the AWS CLI commmand
\f[C]aws configure\f[R]
.RE
.IP \[bu] 2
AWS APIs are (generally speaking) not free, especially if they create
resources.
Most of these examples do not create resources, however you should be
aware of what each of these examples does before invoking them.
For a short description of each of these examples try:
.RS 2
.IP
.nf
\f[C]
perl service-name.pm --help
\f[R]
.fi
.RE
.SH Example Scripts
.PP
Most of these scripts will show you how to use \f[C]Amazon::API\f[R] as
a base class.
Where noted however, the example service may require the use of a class
constructed using the experimental Botocore class constructor
(\f[C]amazon-api\f[R]).
To create the classes for those services use the commands below:
.IP
.nf
\f[C]
for a in ec2 sts; do
  amazon-api -s $a create-stub
  amazon-api -s $a create-shapes
done
\f[R]
.fi
.PP
.TS
tab(@);
l l l.
T{
Name
T}@T{
Service
T}@T{
Notes
T}
_
T{
cloud-watch-events.pm
T}@T{
CloudWatch Events
T}@T{
-
T}
T{
ec2.pm
T}@T{
Elastic Compute Cloud
T}@T{
requires \f[C]Amazon::API::EC2\f[R]
T}
T{
ecr.pm
T}@T{
Elastic Container Registry
T}@T{
-
T}
T{
secrets-manager.pm
T}@T{
Secrets Manager
T}@T{
-
T}
T{
ssm.pm
T}@T{
Systems Manager
T}@T{
-
T}
T{
sts.pm
T}@T{
Security Token Service
T}@T{
requires \f[C]Amazon::API::STS\f[R]
T}
T{
sqs.pm
T}@T{
Simple Queue Service
T}@T{
-
T}
.TE
.PP
The example scripts will execute a subset of the API methods for various
services.
The intent is to show how you can create your own classes or just use
the \f[C]Amazon::API\f[R] class directly to call a service.
.PP
All of the examples are exercised in the same way:
.IP
.nf
\f[C]
perl service-name.pm run API arguments
\f[R]
.fi
.SH Using LocalStack to Run Examples
.PP
If you\[aq]re interested in exercising some of these examples in a local
environment checkout LocalStack (https://localstack.cloud/).
You can use the \f[C]docker-compose.yml\f[R] file below to bring up the
service.
.IP
.nf
\f[C]
version: \[dq]3.8\[dq]

services:
  localstack:
    container_name: \[dq]${LOCALSTACK_DOCKER_NAME-localstack_main}\[dq]
    image: localstack/localstack
    network_mode: bridge
    ports:
      - \[dq]127.0.0.1:4510-4530:4510-4530\[dq]
      - \[dq]127.0.0.1:4566:4566\[dq]
      - \[dq]127.0.0.1:4571:4571\[dq]
    environment:
      - SERVICES=s3,ssm,secretsmanager,kms,sqs,ec2,events
      - DEBUG=${DEBUG-}
      - DATA_DIR=${DATA_DIR-}
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-}
      - HOST_TMP_FOLDER=${TMPDIR:-/tmp/}localstack
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - \[dq]${TMPDIR:-/tmp}/localstack:/tmp/localstack\[dq]
      - \[dq]/var/run/docker.sock:/var/run/docker.sock\[dq]

\f[R]
.fi
.PP
To use LocalStack when exercising an example, use the
\f[C]--endpoint-url\f[R] option.
.IP
.nf
\f[C]
perl sqs.pm --endpoint-url http://localhost:4566 run ListQueues
\f[R]
.fi