view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

      region      => 'us-east-1',
      credentials => $creds_obj,
    });

    # List objects in a bucket
    my $result = $s3->list_objects_v2('my-bucket', prefix => 'logs/');

    foreach my $obj ( @{ $result->{objects} } ) {
      printf "%s  %d bytes\n", $obj->{key}, $obj->{size};
    }

    # Paginate
    while ( $result->{is_truncated} ) {
      $result = $s3->list_objects_v2('my-bucket',
        prefix             => 'logs/',
        continuation_token => $result->{next_continuation_token},
      );
      # ... process $result->{objects}
    }

    # Get an object
    my $obj = $s3->get_object('my-bucket', 'path/to/key.json');
    print $obj->{content};

    # Head an object (existence check / metadata only)
    my $meta = $s3->head_object('my-bucket', 'path/to/key.json');
    if ($meta) {
      print $meta->{content_length};
    }

    # Put an object
    $s3->put_object('my-bucket', 'path/to/key.json', $json_string,
      content_type => 'application/json',
      metadata     => { source => 'lambda' },
    );

    # Copy an object
    $s3->copy_object(
      src_bucket => 'my-bucket', src_key => 'orig/file.json',
      dst_bucket => 'my-bucket', dst_key => 'archive/file.json',
    );

    # Delete an object
    $s3->delete_object('my-bucket', 'path/to/key.json');

    # List all buckets
    my $result = $s3->list_buckets;
    for my $bucket ( @{ $result->{buckets} } ) {
      print $bucket->{name}, "\n";
    }

    # Create a bucket
    $s3->create_bucket('my-bucket');
    $s3->create_bucket('my-bucket', region => 'eu-west-1');

    # Configure a Lambda notification trigger
    $s3->put_bucket_notification_configuration('my-bucket',
      type       => 'lambda',
      lambda_arn => $function_arn,
      events     => 's3:ObjectCreated:*',
      filters    => { prefix => 'uploads/' },
    );

    # Configure an SQS notification trigger
    $s3->put_bucket_notification_configuration('my-bucket',
      type      => 'sqs',
      queue_arn => $queue_arn,
      events    => 's3:ObjectCreated:*',
    );

    # Retrieve notification configuration
    my $configs = $s3->get_bucket_notification_configuration('my-bucket');
    for my $cfg ( @{$configs} ) {
      printf "id=%s lambda=%s queue=%s\n",
        $cfg->{id}, $cfg->{lambda_arn} // '', $cfg->{queue_arn} // '';
    }

# DESCRIPTION

`Amazon::S3::Lite` is a minimal Amazon S3 client covering the
operations most commonly needed in AWS Lambda functions and
lightweight scripts: listing buckets, listing objects, reading,
writing, copying, and deleting.

