/ 
Net-Amazon-S3-0.991
River stage two • 14 direct dependents • 16 total dependents
/ Net::Amazon::S3::Client::Object

NAME

Net::Amazon::S3::Client::Object - An easy-to-use Amazon S3 client object

VERSION

version 0.991

SYNOPSIS

  # show the key
  print $object->key . "\n";

  # show the etag of an existing object (if fetched by listing
  # a bucket)
  print $object->etag . "\n";

  # show the size of an existing object (if fetched by listing
  # a bucket)
  print $object->size . "\n";

  # to create a new object
  my $object = $bucket->object( key => 'this is the key' );
  $object->put('this is the value');

  # to get the value of an object
  my $value = $object->get;

  # to get the metadata of an object
  my %metadata = %{$object->head};

  # to see if an object exists
  if ($object->exists) { ... }

  # to delete an object
  $object->delete;

  # to create a new object which is publically-accessible with a
  # content-type of text/plain which expires on 2010-01-02
  my $object = $bucket->object(
    key          => 'this is the public key',
    acl          => Net::Amazon::S3::ACL::CANNED->PUBLIC_READ,
    content_type => 'text/plain',
    expires      => '2010-01-02',
  );
  $object->put('this is the public value');

  # return the URI of a publically-accessible object
  my $uri = $object->uri;

  # to view if an object is available for downloading
  # Basically, the storage class isn't GLACIER or the object was
  # fully restored
  $object->available;

  # to restore an object on a GLACIER storage class
  $object->restore(
    days => 1,
    tier => 'Standard',
  );

  # to store a new object with server-side encryption enabled
  my $object = $bucket->object(
    key        => 'my secret',
    encryption => 'AES256',
  );
  $object->put('this data will be stored using encryption.');

  # upload a file
  my $object = $bucket->object(
    key          => 'images/my_hat.jpg',
    content_type => 'image/jpeg',
  );
  $object->put_filename('hat.jpg');

  # upload a file if you already know its md5_hex and size
  my $object = $bucket->object(
    key          => 'images/my_hat.jpg',
    content_type => 'image/jpeg',
    etag         => $md5_hex,
    size         => $size,
  );
  $object->put_filename('hat.jpg');

  # download the value of the object into a file
  my $object = $bucket->object( key => 'images/my_hat.jpg' );
  $object->get_filename('hat_backup.jpg');

  # use query string authentication for object fetch
  my $object = $bucket->object(
    key          => 'images/my_hat.jpg',
    expires      => '2009-03-01',
  );
  my $uri = $object->query_string_authentication_uri();

	# use query string authentication for object upload
	my $object = $bucket->object(
		key          => 'images/my_hat.jpg',
		expires      => '2009-03-01',
	);
	my $uri = $object->query_string_authentication_uri_for_method('PUT');

DESCRIPTION

This module represents objects in buckets.

METHODS

range

my $value = $object->range ('bytes=1024-10240')->get;

Provides simple interface to ranged download. See also Net::Amazon::S3::Client::Object::Range.

etag

# show the etag of an existing object (if fetched by listing
# a bucket)
print $object->etag . "\n";

delete

# to delete an object
$object->delete;

exists

# to see if an object exists
if ($object->exists) { ... }

Method doesn't report error when bucket or key doesn't exist.

get

# to get the vaue of an object
my $value = $object->get;
# to get the metadata of an object
my %metadata = %{$object->head};

Unlike exists this method does report error.

get_decoded

# get the value of an object, and decode any Content-Encoding and/or
# charset; see decoded_content in HTTP::Response
my $value = $object->get_decoded;

get_filename

# download the value of the object into a file
my $object = $bucket->object( key => 'images/my_hat.jpg' );
$object->get_filename('hat_backup.jpg');

last_modified, last_modified_raw

# get the last_modified data as DateTime (slow)
my $dt = $obj->last_modified;
# or raw string in form '2015-05-15T10:12:40.000Z' (fast)
# use this form if you are working with thousands of objects and
# do not actually need an expensive DateTime for each of them
my $raw = $obj->last_modified_raw;

key

# show the key
print $object->key . "\n";

available

# to view if an object is available for downloading
# Basically, the storage class isn't GLACIER or the object was
# fully restored
$object->available;

restore

