GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::Amazon::S3::Client::Object(3) User Contributed Perl Documentation Net::Amazon::S3::Client::Object(3)

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

version 0.99

  # 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');

This module represents objects in buckets.

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

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

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

  # to delete an object
  $object->delete;

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

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

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

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

  # 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;

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

  # 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 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.

  # 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".

  # 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',
  });

        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>

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

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

        #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".

  #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 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.

  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.

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

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

        $object->delete_tags;

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

Branislav Zahradník <barney@cpan.org>

This software is copyright (c) 2021 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.

2021-12-05 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.