---
name: "Net::Amazon::S3::Client::Object"
section: "3pm"
platform: "linux"
package: "libnet-amazon-s3-perl"
version: "0.991-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Net::Amazon::S3::Client::Object"
---

# Net::Amazon::S3::Client::Object(3pm)

An easy-to-use 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;
```

### head

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