# to restore an object on a GLACIER storage class
$object->restore(
  days => 1,
  tier => 'Standard',
);

put

# to create a new object
my $object = $bucket->object( key => 'this is the key' );
$object->put('this is the value');

# to create a new object which is publically-accessible with a
# content-type of text/plain
my $object = $bucket->object(
  key          => 'this is the public key',
  acl          => 'public-read',
  content_type => 'text/plain',
);
$object->put('this is the public value');

For acl refer Net::Amazon::S3::ACL.

You may also set Content-Encoding using content_encoding, and Content-Disposition using content_disposition.

You may specify the S3 storage class by setting storage_class to either standard, reduced_redundancy, standard_ia, onezone_ia, intelligent_tiering, glacier, or deep_archive; the default is standard.

You may set website-redirect-location object metadata by setting website_redirect_location to either another object name in the same bucket, or to an external URL.

put_filename

# upload a file
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
);
$object->put_filename('hat.jpg');

# upload a file if you already know its md5_hex and size
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  content_type => 'image/jpeg',
  etag         => $md5_hex,
  size         => $size,
);
$object->put_filename('hat.jpg');

You may also set Content-Encoding using content_encoding, and Content-Disposition using content_disposition.

You may specify the S3 storage class by setting storage_class to either standard, reduced_redundancy, standard_ia, onezone_ia, intelligent_tiering, glacier, or deep_archive; the default is standard.

You may set website-redirect-location object metadata by setting website_redirect_location to either another object name in the same bucket, or to an external URL.

User metadata may be set by providing a non-empty hashref as user_metadata.

query_string_authentication_uri

# use query string authentication, forcing download with custom filename
my $object = $bucket->object(
  key          => 'images/my_hat.jpg',
  expires      => '2009-03-01',
);
my $uri = $object->query_string_authentication_uri({
  'response-content-disposition' => 'attachment; filename=abc.doc',
});

query_string_authentication_uri_for_method

my $uri = $object->query_string_authentication_uri_for_method ('PUT');

Similar to "query_string_authentication_uri" but creates presigned uri for specified HTTP method (Signature V4 uses also HTTP method).

Methods providee authenticated uri only for direct object operations.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html

size

# show the size of an existing object (if fetched by listing
# a bucket)
print $object->size . "\n";

uri

# return the URI of a publically-accessible object
my $uri = $object->uri;

initiate_multipart_upload

#initiate a new multipart upload for this object
my $object = $bucket->object(
	key         => 'massive_video.avi',
	acl         => ...,
);
my $upload_id = $object->initiate_multipart_upload;

For description of acl refer Net::Amazon::S3::ACL.

put_part

#add a part to a multipart upload
my $put_part_response = $object->put_part(
   upload_id      => $upload_id,
   part_number    => 1,
   value          => $chunk_content,
);
my $part_etag = $put_part_response->header('ETag')

Returns an L<HTTP::Response> object. It is necessary to keep the ETags for
each part, as these are required to complete the upload.

complete_multipart_upload

#complete a multipart upload
$object->complete_multipart_upload(
  upload_id       => $upload_id,
  etags           => [$etag_1, $etag_2],
  part_numbers    => [$part_number_1, $part_number2],
);

The etag and part_numbers parameters are ordered lists specifying the part
numbers and ETags for each individual part of the multipart upload.

user_metadata

my $object = $bucket->object(key => $key);
my $content = $object->get; # or use $object->get_filename($filename)

# return the user metadata downloaded, as a hashref
my $user_metadata = $object->user_metadata;

To upload an object with user metadata, set user_metadata at construction time to a hashref, with no x-amz-meta- prefixes on the key names. When downloading an object, the get, get_decoded and get_filename ethods set the contents of user_metadata to the same format.

add_tags

$object->add_tags (
	tags        => { tag1 => 'val1', tag2 => 'val2' },
);

$object->add_tags (
	tags        => { tag1 => 'val1', tag2 => 'val2' },
	version_id  => $version_id,
);

delete_tags

$object->delete_tags;

$object->delete_tags (
	version_id  => $version_id,
);

AUTHOR

Branislav Zahradník <barney@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Amazon Digital Services, Leon Brocard, Brad Fitzpatrick, Pedro Figueiredo, Rusty Conover, Branislav Zahradník.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.