view release on metacpan or  search on metacpan

lib/Amazon/S3/Bucket.pm  view on Meta::CPAN

Filehandle from which object data is read.

The complete contents of the filehandle are staged in a temporary file
before the request is sent.

=item callback

Code reference that supplies object data.

The callback is repeatedly invoked until it returns C<undef>. Each
successful invocation must return a scalar reference containing the next
chunk of object data.

For example:

  my $callback = sub {
    return
      if !@chunks;

    my $chunk = shift @chunks;
  
    return \$chunk;
  };

The complete contents produced by the callback are staged in a temporary
file before the request is sent.

=back

Only one of C<data>, C<filename>, C<fh>, or C<callback> may be supplied.

Other entries in the hash reference are treated in the same manner as
the positional C<configuration> hash.

=head4 Temporary storage

Uploads using C<fh> or C<callback> are staged completely in a temporary
file before the S3 request begins.

Staging allows C[Amazon::S3](Amazon::S3) to determine the complete object size,
calculate request checksums, and replay the upload if necessary.

The system temporary directory must therefore be writable and must have
sufficient free space to hold the complete object. An upload using
C<fh> or C<callback> may fail before contacting S3 if temporary storage
cannot be created or written.

Uploads using C<data> do not require temporary storage.

Uploads using C<filename> use the supplied file directly and do not
create an additional temporary copy.

Temporary files created for C<fh> or C<callback> uploads are removed
after the upload completes or fails.

=head4 Checksums

C<Content-MD5> is added automatically.

C[Amazon::S3](Amazon::S3) also calculates and sends an S3 checksum automatically.
By default, CRC64NVME is used. Most applications do not need to select
or calculate a checksum explicitly.

The checksum algorithm can be changed using the associated
L[Amazon::S3](Amazon::S3) object's C<checksum_algorithm> setting.

See L[Amazon::S3/CHECKSUMS](Amazon::S3/CHECKSUMS).

=head4 Return Value

On success, returns a true value.

On failure, returns C<undef> or throws an exception depending on the
underlying request failure.

=head3 add_key_filename

  my $ok = $bucket->add_key_filename($key, $filename, %configuration,);

Creates or replaces an object using the contents of a local file.

This is a convenience wrapper around the C<filename> form of
C<add_key()>.

The supplied file is streamed directly and is not copied to temporary
storage.

Returns the same value as C<add_key()>.

See L</add_key>.

=head3 copy_object

  my $result = $bucket->copy_object(
    { key    => $destination_key,
      source => $source_key,
      bucket => $source_bucket,
      headers => \%headers,
    }
  );

  my $result = $bucket->copy_object(
    key    => $destination_key,
    source => $source_key,
    bucket => $source_bucket,
  );

Copies an S3 object.

The bucket represented by this object is the destination bucket.

The following parameters are supported:

=over 4

=item bucket

Optional source bucket name.

The default is the destination bucket.

lib/Amazon/S3/Bucket.pm  view on Meta::CPAN

Optional checksum algorithm associated with the multipart upload.

=item key

Required object key.

=item parts

Required hash reference keyed by part number.

For the historical interface, each value is the ETag returned for the
part:

  {
    1 => $etag_1,
    2 => $etag_2,
  }

When checksum information is needed, each value may instead be a hash
reference:

  {
    1 => {
      etag     => $etag_1,
      checksum => $checksum_1,
    },
  }

=item upload_id

Required multipart upload ID.

=back

Returns a true value on success.

Invalid arguments or request errors throw an exception.

=head3 initiate_multipart_upload

  my $upload_id = $bucket->initiate_multipart_upload(
    $key,
    \%headers,
  );

  my ( $upload_id, $algorithm )
    = $bucket->initiate_multipart_upload(
      $key,
      \%headers,
    );

Initiates a multipart upload.

=over 4

=item headers

Optional request headers.

When C<x-amz-checksum-algorithm> is supplied, the selected algorithm
is carried through the multipart workflow.

For CRC64NVME, CRC32, and CRC32C, C<x-amz-checksum-type> is set to
C<FULL_OBJECT>.

=item key

Required object key.

=back

In scalar context, returns the upload ID assigned by S3.

In list context, returns the upload ID and the lowercase checksum
algorithm selected for the upload.

Invalid arguments, unsupported explicitly requested checksum
algorithms, or request errors throw an exception.

=head3 list_multipart_upload_parts

  my $xml = $bucket->list_multipart_upload_parts(
    $key,
    $upload_id,
    \%headers,
  );

Lists parts already uploaded for an existing multipart upload.

=over 4

=item headers

Optional request headers.

=item key

Required object key.

=item upload_id

Required multipart upload ID.

=back

Returns the XML response body returned by S3.

Request errors throw an exception.

=head3 list_multipart_uploads

  my $xml = $bucket->list_multipart_uploads;

  my $xml = $bucket->list_multipart_uploads(\%headers);

Lists active multipart uploads for this bucket.

The optional argument is a request-headers hash reference.

Returns the XML response body returned by S3.

Request errors throw an exception.

=head3 upload_multipart_object

  my $parts = $bucket->upload_multipart_object(
    { key  => $key,
      data => $data,
    }
  );

Uploads an object using the multipart upload API and manages the
multipart lifecycle.

The method accepts a hash reference or a list of key/value pairs.