It is built on [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny) (core since Perl 5.14) and
[Amazon::Signature4::Lite](https://metacpan.org/pod/Amazon%3A%3ASignature4%3A%3ALite), with no dependency on LWP or any part of
the libwww-perl ecosystem. The dependency list is intentionally small,
making it well-suited for Lambda container images where minimizing
cold-start time and image size matters.

It is not a replacement for [Amazon::S3](https://metacpan.org/pod/Amazon%3A%3AS3) or [Net::Amazon::S3](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3AS3), which
support the full S3 API surface including multipart upload, bucket
management, ACLs, versioning, and presigned URLs. If you need those
features, use one of those distributions instead.

[Amazon::S3::Thin](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3AThin) is another excellent lightweight S3 client with a
similar philosophy and a longer track record. It is more complete than
this module - supporting presigned URLs, bulk delete, and
virtual-hosted-style requests - and returns raw [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse)
objects so callers handle status codes and errors
themselves. `Amazon::S3::Lite` differs in three ways: it has no
dependency on LWP (`Amazon::S3::Thin` defaults to [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent)),
it returns parsed hashrefs rather than raw response objects, and it
has first-class support for Lambda IAM role credential rotation. If
you need the broader feature set or prefer direct HTTP access,
`Amazon::S3::Thin` is a fine choice.

# CONSTRUCTOR

## new

    my $s3 = Amazon::S3::Lite->new(\%options);

Returns a new `Amazon::S3::Lite` object. Options:

- region (options, default: us-east-1)

    The AWS region for your bucket, e.g. `us-east-1`.

- aws\_access\_key\_id / aws\_secret\_access\_key

    Static credentials. `token` may also be supplied for STS temporary
    credentials (as used by Lambda execution roles).

    These are only consulted if no `credentials` object is provided.

- token

    Optional STS session token, used alongside static credentials for
    temporary credential sets.

- credentials

    An object providing credential getters. The object must respond to:

        $creds->aws_access_key_id
        $creds->aws_secret_access_key
        $creds->token            # may return undef

    Any object that satisfies this interface is accepted -
    [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials), [Paws::Credential::\*](https://metacpan.org/pod/Paws%3A%3ACredential%3A%3A%2A), or your own. The
    getters are called at request time, so objects that refresh expiring
    credentials transparently are supported.

- logger

    An object providing the standard log methods:

        $logger->trace(...)
        $logger->debug(...)
        $logger->info(...)
        $logger->warn(...)

share/README.md  view on Meta::CPAN

whichever of the following are set:

- index\_document

    The index document suffix.

- error\_document

    The error document key.

- redirect\_all\_requests\_to

    The hostname all requests are redirected to, if the bucket is
    configured as a redirect.

## delete\_bucket\_website

    $s3->delete_bucket_website($bucket);

Removes the website configuration from a bucket. Returns a true value
on success.

## put\_bucket\_policy

    $s3->put_bucket_policy($bucket, \%policy);
    $s3->put_bucket_policy($bucket, $json_string);

Attaches a bucket policy. The policy may be given either as a Perl
data structure (a hashref, which is encoded to canonical JSON) or as a
pre-encoded JSON string. Returns a true value on success.

## get\_bucket\_policy

    my $policy = $s3->get_bucket_policy($bucket);
    my $json   = $s3->get_bucket_policy($bucket, raw => 1);

Returns the bucket's policy, or `undef` if the bucket has no policy
(S3 returns `NoSuchBucketPolicy`). By default the policy is decoded
and returned as a hashref; pass `raw => 1` to get the raw JSON
string instead.

- raw

    When true, return the policy as its raw JSON string rather than a
    decoded hashref.

## put\_bucket\_notification\_configuration

    # Lambda trigger
    $s3->put_bucket_notification_configuration($bucket,
      type       => 'lambda',
      lambda_arn => $function_arn,
      events     => 's3:ObjectCreated:*',
    );

    # SQS trigger
    $s3->put_bucket_notification_configuration($bucket,
      type      => 'sqs',
      queue_arn => $queue_arn,
      events    => [qw(s3:ObjectCreated:* s3:ObjectRemoved:*)],
      filters   => { prefix => 'uploads/', suffix => '.csv' },
    );

Sets the bucket notification configuration for `$bucket`, routing
S3 events to a Lambda function or SQS queue.

Options:

- type (required)

    The notification target type. Must be `lambda` or `sqs`.

- lambda\_arn (required when type is `lambda`)

    The ARN of the Lambda function to invoke.

- queue\_arn (required when type is `sqs`)

    The ARN of the SQS queue to deliver messages to.

- events (required)

    A scalar event name or an arrayref of event names.
    Common values: `s3:ObjectCreated:*`, `s3:ObjectRemoved:*`.

- filters

    A hashref of S3 key filter rules. Supported keys are `prefix`
    and `suffix`.

- id

    An identifier for the configuration entry. Defaults to `notification-1`.

Returns true on success. Croaks on failure.

## get\_bucket\_notification\_configuration

    my $configs = $s3->get_bucket_notification_configuration($bucket);

    for my $cfg ( @{$configs} ) {
      if ( $cfg->{lambda_arn} ) {
        printf "Lambda: id=%s arn=%s\n", $cfg->{id}, $cfg->{lambda_arn};
      }
      elsif ( $cfg->{queue_arn} ) {
        printf "SQS:    id=%s arn=%s\n", $cfg->{id}, $cfg->{queue_arn};
      }
      print "  events: ", join(', ', @{ $cfg->{events} }), "\n";
    }

Retrieves the current notification configuration for `$bucket`.
Handles both Lambda (`CloudFunctionConfiguration`) and SQS
(`QueueConfiguration`) entries, which are the XML element names
the S3 API returns regardless of how the configuration was created.

Returns an arrayref of configuration hashrefs, each containing:

- id

    The configuration entry identifier.