Class: Aws::S3::Client

Inherits:
Seahorse::Client::Base
  • Object
show all
Includes:
ClientStubs
Defined in:
lib/aws-sdk-s3/client.rb

Class Attribute Summary collapse

API Operations collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Client

Returns a new instance of Client.

Parameters:

  • options (Hash) —

    a customizable set of options



196
197
198
 
# File 'lib/aws-sdk-s3/client.rb', line 196

def initialize(*args)
  super
end

Class Attribute Details

.identifier ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



6229
6230
6231
 
# File 'lib/aws-sdk-s3/client.rb', line 6229

def identifier
  @identifier
end

Class Method Details

.errors_module ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



6232
6233
6234
 
# File 'lib/aws-sdk-s3/client.rb', line 6232

def errors_module
  Errors
end

Instance Method Details

#abort_multipart_upload(params = {}) ⇒ Types::AbortMultipartUploadOutput

Aborts a multipart upload.

To verify that all parts have been removed, so you don’t get charged for the part storage, you should call the List Parts operation and ensure the parts list is empty.

Examples:

Example: To abort a multipart upload


# The following example aborts a multipart upload.

resp = client.abort_multipart_upload({
  bucket: "examplebucket", 
  key: "bigobject", 
  upload_id: "xadcOB_7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--", 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.abort_multipart_upload({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  upload_id: "MultipartUploadId", # required
  request_payer: "requester", # accepts requester
})

Response structure


resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :upload_id (required, String)
  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



257
258
259
260
 
# File 'lib/aws-sdk-s3/client.rb', line 257

def abort_multipart_upload(params = {}, options = {})
  req = build_request(:abort_multipart_upload, params)
  req.send_request(options)
end

#build_request(operation_name, params = {}) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • params ({}) (defaults to: {}) 


6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
 
# File 'lib/aws-sdk-s3/client.rb', line 6088

def build_request(operation_name, params = {})
  handlers = @handlers.for(operation_name)
  context = Seahorse::Client::RequestContext.new(
    operation_name: operation_name,
    operation: config.api.operation(operation_name),
    client: self,
    params: params,
    config: config)
  context[:gem_name] = 'aws-sdk-s3'
  context[:gem_version] = '1.9.0'
  Seahorse::Client::Request.new(handlers, context)
end

#complete_multipart_upload(params = {}) ⇒ Types::CompleteMultipartUploadOutput

Completes a multipart upload by assembling previously uploaded parts.

Examples:

Example: To complete multipart upload


# The following example completes a multipart upload.

resp = client.complete_multipart_upload({
  bucket: "examplebucket", 
  key: "bigobject", 
  multipart_upload: {
    parts: [
      {
        etag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"", 
        part_number: 1, 
      }, 
      {
        etag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"", 
        part_number: 2, 
      }, 
    ], 
  }, 
  upload_id: "7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--", 
})

resp.to_h outputs the following:
{
  bucket: "acexamplebucket", 
  etag: "\"4d9031c7644d8081c2829f4ea23c55f7-2\"", 
  key: "bigobject", 
  location: "https://examplebucket.s3.amazonaws.com/bigobject", 
}

Request syntax with placeholder values


resp = client.complete_multipart_upload({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  multipart_upload: {
    parts: [
      {
        etag: "ETag",
        part_number: 1,
      },
    ],
  },
  upload_id: "MultipartUploadId", # required
  request_payer: "requester", # accepts requester
})

Response structure


resp.location #=> String
resp.bucket #=> String
resp.key #=> String
resp.expiration #=> String
resp.etag #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.version_id #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

See Also:



355
356
357
358
 
# File 'lib/aws-sdk-s3/client.rb', line 355

def complete_multipart_upload(params = {}, options = {})
  req = build_request(:complete_multipart_upload, params)
  req.send_request(options)
end

#copy_object(params = {}) ⇒ Types::CopyObjectOutput

Creates a copy of an object that is already stored in Amazon S3.

Examples:

Example: To copy an object


# The following example copies an object from one bucket to another.

resp = client.copy_object({
  bucket: "destinationbucket", 
  copy_source: "/sourcebucket/HappyFacejpg", 
  key: "HappyFaceCopyjpg", 
})

resp.to_h outputs the following:
{
  copy_object_result: {
    etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
    last_modified: Time.parse("2016-12-15T17:38:53.000Z"), 
  }, 
}

Request syntax with placeholder values


resp = client.copy_object({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  bucket: "BucketName", # required
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_type: "ContentType",
  copy_source: "CopySource", # required
  copy_source_if_match: "CopySourceIfMatch",
  copy_source_if_modified_since: Time.now,
  copy_source_if_none_match: "CopySourceIfNoneMatch",
  copy_source_if_unmodified_since: Time.now,
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  key: "ObjectKey", # required
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  metadata_directive: "COPY", # accepts COPY, REPLACE
  tagging_directive: "COPY", # accepts COPY, REPLACE
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  copy_source_sse_customer_algorithm: "CopySourceSSECustomerAlgorithm",
  copy_source_sse_customer_key: "CopySourceSSECustomerKey",
  copy_source_sse_customer_key_md5: "CopySourceSSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
})

Response structure


resp.copy_object_result.etag #=> String
resp.copy_object_result.last_modified #=> Time
resp.expiration #=> String
resp.copy_source_version_id #=> String
resp.version_id #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :bucket (required, String)
  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :copy_source (required, String) —

    The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.

  • :copy_source_if_match (String) —

    Copies the object if its entity tag (ETag) matches the specified tag.

  • :copy_source_if_modified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it has been modified since the specified time.

  • :copy_source_if_none_match (String) —

    Copies the object if its entity tag (ETag) is different than the specified ETag.

  • :copy_source_if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it hasn’t been modified since the specified time.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :key (required, String)
  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :metadata_directive (String) —

    Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.

  • :tagging_directive (String) —

    Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :copy_source_sse_customer_algorithm (String) —

    Specifies the algorithm to use when decrypting the source object (e.g., AES256).

  • :copy_source_sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.

  • :copy_source_sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object destination object this value must be used in conjunction with the TaggingDirective. The tag-set must be encoded as URL Query parameters

Returns:

See Also:



580
581
582
583
 
# File 'lib/aws-sdk-s3/client.rb', line 580

def copy_object(params = {}, options = {})
  req = build_request(:copy_object, params)
  req.send_request(options)
end

#create_bucket(params = {}) ⇒ Types::CreateBucketOutput

Creates a new bucket.

Examples:

Example: To create a bucket in a specific region


# The following example creates a bucket. The request specifies an AWS region where to create the bucket.

resp = client.create_bucket({
  bucket: "examplebucket", 
  create_bucket_configuration: {
    location_constraint: "eu-west-1", 
  }, 
})

resp.to_h outputs the following:
{
  location: "http://examplebucket.s3.amazonaws.com/", 
}

Example: To create a bucket


# The following example creates a bucket.

resp = client.create_bucket({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  location: "/examplebucket", 
}

Request syntax with placeholder values


resp = client.create_bucket({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read
  bucket: "BucketName", # required
  create_bucket_configuration: {
    location_constraint: "EU", # accepts EU, eu-west-1, us-west-1, us-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, sa-east-1, cn-north-1, eu-central-1
  },
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write: "GrantWrite",
  grant_write_acp: "GrantWriteACP",
})

Response structure


resp.location #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the bucket.

  • :bucket (required, String)
  • :create_bucket_configuration (Types::CreateBucketConfiguration)
  • :grant_full_control (String) —

    Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.

  • :grant_read (String) —

    Allows grantee to list the objects in the bucket.

  • :grant_read_acp (String) —

    Allows grantee to read the bucket ACL.

  • :grant_write (String) —

    Allows grantee to create, overwrite, and delete any object in the bucket.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable bucket.

Returns:

See Also:



668
669
670
671
 
# File 'lib/aws-sdk-s3/client.rb', line 668

def create_bucket(params = {}, options = {})
  req = build_request(:create_bucket, params)
  req.send_request(options)
end

#create_multipart_upload(params = {}) ⇒ Types::CreateMultipartUploadOutput

Initiates a multipart upload and returns an upload ID.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Examples:

Example: To initiate a multipart upload


# The following example initiates a multipart upload.

resp = client.create_multipart_upload({
  bucket: "examplebucket", 
  key: "largeobject", 
})

resp.to_h outputs the following:
{
  bucket: "examplebucket", 
  key: "largeobject", 
  upload_id: "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--", 
}

Request syntax with placeholder values


resp = client.create_multipart_upload({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  bucket: "BucketName", # required
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_type: "ContentType",
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  key: "ObjectKey", # required
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
})

Response structure


resp.abort_date #=> Time
resp.abort_rule_id #=> String
resp.bucket #=> String
resp.key #=> String
resp.upload_id #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :bucket (required, String)
  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :key (required, String)
  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object. The tag-set must be encoded as URL Query parameters

Returns:

See Also:



847
848
849
850
 
# File 'lib/aws-sdk-s3/client.rb', line 847

def create_multipart_upload(params = {}, options = {})
  req = build_request(:create_multipart_upload, params)
  req.send_request(options)
end

#delete_bucket(params = {}) ⇒ Struct

Deletes the bucket. All objects (including all object versions and Delete Markers) in the bucket must be deleted before the bucket itself can be deleted.

Examples:

Example: To delete a bucket


# The following example deletes the specified bucket.

resp = client.delete_bucket({
  bucket: "forrandall2", 
})

Request syntax with placeholder values


resp = client.delete_bucket({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



879
880
881
882
 
# File 'lib/aws-sdk-s3/client.rb', line 879

def delete_bucket(params = {}, options = {})
  req = build_request(:delete_bucket, params)
  req.send_request(options)
end

#delete_bucket_analytics_configuration(params = {}) ⇒ Struct

Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).

Examples:

Request syntax with placeholder values


resp = client.delete_bucket_analytics_configuration({
  bucket: "BucketName", # required
  id: "AnalyticsId", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket from which an analytics configuration is deleted.

  • :id (required, String) —

    The identifier used to represent an analytics configuration.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



907
908
909
910
 
# File 'lib/aws-sdk-s3/client.rb', line 907

def delete_bucket_analytics_configuration(params = {}, options = {})
  req = build_request(:delete_bucket_analytics_configuration, params)
  req.send_request(options)
end

#delete_bucket_cors(params = {}) ⇒ Struct

Deletes the cors configuration information set for the bucket.

Examples:

Example: To delete cors configuration on a bucket.


# The following example deletes CORS configuration on a bucket.

resp = client.delete_bucket_cors({
  bucket: "examplebucket", 
})

Request syntax with placeholder values


resp = client.delete_bucket_cors({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



937
938
939
940
 
# File 'lib/aws-sdk-s3/client.rb', line 937

def delete_bucket_cors(params = {}, options = {})
  req = build_request(:delete_bucket_cors, params)
  req.send_request(options)
end

#delete_bucket_encryption(params = {}) ⇒ Struct

Deletes the server-side encryption configuration from the bucket.

Examples:

Request syntax with placeholder values


resp = client.delete_bucket_encryption({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the server-side encryption configuration to delete.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



960
961
962
963
 
# File 'lib/aws-sdk-s3/client.rb', line 960

def delete_bucket_encryption(params = {}, options = {})
  req = build_request(:delete_bucket_encryption, params)
  req.send_request(options)
end

#delete_bucket_inventory_configuration(params = {}) ⇒ Struct

Deletes an inventory configuration (identified by the inventory ID) from the bucket.

Examples:

Request syntax with placeholder values


resp = client.delete_bucket_inventory_configuration({
  bucket: "BucketName", # required
  id: "InventoryId", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the inventory configuration to delete.

  • :id (required, String) —

    The ID used to identify the inventory configuration.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



988
989
990
991
 
# File 'lib/aws-sdk-s3/client.rb', line 988

def delete_bucket_inventory_configuration(params = {}, options = {})
  req = build_request(:delete_bucket_inventory_configuration, params)
  req.send_request(options)
end

#delete_bucket_lifecycle(params = {}) ⇒ Struct

Deletes the lifecycle configuration from the bucket.

Examples:

Example: To delete lifecycle configuration on a bucket.


# The following example deletes lifecycle configuration on a bucket.

resp = client.delete_bucket_lifecycle({
  bucket: "examplebucket", 
})

Request syntax with placeholder values


resp = client.delete_bucket_lifecycle({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1018
1019
1020
1021
 
# File 'lib/aws-sdk-s3/client.rb', line 1018

def delete_bucket_lifecycle(params = {}, options = {})
  req = build_request(:delete_bucket_lifecycle, params)
  req.send_request(options)
end

#delete_bucket_metrics_configuration(params = {}) ⇒ Struct

Deletes a metrics configuration (specified by the metrics configuration ID) from the bucket.

Examples:

Request syntax with placeholder values


resp = client.delete_bucket_metrics_configuration({
  bucket: "BucketName", # required
  id: "MetricsId", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the metrics configuration to delete.

  • :id (required, String) —

    The ID used to identify the metrics configuration.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1045
1046
1047
1048
 
# File 'lib/aws-sdk-s3/client.rb', line 1045

def delete_bucket_metrics_configuration(params = {}, options = {})
  req = build_request(:delete_bucket_metrics_configuration, params)
  req.send_request(options)
end

#delete_bucket_policy(params = {}) ⇒ Struct

Deletes the policy from the bucket.

Examples:

Example: To delete bucket policy


# The following example deletes bucket policy on the specified bucket.

resp = client.delete_bucket_policy({
  bucket: "examplebucket", 
})

Request syntax with placeholder values


resp = client.delete_bucket_policy({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1075
1076
1077
1078
 
# File 'lib/aws-sdk-s3/client.rb', line 1075

def delete_bucket_policy(params = {}, options = {})
  req = build_request(:delete_bucket_policy, params)
  req.send_request(options)
end

#delete_bucket_replication(params = {}) ⇒ Struct

Deletes the replication configuration from the bucket.

Examples:

Example: To delete bucket replication configuration


# The following example deletes replication configuration set on bucket.

resp = client.delete_bucket_replication({
  bucket: "example", 
})

Request syntax with placeholder values


resp = client.delete_bucket_replication({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1105
1106
1107
1108
 
# File 'lib/aws-sdk-s3/client.rb', line 1105

def delete_bucket_replication(params = {}, options = {})
  req = build_request(:delete_bucket_replication, params)
  req.send_request(options)
end

#delete_bucket_tagging(params = {}) ⇒ Struct

Deletes the tags from the bucket.

Examples:

Example: To delete bucket tags


# The following example deletes bucket tags.

resp = client.delete_bucket_tagging({
  bucket: "examplebucket", 
})

Request syntax with placeholder values


resp = client.delete_bucket_tagging({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1135
1136
1137
1138
 
# File 'lib/aws-sdk-s3/client.rb', line 1135

def delete_bucket_tagging(params = {}, options = {})
  req = build_request(:delete_bucket_tagging, params)
  req.send_request(options)
end

#delete_bucket_website(params = {}) ⇒ Struct

This operation removes the website configuration from the bucket.

Examples:

Example: To delete bucket website configuration


# The following example deletes bucket website configuration.

resp = client.delete_bucket_website({
  bucket: "examplebucket", 
})

Request syntax with placeholder values


resp = client.delete_bucket_website({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



1165
1166
1167
1168
 
# File 'lib/aws-sdk-s3/client.rb', line 1165

def delete_bucket_website(params = {}, options = {})
  req = build_request(:delete_bucket_website, params)
  req.send_request(options)
end

#delete_object(params = {}) ⇒ Types::DeleteObjectOutput

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn’t a null version, Amazon S3 does not remove any objects.

Examples:

Example: To delete an object (from a non-versioned bucket)


# The following example deletes an object from a non-versioned bucket.

resp = client.delete_object({
  bucket: "ExampleBucket", 
  key: "HappyFace.jpg", 
})

Example: To delete an object


# The following example deletes an object from an S3 bucket.

resp = client.delete_object({
  bucket: "examplebucket", 
  key: "objectkey.jpg", 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.delete_object({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  mfa: "MFA",
  version_id: "ObjectVersionId",
  request_payer: "requester", # accepts requester
})

Response structure


resp.delete_marker #=> Boolean
resp.version_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :mfa (String) —

    The concatenation of the authentication device’s serial number, a space, and the value that is displayed on your authentication device.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



1241
1242
1243
1244
 
# File 'lib/aws-sdk-s3/client.rb', line 1241

def delete_object(params = {}, options = {})
  req = build_request(:delete_object, params)
  req.send_request(options)
end

#delete_object_tagging(params = {}) ⇒ Types::DeleteObjectTaggingOutput

Removes the tag-set from an existing object.

Examples:

Example: To remove tag set from an object version


# The following example removes tag set associated with the specified object version. The request specifies both the
# object key and object version.

resp = client.delete_object_tagging({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
  version_id: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", 
})

resp.to_h outputs the following:
{
  version_id: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", 
}

Example: To remove tag set from an object


# The following example removes tag set associated with the specified object. If the bucket is versioning enabled, the
# operation removes tag set from the latest object version.

resp = client.delete_object_tagging({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  version_id: "null", 
}

Request syntax with placeholder values


resp = client.delete_object_tagging({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  version_id: "ObjectVersionId",
})

Response structure


resp.version_id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :version_id (String) —

    The versionId of the object that the tag-set will be removed from.

Returns:

See Also:



1307
1308
1309
1310
 
# File 'lib/aws-sdk-s3/client.rb', line 1307

def delete_object_tagging(params = {}, options = {})
  req = build_request(:delete_object_tagging, params)
  req.send_request(options)
end

#delete_objects(params = {}) ⇒ Types::DeleteObjectsOutput

This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.

Examples:

Example: To delete multiple object versions from a versioned bucket


# The following example deletes objects from a bucket. The request specifies object versions. S3 deletes specific object
# versions and returns the key and versions of deleted objects in the response.

resp = client.delete_objects({
  bucket: "examplebucket", 
  delete: {
    objects: [
      {
        key: "HappyFace.jpg", 
        version_id: "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b", 
      }, 
      {
        key: "HappyFace.jpg", 
        version_id: "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd", 
      }, 
    ], 
    quiet: false, 
  }, 
})

resp.to_h outputs the following:
{
  deleted: [
    {
      key: "HappyFace.jpg", 
      version_id: "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd", 
    }, 
    {
      key: "HappyFace.jpg", 
      version_id: "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b", 
    }, 
  ], 
}

Example: To delete multiple objects from a versioned bucket


# The following example deletes objects from a bucket. The bucket is versioned, and the request does not specify the
# object version to delete. In this case, all versions remain in the bucket and S3 adds a delete marker.

resp = client.delete_objects({
  bucket: "examplebucket", 
  delete: {
    objects: [
      {
        key: "objectkey1", 
      }, 
      {
        key: "objectkey2", 
      }, 
    ], 
    quiet: false, 
  }, 
})

resp.to_h outputs the following:
{
  deleted: [
    {
      delete_marker: true, 
      delete_marker_version_id: "A._w1z6EFiCF5uhtQMDal9JDkID9tQ7F", 
      key: "objectkey1", 
    }, 
    {
      delete_marker: true, 
      delete_marker_version_id: "iOd_ORxhkKe_e8G8_oSGxt2PjsCZKlkt", 
      key: "objectkey2", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.delete_objects({
  bucket: "BucketName", # required
  delete: { # required
    objects: [ # required
      {
        key: "ObjectKey", # required
        version_id: "ObjectVersionId",
      },
    ],
    quiet: false,
  },
  mfa: "MFA",
  request_payer: "requester", # accepts requester
})

Response structure


resp.deleted #=> Array
resp.deleted[0].key #=> String
resp.deleted[0].version_id #=> String
resp.deleted[0].delete_marker #=> Boolean
resp.deleted[0].delete_marker_version_id #=> String
resp.request_charged #=> String, one of "requester"
resp.errors #=> Array
resp.errors[0].key #=> String
resp.errors[0].version_id #=> String
resp.errors[0].code #=> String
resp.errors[0].message #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :delete (required, Types::Delete)
  • :mfa (String) —

    The concatenation of the authentication device’s serial number, a space, and the value that is displayed on your authentication device.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



1444
1445
1446
1447
 
# File 'lib/aws-sdk-s3/client.rb', line 1444

def delete_objects(params = {}, options = {})
  req = build_request(:delete_objects, params)
  req.send_request(options)
end

#get_bucket_accelerate_configuration(params = {}) ⇒ Types::GetBucketAccelerateConfigurationOutput

Returns the accelerate configuration of a bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_accelerate_configuration({
  bucket: "BucketName", # required
})

Response structure


resp.status #=> String, one of "Enabled", "Suspended"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    Name of the bucket for which the accelerate configuration is retrieved.

Returns:

See Also:



1473
1474
1475
1476
 
# File 'lib/aws-sdk-s3/client.rb', line 1473

def get_bucket_accelerate_configuration(params = {}, options = {})
  req = build_request(:get_bucket_accelerate_configuration, params)
  req.send_request(options)
end

#get_bucket_acl(params = {}) ⇒ Types::GetBucketAclOutput

Gets the access control policy for the bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_acl({
  bucket: "BucketName", # required
})

Response structure


resp.owner.display_name #=> String
resp.owner.id #=> String
resp.grants #=> Array
resp.grants[0].grantee.display_name #=> String
resp.grants[0].grantee.email_address #=> String
resp.grants[0].grantee.id #=> String
resp.grants[0].grantee.type #=> String, one of "CanonicalUser", "AmazonCustomerByEmail", "Group"
resp.grants[0].grantee.uri #=> String
resp.grants[0].permission #=> String, one of "FULL_CONTROL", "WRITE", "WRITE_ACP", "READ", "READ_ACP"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1509
1510
1511
1512
 
# File 'lib/aws-sdk-s3/client.rb', line 1509

def get_bucket_acl(params = {}, options = {})
  req = build_request(:get_bucket_acl, params)
  req.send_request(options)
end

#get_bucket_analytics_configuration(params = {}) ⇒ Types::GetBucketAnalyticsConfigurationOutput

Gets an analytics configuration for the bucket (specified by the analytics configuration ID).

Examples:

Request syntax with placeholder values


resp = client.get_bucket_analytics_configuration({
  bucket: "BucketName", # required
  id: "AnalyticsId", # required
})

Response structure


resp.analytics_configuration.id #=> String
resp.analytics_configuration.filter.prefix #=> String
resp.analytics_configuration.filter.tag.key #=> String
resp.analytics_configuration.filter.tag.value #=> String
resp.analytics_configuration.filter.and.prefix #=> String
resp.analytics_configuration.filter.and.tags #=> Array
resp.analytics_configuration.filter.and.tags[0].key #=> String
resp.analytics_configuration.filter.and.tags[0].value #=> String
resp.analytics_configuration.storage_class_analysis.data_export.output_schema_version #=> String, one of "V_1"
resp.analytics_configuration.storage_class_analysis.data_export.destination.s3_bucket_destination.format #=> String, one of "CSV"
resp.analytics_configuration.storage_class_analysis.data_export.destination.s3_bucket_destination. #=> String
resp.analytics_configuration.storage_class_analysis.data_export.destination.s3_bucket_destination.bucket #=> String
resp.analytics_configuration.storage_class_analysis.data_export.destination.s3_bucket_destination.prefix #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket from which an analytics configuration is retrieved.

  • :id (required, String) —

    The identifier used to represent an analytics configuration.

Returns:

See Also:



1555
1556
1557
1558
 
# File 'lib/aws-sdk-s3/client.rb', line 1555

def get_bucket_analytics_configuration(params = {}, options = {})
  req = build_request(:get_bucket_analytics_configuration, params)
  req.send_request(options)
end

#get_bucket_cors(params = {}) ⇒ Types::GetBucketCorsOutput

Returns the cors configuration for the bucket.

Examples:

Example: To get cors configuration set on a bucket


# The following example returns cross-origin resource sharing (CORS) configuration set on a bucket.

resp = client.get_bucket_cors({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  cors_rules: [
    {
      allowed_headers: [
        "Authorization", 
      ], 
      allowed_methods: [
        "GET", 
      ], 
      allowed_origins: [
        "*", 
      ], 
      max_age_seconds: 3000, 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.get_bucket_cors({
  bucket: "BucketName", # required
})

Response structure


resp.cors_rules #=> Array
resp.cors_rules[0].allowed_headers #=> Array
resp.cors_rules[0].allowed_headers[0] #=> String
resp.cors_rules[0].allowed_methods #=> Array
resp.cors_rules[0].allowed_methods[0] #=> String
resp.cors_rules[0].allowed_origins #=> Array
resp.cors_rules[0].allowed_origins[0] #=> String
resp.cors_rules[0].expose_headers #=> Array
resp.cors_rules[0].expose_headers[0] #=> String
resp.cors_rules[0].max_age_seconds #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1618
1619
1620
1621
 
# File 'lib/aws-sdk-s3/client.rb', line 1618

def get_bucket_cors(params = {}, options = {})
  req = build_request(:get_bucket_cors, params)
  req.send_request(options)
end

#get_bucket_encryption(params = {}) ⇒ Types::GetBucketEncryptionOutput

Returns the server-side encryption configuration of a bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_encryption({
  bucket: "BucketName", # required
})

Response structure


resp.server_side_encryption_configuration.rules #=> Array
resp.server_side_encryption_configuration.rules[0].apply_server_side_encryption_by_default.sse_algorithm #=> String, one of "AES256", "aws:kms"
resp.server_side_encryption_configuration.rules[0].apply_server_side_encryption_by_default.kms_master_key_id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket from which the server-side encryption configuration is retrieved.

Returns:

See Also:



1649
1650
1651
1652
 
# File 'lib/aws-sdk-s3/client.rb', line 1649

def get_bucket_encryption(params = {}, options = {})
  req = build_request(:get_bucket_encryption, params)
  req.send_request(options)
end

#get_bucket_inventory_configuration(params = {}) ⇒ Types::GetBucketInventoryConfigurationOutput

Returns an inventory configuration (identified by the inventory ID) from the bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_inventory_configuration({
  bucket: "BucketName", # required
  id: "InventoryId", # required
})

Response structure


resp.inventory_configuration.destination.s3_bucket_destination. #=> String
resp.inventory_configuration.destination.s3_bucket_destination.bucket #=> String
resp.inventory_configuration.destination.s3_bucket_destination.format #=> String, one of "CSV", "ORC"
resp.inventory_configuration.destination.s3_bucket_destination.prefix #=> String
resp.inventory_configuration.destination.s3_bucket_destination.encryption.ssekms.key_id #=> String
resp.inventory_configuration.is_enabled #=> Boolean
resp.inventory_configuration.filter.prefix #=> String
resp.inventory_configuration.id #=> String
resp.inventory_configuration.included_object_versions #=> String, one of "All", "Current"
resp.inventory_configuration.optional_fields #=> Array
resp.inventory_configuration.optional_fields[0] #=> String, one of "Size", "LastModifiedDate", "StorageClass", "ETag", "IsMultipartUploaded", "ReplicationStatus", "EncryptionStatus"
resp.inventory_configuration.schedule.frequency #=> String, one of "Daily", "Weekly"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the inventory configuration to retrieve.

  • :id (required, String) —

    The ID used to identify the inventory configuration.

Returns:

See Also:



1694
1695
1696
1697
 
# File 'lib/aws-sdk-s3/client.rb', line 1694

def get_bucket_inventory_configuration(params = {}, options = {})
  req = build_request(:get_bucket_inventory_configuration, params)
  req.send_request(options)
end

#get_bucket_lifecycle(params = {}) ⇒ Types::GetBucketLifecycleOutput

Deprecated, see the GetBucketLifecycleConfiguration operation.

Examples:

Example: To get a bucket acl


# The following example gets ACL on the specified bucket.

resp = client.get_bucket_lifecycle({
  bucket: "acl1", 
})

resp.to_h outputs the following:
{
  rules: [
    {
      expiration: {
        days: 1, 
      }, 
      id: "delete logs", 
      prefix: "123/", 
      status: "Enabled", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.get_bucket_lifecycle({
  bucket: "BucketName", # required
})

Response structure


resp.rules #=> Array
resp.rules[0].expiration.date #=> Time
resp.rules[0].expiration.days #=> Integer
resp.rules[0].expiration.expired_object_delete_marker #=> Boolean
resp.rules[0].id #=> String
resp.rules[0].prefix #=> String
resp.rules[0].status #=> String, one of "Enabled", "Disabled"
resp.rules[0].transition.date #=> Time
resp.rules[0].transition.days #=> Integer
resp.rules[0].transition.storage_class #=> String, one of "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.rules[0].noncurrent_version_transition.noncurrent_days #=> Integer
resp.rules[0].noncurrent_version_transition.storage_class #=> String, one of "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.rules[0].noncurrent_version_expiration.noncurrent_days #=> Integer
resp.rules[0].abort_incomplete_multipart_upload.days_after_initiation #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1757
1758
1759
1760
 
# File 'lib/aws-sdk-s3/client.rb', line 1757

def get_bucket_lifecycle(params = {}, options = {})
  req = build_request(:get_bucket_lifecycle, params)
  req.send_request(options)
end

#get_bucket_lifecycle_configuration(params = {}) ⇒ Types::GetBucketLifecycleConfigurationOutput

Returns the lifecycle configuration information set on the bucket.

Examples:

Example: To get lifecycle configuration on a bucket


# The following example retrieves lifecycle configuration on set on a bucket. 

resp = client.get_bucket_lifecycle_configuration({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  rules: [
    {
      id: "Rule for TaxDocs/", 
      prefix: "TaxDocs", 
      status: "Enabled", 
      transitions: [
        {
          days: 365, 
          storage_class: "STANDARD_IA", 
        }, 
      ], 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.get_bucket_lifecycle_configuration({
  bucket: "BucketName", # required
})

Response structure


resp.rules #=> Array
resp.rules[0].expiration.date #=> Time
resp.rules[0].expiration.days #=> Integer
resp.rules[0].expiration.expired_object_delete_marker #=> Boolean
resp.rules[0].id #=> String
resp.rules[0].prefix #=> String
resp.rules[0].filter.prefix #=> String
resp.rules[0].filter.tag.key #=> String
resp.rules[0].filter.tag.value #=> String
resp.rules[0].filter.and.prefix #=> String
resp.rules[0].filter.and.tags #=> Array
resp.rules[0].filter.and.tags[0].key #=> String
resp.rules[0].filter.and.tags[0].value #=> String
resp.rules[0].status #=> String, one of "Enabled", "Disabled"
resp.rules[0].transitions #=> Array
resp.rules[0].transitions[0].date #=> Time
resp.rules[0].transitions[0].days #=> Integer
resp.rules[0].transitions[0].storage_class #=> String, one of "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.rules[0].noncurrent_version_transitions #=> Array
resp.rules[0].noncurrent_version_transitions[0].noncurrent_days #=> Integer
resp.rules[0].noncurrent_version_transitions[0].storage_class #=> String, one of "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.rules[0].noncurrent_version_expiration.noncurrent_days #=> Integer
resp.rules[0].abort_incomplete_multipart_upload.days_after_initiation #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1832
1833
1834
1835
 
# File 'lib/aws-sdk-s3/client.rb', line 1832

def get_bucket_lifecycle_configuration(params = {}, options = {})
  req = build_request(:get_bucket_lifecycle_configuration, params)
  req.send_request(options)
end

#get_bucket_location(params = {}) ⇒ Types::GetBucketLocationOutput

Returns the region the bucket resides in.

Examples:

Example: To get bucket location


# The following example returns bucket location.

resp = client.get_bucket_location({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  location_constraint: "us-west-2", 
}

Request syntax with placeholder values


resp = client.get_bucket_location({
  bucket: "BucketName", # required
})

Response structure


resp.location_constraint #=> String, one of "EU", "eu-west-1", "us-west-1", "us-west-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ap-northeast-1", "sa-east-1", "cn-north-1", "eu-central-1"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1873
1874
1875
1876
 
# File 'lib/aws-sdk-s3/client.rb', line 1873

def get_bucket_location(params = {}, options = {})
  req = build_request(:get_bucket_location, params)
  req.send_request(options)
end

#get_bucket_logging(params = {}) ⇒ Types::GetBucketLoggingOutput

Returns the logging status of a bucket and the permissions users have to view and modify that status. To use GET, you must be the bucket owner.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_logging({
  bucket: "BucketName", # required
})

Response structure


resp.logging_enabled.target_bucket #=> String
resp.logging_enabled.target_grants #=> Array
resp.logging_enabled.target_grants[0].grantee.display_name #=> String
resp.logging_enabled.target_grants[0].grantee.email_address #=> String
resp.logging_enabled.target_grants[0].grantee.id #=> String
resp.logging_enabled.target_grants[0].grantee.type #=> String, one of "CanonicalUser", "AmazonCustomerByEmail", "Group"
resp.logging_enabled.target_grants[0].grantee.uri #=> String
resp.logging_enabled.target_grants[0].permission #=> String, one of "FULL_CONTROL", "READ", "WRITE"
resp.logging_enabled.target_prefix #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



1910
1911
1912
1913
 
# File 'lib/aws-sdk-s3/client.rb', line 1910

def get_bucket_logging(params = {}, options = {})
  req = build_request(:get_bucket_logging, params)
  req.send_request(options)
end

#get_bucket_metrics_configuration(params = {}) ⇒ Types::GetBucketMetricsConfigurationOutput

Gets a metrics configuration (specified by the metrics configuration ID) from the bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_metrics_configuration({
  bucket: "BucketName", # required
  id: "MetricsId", # required
})

Response structure


resp.metrics_configuration.id #=> String
resp.metrics_configuration.filter.prefix #=> String
resp.metrics_configuration.filter.tag.key #=> String
resp.metrics_configuration.filter.tag.value #=> String
resp.metrics_configuration.filter.and.prefix #=> String
resp.metrics_configuration.filter.and.tags #=> Array
resp.metrics_configuration.filter.and.tags[0].key #=> String
resp.metrics_configuration.filter.and.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the metrics configuration to retrieve.

  • :id (required, String) —

    The ID used to identify the metrics configuration.

Returns:

See Also:



1951
1952
1953
1954
 
# File 'lib/aws-sdk-s3/client.rb', line 1951

def get_bucket_metrics_configuration(params = {}, options = {})
  req = build_request(:get_bucket_metrics_configuration, params)
  req.send_request(options)
end

#get_bucket_notification(params = {}) ⇒ Types::NotificationConfigurationDeprecated

Deprecated, see the GetBucketNotificationConfiguration operation.

Examples:

Example: To get notification configuration set on a bucket


# The following example returns notification configuration set on a bucket.

resp = client.get_bucket_notification({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  queue_configuration: {
    event: "s3:ObjectCreated:Put", 
    events: [
      "s3:ObjectCreated:Put", 
    ], 
    id: "MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx", 
    queue: "arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue", 
  }, 
  topic_configuration: {
    event: "s3:ObjectCreated:Copy", 
    events: [
      "s3:ObjectCreated:Copy", 
    ], 
    id: "YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi", 
    topic: "arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic", 
  }, 
}

Example: To get notification configuration set on a bucket


# The following example returns notification configuration set on a bucket.

resp = client.get_bucket_notification({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  queue_configuration: {
    event: "s3:ObjectCreated:Put", 
    events: [
      "s3:ObjectCreated:Put", 
    ], 
    id: "MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx", 
    queue: "arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue", 
  }, 
  topic_configuration: {
    event: "s3:ObjectCreated:Copy", 
    events: [
      "s3:ObjectCreated:Copy", 
    ], 
    id: "YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi", 
    topic: "arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic", 
  }, 
}

Request syntax with placeholder values


resp = client.get_bucket_notification({
  bucket: "BucketName", # required
})

Response structure


resp.topic_configuration.id #=> String
resp.topic_configuration.events #=> Array
resp.topic_configuration.events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.topic_configuration.event #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.topic_configuration.topic #=> String
resp.queue_configuration.id #=> String
resp.queue_configuration.event #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.queue_configuration.events #=> Array
resp.queue_configuration.events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.queue_configuration.queue #=> String
resp.cloud_function_configuration.id #=> String
resp.cloud_function_configuration.event #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.cloud_function_configuration.events #=> Array
resp.cloud_function_configuration.events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.cloud_function_configuration.cloud_function #=> String
resp.cloud_function_configuration.invocation_role #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    Name of the bucket to get the notification configuration for.

Returns:

See Also:



2053
2054
2055
2056
 
# File 'lib/aws-sdk-s3/client.rb', line 2053

def get_bucket_notification(params = {}, options = {})
  req = build_request(:get_bucket_notification, params)
  req.send_request(options)
end

#get_bucket_notification_configuration(params = {}) ⇒ Types::NotificationConfiguration

Returns the notification configuration of a bucket.

Examples:

Request syntax with placeholder values


resp = client.get_bucket_notification_configuration({
  bucket: "BucketName", # required
})

Response structure


resp.topic_configurations #=> Array
resp.topic_configurations[0].id #=> String
resp.topic_configurations[0].topic_arn #=> String
resp.topic_configurations[0].events #=> Array
resp.topic_configurations[0].events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.topic_configurations[0].filter.key.filter_rules #=> Array
resp.topic_configurations[0].filter.key.filter_rules[0].name #=> String, one of "prefix", "suffix"
resp.topic_configurations[0].filter.key.filter_rules[0].value #=> String
resp.queue_configurations #=> Array
resp.queue_configurations[0].id #=> String
resp.queue_configurations[0].queue_arn #=> String
resp.queue_configurations[0].events #=> Array
resp.queue_configurations[0].events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.queue_configurations[0].filter.key.filter_rules #=> Array
resp.queue_configurations[0].filter.key.filter_rules[0].name #=> String, one of "prefix", "suffix"
resp.queue_configurations[0].filter.key.filter_rules[0].value #=> String
resp.lambda_function_configurations #=> Array
resp.lambda_function_configurations[0].id #=> String
resp.lambda_function_configurations[0].lambda_function_arn #=> String
resp.lambda_function_configurations[0].events #=> Array
resp.lambda_function_configurations[0].events[0] #=> String, one of "s3:ReducedRedundancyLostObject", "s3:ObjectCreated:*", "s3:ObjectCreated:Put", "s3:ObjectCreated:Post", "s3:ObjectCreated:Copy", "s3:ObjectCreated:CompleteMultipartUpload", "s3:ObjectRemoved:*", "s3:ObjectRemoved:Delete", "s3:ObjectRemoved:DeleteMarkerCreated"
resp.lambda_function_configurations[0].filter.key.filter_rules #=> Array
resp.lambda_function_configurations[0].filter.key.filter_rules[0].name #=> String, one of "prefix", "suffix"
resp.lambda_function_configurations[0].filter.key.filter_rules[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    Name of the bucket to get the notification configuration for.

Returns:

See Also:



2106
2107
2108
2109
 
# File 'lib/aws-sdk-s3/client.rb', line 2106

def get_bucket_notification_configuration(params = {}, options = {})
  req = build_request(:get_bucket_notification_configuration, params)
  req.send_request(options)
end

#get_bucket_policy(params = {}) ⇒ Types::GetBucketPolicyOutput

Returns the policy of a specified bucket.

Examples:

Example: To get bucket policy


# The following example returns bucket policy associated with a bucket.

resp = client.get_bucket_policy({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  policy: "{\"Version\":\"2008-10-17\",\"Id\":\"LogPolicy\",\"Statement\":[{\"Sid\":\"Enables the log delivery group to publish logs to your bucket \",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"111122223333\"},\"Action\":[\"s3:GetBucketAcl\",\"s3:GetObjectAcl\",\"s3:PutObject\"],\"Resource\":[\"arn:aws:s3:::policytest1/*\",\"arn:aws:s3:::policytest1\"]}]}", 
}

Request syntax with placeholder values


resp = client.get_bucket_policy({
  bucket: "BucketName", # required
})

Response structure


resp.policy #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2147
2148
2149
2150
 
# File 'lib/aws-sdk-s3/client.rb', line 2147

def get_bucket_policy(params = {}, options = {}, &block)
  req = build_request(:get_bucket_policy, params)
  req.send_request(options, &block)
end

#get_bucket_replication(params = {}) ⇒ Types::GetBucketReplicationOutput

Returns the replication configuration of a bucket.

Examples:

Example: To get replication configuration set on a bucket


# The following example returns replication configuration set on a bucket.

resp = client.get_bucket_replication({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  replication_configuration: {
    role: "arn:aws:iam::acct-id:role/example-role", 
    rules: [
      {
        destination: {
          bucket: "arn:aws:s3:::destination-bucket", 
        }, 
        id: "MWIwNTkwZmItMTE3MS00ZTc3LWJkZDEtNzRmODQwYzc1OTQy", 
        prefix: "Tax", 
        status: "Enabled", 
      }, 
    ], 
  }, 
}

Request syntax with placeholder values


resp = client.get_bucket_replication({
  bucket: "BucketName", # required
})

Response structure


resp.replication_configuration.role #=> String
resp.replication_configuration.rules #=> Array
resp.replication_configuration.rules[0].id #=> String
resp.replication_configuration.rules[0].prefix #=> String
resp.replication_configuration.rules[0].status #=> String, one of "Enabled", "Disabled"
resp.replication_configuration.rules[0].source_selection_criteria.sse_kms_encrypted_objects.status #=> String, one of "Enabled", "Disabled"
resp.replication_configuration.rules[0].destination.bucket #=> String
resp.replication_configuration.rules[0].destination. #=> String
resp.replication_configuration.rules[0].destination.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA"
resp.replication_configuration.rules[0].destination.access_control_translation.owner #=> String, one of "Destination"
resp.replication_configuration.rules[0].destination.encryption_configuration.replica_kms_key_id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2210
2211
2212
2213
 
# File 'lib/aws-sdk-s3/client.rb', line 2210

def get_bucket_replication(params = {}, options = {})
  req = build_request(:get_bucket_replication, params)
  req.send_request(options)
end

#get_bucket_request_payment(params = {}) ⇒ Types::GetBucketRequestPaymentOutput

Returns the request payment configuration of a bucket.

Examples:

Example: To get bucket versioning configuration


# The following example retrieves bucket versioning configuration.

resp = client.get_bucket_request_payment({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  payer: "BucketOwner", 
}

Request syntax with placeholder values


resp = client.get_bucket_request_payment({
  bucket: "BucketName", # required
})

Response structure


resp.payer #=> String, one of "Requester", "BucketOwner"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2251
2252
2253
2254
 
# File 'lib/aws-sdk-s3/client.rb', line 2251

def get_bucket_request_payment(params = {}, options = {})
  req = build_request(:get_bucket_request_payment, params)
  req.send_request(options)
end

#get_bucket_tagging(params = {}) ⇒ Types::GetBucketTaggingOutput

Returns the tag set associated with the bucket.

Examples:

Example: To get tag set associated with a bucket


# The following example returns tag set associated with a bucket

resp = client.get_bucket_tagging({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  tag_set: [
    {
      key: "key1", 
      value: "value1", 
    }, 
    {
      key: "key2", 
      value: "value2", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.get_bucket_tagging({
  bucket: "BucketName", # required
})

Response structure


resp.tag_set #=> Array
resp.tag_set[0].key #=> String
resp.tag_set[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2303
2304
2305
2306
 
# File 'lib/aws-sdk-s3/client.rb', line 2303

def get_bucket_tagging(params = {}, options = {})
  req = build_request(:get_bucket_tagging, params)
  req.send_request(options)
end

#get_bucket_versioning(params = {}) ⇒ Types::GetBucketVersioningOutput

Returns the versioning state of a bucket.

Examples:

Example: To get bucket versioning configuration


# The following example retrieves bucket versioning configuration.

resp = client.get_bucket_versioning({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  mfa_delete: "Disabled", 
  status: "Enabled", 
}

Request syntax with placeholder values


resp = client.get_bucket_versioning({
  bucket: "BucketName", # required
})

Response structure


resp.status #=> String, one of "Enabled", "Suspended"
resp.mfa_delete #=> String, one of "Enabled", "Disabled"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2347
2348
2349
2350
 
# File 'lib/aws-sdk-s3/client.rb', line 2347

def get_bucket_versioning(params = {}, options = {})
  req = build_request(:get_bucket_versioning, params)
  req.send_request(options)
end

#get_bucket_website(params = {}) ⇒ Types::GetBucketWebsiteOutput

Returns the website configuration for a bucket.

Examples:

Example: To get bucket website configuration


# The following example retrieves website configuration of a bucket.

resp = client.get_bucket_website({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  error_document: {
    key: "error.html", 
  }, 
  index_document: {
    suffix: "index.html", 
  }, 
}

Request syntax with placeholder values


resp = client.get_bucket_website({
  bucket: "BucketName", # required
})

Response structure


resp.redirect_all_requests_to.host_name #=> String
resp.redirect_all_requests_to.protocol #=> String, one of "http", "https"
resp.index_document.suffix #=> String
resp.error_document.key #=> String
resp.routing_rules #=> Array
resp.routing_rules[0].condition.http_error_code_returned_equals #=> String
resp.routing_rules[0].condition.key_prefix_equals #=> String
resp.routing_rules[0].redirect.host_name #=> String
resp.routing_rules[0].redirect.http_redirect_code #=> String
resp.routing_rules[0].redirect.protocol #=> String, one of "http", "https"
resp.routing_rules[0].redirect.replace_key_prefix_with #=> String
resp.routing_rules[0].redirect.replace_key_with #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

See Also:



2407
2408
2409
2410
 
# File 'lib/aws-sdk-s3/client.rb', line 2407

def get_bucket_website(params = {}, options = {})
  req = build_request(:get_bucket_website, params)
  req.send_request(options)
end

#get_object(params = {}) ⇒ Types::GetObjectOutput

Retrieves objects from Amazon S3.

Examples:

Example: To retrieve an object


# The following example retrieves an object for an S3 bucket.

resp = client.get_object({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  accept_ranges: "bytes", 
  content_length: 3191, 
  content_type: "image/jpeg", 
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  last_modified: Time.parse("Thu, 15 Dec 2016 01:19:41 GMT"), 
  metadata: {
  }, 
  tag_count: 2, 
  version_id: "null", 
}

Example: To retrieve a byte range of an object


# The following example retrieves an object for an S3 bucket. The request specifies the range header to retrieve a
# specific byte range.

resp = client.get_object({
  bucket: "examplebucket", 
  key: "SampleFile.txt", 
  range: "bytes=0-9", 
})

resp.to_h outputs the following:
{
  accept_ranges: "bytes", 
  content_length: 10, 
  content_range: "bytes 0-9/43", 
  content_type: "text/plain", 
  etag: "\"0d94420ffd0bc68cd3d152506b97a9cc\"", 
  last_modified: Time.parse("Thu, 09 Oct 2014 22:57:28 GMT"), 
  metadata: {
  }, 
  version_id: "null", 
}

Download an object to disk

# stream object directly to disk
resp = s3.get_object(
  response_target: '/path/to/file',
  bucket: 'bucket-name',
  key: 'object-key')

# you can still access other response data
resp.metadata #=> { ... }
resp.etag #=> "..."

Download object into memory

# omit :response_target to download to a StringIO in memory
resp = s3.get_object(bucket: 'bucket-name', key: 'object-key')

# call #read or #string on the response body
resp.body.read
#=> '...'

Streaming data to a block

# WARNING: yielding data to a block disables retries of networking errors
File.open('/path/to/file', 'wb') do |file|
  s3.get_object(bucket: 'bucket-name', key: 'object-key') do |chunk|
    file.write(chunk)
  end
end

Request syntax with placeholder values


resp = client.get_object({
  bucket: "BucketName", # required
  if_match: "IfMatch",
  if_modified_since: Time.now,
  if_none_match: "IfNoneMatch",
  if_unmodified_since: Time.now,
  key: "ObjectKey", # required
  range: "Range",
  response_cache_control: "ResponseCacheControl",
  response_content_disposition: "ResponseContentDisposition",
  response_content_encoding: "ResponseContentEncoding",
  response_content_language: "ResponseContentLanguage",
  response_content_type: "ResponseContentType",
  response_expires: Time.now,
  version_id: "ObjectVersionId",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  part_number: 1,
})

Response structure


resp.body #=> IO
resp.delete_marker #=> Boolean
resp.accept_ranges #=> String
resp.expiration #=> String
resp.restore #=> String
resp.last_modified #=> Time
resp.content_length #=> Integer
resp.etag #=> String
resp.missing_meta #=> Integer
resp.version_id #=> String
resp.cache_control #=> String
resp.content_disposition #=> String
resp.content_encoding #=> String
resp.content_language #=> String
resp.content_range #=> String
resp.content_type #=> String
resp.expires #=> Time
resp.expires_string #=> String
resp.website_redirect_location #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.metadata #=> Hash
resp.metadata["MetadataKey"] #=> String
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA"
resp.request_charged #=> String, one of "requester"
resp.replication_status #=> String, one of "COMPLETE", "PENDING", "FAILED", "REPLICA"
resp.parts_count #=> Integer
resp.tag_count #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :response_target (String, IO) —

    Where to write response data, file path, or IO object.

  • :bucket (required, String)
  • :if_match (String) —

    Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).

  • :if_modified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

  • :if_none_match (String) —

    Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).

  • :if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

  • :key (required, String)
  • :range (String) —

    Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

  • :response_cache_control (String) —

    Sets the Cache-Control header of the response.

  • :response_content_disposition (String) —

    Sets the Content-Disposition header of the response

  • :response_content_encoding (String) —

    Sets the Content-Encoding header of the response.

  • :response_content_language (String) —

    Sets the Content-Language header of the response.

  • :response_content_type (String) —

    Sets the Content-Type header of the response.

  • :response_expires (Time, DateTime, Date, Integer, String) —

    Sets the Expires header of the response.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :part_number (Integer) —

    Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a ‘ranged’ GET request for the part specified. Useful for downloading just a part of an object.

Returns:

See Also:



2659
2660
2661
2662
 
# File 'lib/aws-sdk-s3/client.rb', line 2659

def get_object(params = {}, options = {}, &block)
  req = build_request(:get_object, params)
  req.send_request(options, &block)
end

#get_object_acl(params = {}) ⇒ Types::GetObjectAclOutput

Returns the access control list (ACL) of an object.

Examples:

Example: To retrieve object ACL


# The following example retrieves access control list (ACL) of an object.

resp = client.get_object_acl({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  grants: [
    {
      grantee: {
        display_name: "owner-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
        type: "CanonicalUser", 
      }, 
      permission: "WRITE", 
    }, 
    {
      grantee: {
        display_name: "owner-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
        type: "CanonicalUser", 
      }, 
      permission: "WRITE_ACP", 
    }, 
    {
      grantee: {
        display_name: "owner-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
        type: "CanonicalUser", 
      }, 
      permission: "READ", 
    }, 
    {
      grantee: {
        display_name: "owner-display-name", 
        id: "852b113eexamplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
        type: "CanonicalUser", 
      }, 
      permission: "READ_ACP", 
    }, 
  ], 
  owner: {
    display_name: "owner-display-name", 
    id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
  }, 
}

Request syntax with placeholder values


resp = client.get_object_acl({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  version_id: "ObjectVersionId",
  request_payer: "requester", # accepts requester
})

Response structure


resp.owner.display_name #=> String
resp.owner.id #=> String
resp.grants #=> Array
resp.grants[0].grantee.display_name #=> String
resp.grants[0].grantee.email_address #=> String
resp.grants[0].grantee.id #=> String
resp.grants[0].grantee.type #=> String, one of "CanonicalUser", "AmazonCustomerByEmail", "Group"
resp.grants[0].grantee.uri #=> String
resp.grants[0].permission #=> String, one of "FULL_CONTROL", "WRITE", "WRITE_ACP", "READ", "READ_ACP"
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



2764
2765
2766
2767
 
# File 'lib/aws-sdk-s3/client.rb', line 2764

def get_object_acl(params = {}, options = {})
  req = build_request(:get_object_acl, params)
  req.send_request(options)
end

#get_object_tagging(params = {}) ⇒ Types::GetObjectTaggingOutput

Returns the tag-set of an object.

Examples:

Example: To retrieve tag set of an object


# The following example retrieves tag set of an object.

resp = client.get_object_tagging({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  tag_set: [
    {
      key: "Key4", 
      value: "Value4", 
    }, 
    {
      key: "Key3", 
      value: "Value3", 
    }, 
  ], 
  version_id: "null", 
}

Example: To retrieve tag set of a specific object version


# The following example retrieves tag set of an object. The request specifies object version.

resp = client.get_object_tagging({
  bucket: "examplebucket", 
  key: "exampleobject", 
  version_id: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", 
})

resp.to_h outputs the following:
{
  tag_set: [
    {
      key: "Key1", 
      value: "Value1", 
    }, 
  ], 
  version_id: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI", 
}

Request syntax with placeholder values


resp = client.get_object_tagging({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  version_id: "ObjectVersionId",
})

Response structure


resp.version_id #=> String
resp.tag_set #=> Array
resp.tag_set[0].key #=> String
resp.tag_set[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :version_id (String)

Returns:

See Also:



2847
2848
2849
2850
 
# File 'lib/aws-sdk-s3/client.rb', line 2847

def get_object_tagging(params = {}, options = {})
  req = build_request(:get_object_tagging, params)
  req.send_request(options)
end

#get_object_torrent(params = {}) ⇒ Types::GetObjectTorrentOutput

Return torrent files from a bucket.

Examples:

Example: To retrieve torrent files for an object


# The following example retrieves torrent files of an object.

resp = client.get_object_torrent({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.get_object_torrent({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  request_payer: "requester", # accepts requester
})

Response structure


resp.body #=> IO
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :response_target (String, IO) —

    Where to write response data, file path, or IO object.

  • :bucket (required, String)
  • :key (required, String)
  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



2904
2905
2906
2907
 
# File 'lib/aws-sdk-s3/client.rb', line 2904

def get_object_torrent(params = {}, options = {}, &block)
  req = build_request(:get_object_torrent, params)
  req.send_request(options, &block)
end

#head_bucket(params = {}) ⇒ Struct

This operation is useful to determine if a bucket exists and you have permission to access it.

Examples:

Example: To determine if bucket exists


# This operation checks to see if a bucket exists.

resp = client.head_bucket({
  bucket: "acl1", 
})

Request syntax with placeholder values


resp = client.head_bucket({
  bucket: "BucketName", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



2935
2936
2937
2938
 
# File 'lib/aws-sdk-s3/client.rb', line 2935

def head_bucket(params = {}, options = {})
  req = build_request(:head_bucket, params)
  req.send_request(options)
end

#head_object(params = {}) ⇒ Types::HeadObjectOutput

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you’re only interested in an object’s metadata. To use HEAD, you must have READ access to the object.

Examples:

Example: To retrieve metadata of an object without returning the object itself


# The following example retrieves an object metadata.

resp = client.head_object({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  accept_ranges: "bytes", 
  content_length: 3191, 
  content_type: "image/jpeg", 
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  last_modified: Time.parse("Thu, 15 Dec 2016 01:19:41 GMT"), 
  metadata: {
  }, 
  version_id: "null", 
}

Request syntax with placeholder values


resp = client.head_object({
  bucket: "BucketName", # required
  if_match: "IfMatch",
  if_modified_since: Time.now,
  if_none_match: "IfNoneMatch",
  if_unmodified_since: Time.now,
  key: "ObjectKey", # required
  range: "Range",
  version_id: "ObjectVersionId",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  part_number: 1,
})

Response structure


resp.delete_marker #=> Boolean
resp.accept_ranges #=> String
resp.expiration #=> String
resp.restore #=> String
resp.last_modified #=> Time
resp.content_length #=> Integer
resp.etag #=> String
resp.missing_meta #=> Integer
resp.version_id #=> String
resp.cache_control #=> String
resp.content_disposition #=> String
resp.content_encoding #=> String
resp.content_language #=> String
resp.content_type #=> String
resp.expires #=> Time
resp.expires_string #=> String
resp.website_redirect_location #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.metadata #=> Hash
resp.metadata["MetadataKey"] #=> String
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA"
resp.request_charged #=> String, one of "requester"
resp.replication_status #=> String, one of "COMPLETE", "PENDING", "FAILED", "REPLICA"
resp.parts_count #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :if_match (String) —

    Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).

  • :if_modified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

  • :if_none_match (String) —

    Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).

  • :if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

  • :key (required, String)
  • :range (String) —

    Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :part_number (Integer) —

    Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a ‘ranged’ HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.

Returns:

See Also:



3105
3106
3107
3108
 
# File 'lib/aws-sdk-s3/client.rb', line 3105

def head_object(params = {}, options = {})
  req = build_request(:head_object, params)
  req.send_request(options)
end

#list_bucket_analytics_configurations(params = {}) ⇒ Types::ListBucketAnalyticsConfigurationsOutput

Lists the analytics configurations for the bucket.

Examples:

Request syntax with placeholder values


resp = client.list_bucket_analytics_configurations({
  bucket: "BucketName", # required
  continuation_token: "Token",
})

Response structure


resp.is_truncated #=> Boolean
resp.continuation_token #=> String
resp.next_continuation_token #=> String
resp.analytics_configuration_list #=> Array
resp.analytics_configuration_list[0].id #=> String
resp.analytics_configuration_list[0].filter.prefix #=> String
resp.analytics_configuration_list[0].filter.tag.key #=> String
resp.analytics_configuration_list[0].filter.tag.value #=> String
resp.analytics_configuration_list[0].filter.and.prefix #=> String
resp.analytics_configuration_list[0].filter.and.tags #=> Array
resp.analytics_configuration_list[0].filter.and.tags[0].key #=> String
resp.analytics_configuration_list[0].filter.and.tags[0].value #=> String
resp.analytics_configuration_list[0].storage_class_analysis.data_export.output_schema_version #=> String, one of "V_1"
resp.analytics_configuration_list[0].storage_class_analysis.data_export.destination.s3_bucket_destination.format #=> String, one of "CSV"
resp.analytics_configuration_list[0].storage_class_analysis.data_export.destination.s3_bucket_destination. #=> String
resp.analytics_configuration_list[0].storage_class_analysis.data_export.destination.s3_bucket_destination.bucket #=> String
resp.analytics_configuration_list[0].storage_class_analysis.data_export.destination.s3_bucket_destination.prefix #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket from which analytics configurations are retrieved.

  • :continuation_token (String) —

    The ContinuationToken that represents a placeholder from where this request should begin.

Returns:

See Also:



3158
3159
3160
3161
 
# File 'lib/aws-sdk-s3/client.rb', line 3158

def list_bucket_analytics_configurations(params = {}, options = {})
  req = build_request(:list_bucket_analytics_configurations, params)
  req.send_request(options)
end

#list_bucket_inventory_configurations(params = {}) ⇒ Types::ListBucketInventoryConfigurationsOutput

Returns a list of inventory configurations for the bucket.

Examples:

Request syntax with placeholder values


resp = client.list_bucket_inventory_configurations({
  bucket: "BucketName", # required
  continuation_token: "Token",
})

Response structure


resp.continuation_token #=> String
resp.inventory_configuration_list #=> Array
resp.inventory_configuration_list[0].destination.s3_bucket_destination. #=> String
resp.inventory_configuration_list[0].destination.s3_bucket_destination.bucket #=> String
resp.inventory_configuration_list[0].destination.s3_bucket_destination.format #=> String, one of "CSV", "ORC"
resp.inventory_configuration_list[0].destination.s3_bucket_destination.prefix #=> String
resp.inventory_configuration_list[0].destination.s3_bucket_destination.encryption.ssekms.key_id #=> String
resp.inventory_configuration_list[0].is_enabled #=> Boolean
resp.inventory_configuration_list[0].filter.prefix #=> String
resp.inventory_configuration_list[0].id #=> String
resp.inventory_configuration_list[0].included_object_versions #=> String, one of "All", "Current"
resp.inventory_configuration_list[0].optional_fields #=> Array
resp.inventory_configuration_list[0].optional_fields[0] #=> String, one of "Size", "LastModifiedDate", "StorageClass", "ETag", "IsMultipartUploaded", "ReplicationStatus", "EncryptionStatus"
resp.inventory_configuration_list[0].schedule.frequency #=> String, one of "Daily", "Weekly"
resp.is_truncated #=> Boolean
resp.next_continuation_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the inventory configurations to retrieve.

  • :continuation_token (String) —

    The marker used to continue an inventory configuration listing that has been truncated. Use the NextContinuationToken from a previously truncated list response to continue the listing. The continuation token is an opaque value that Amazon S3 understands.

Returns:

See Also:



3212
3213
3214
3215
 
# File 'lib/aws-sdk-s3/client.rb', line 3212

def list_bucket_inventory_configurations(params = {}, options = {})
  req = build_request(:list_bucket_inventory_configurations, params)
  req.send_request(options)
end

#list_bucket_metrics_configurations(params = {}) ⇒ Types::ListBucketMetricsConfigurationsOutput

Lists the metrics configurations for the bucket.

Examples:

Request syntax with placeholder values


resp = client.list_bucket_metrics_configurations({
  bucket: "BucketName", # required
  continuation_token: "Token",
})

Response structure


resp.is_truncated #=> Boolean
resp.continuation_token #=> String
resp.next_continuation_token #=> String
resp.metrics_configuration_list #=> Array
resp.metrics_configuration_list[0].id #=> String
resp.metrics_configuration_list[0].filter.prefix #=> String
resp.metrics_configuration_list[0].filter.tag.key #=> String
resp.metrics_configuration_list[0].filter.tag.value #=> String
resp.metrics_configuration_list[0].filter.and.prefix #=> String
resp.metrics_configuration_list[0].filter.and.tags #=> Array
resp.metrics_configuration_list[0].filter.and.tags[0].key #=> String
resp.metrics_configuration_list[0].filter.and.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket containing the metrics configurations to retrieve.

  • :continuation_token (String) —

    The marker that is used to continue a metrics configuration listing that has been truncated. Use the NextContinuationToken from a previously truncated list response to continue the listing. The continuation token is an opaque value that Amazon S3 understands.

Returns:

See Also:



3262
3263
3264
3265
 
# File 'lib/aws-sdk-s3/client.rb', line 3262

def list_bucket_metrics_configurations(params = {}, options = {})
  req = build_request(:list_bucket_metrics_configurations, params)
  req.send_request(options)
end

#list_buckets(params = {}) ⇒ Types::ListBucketsOutput

Returns a list of all buckets owned by the authenticated sender of the request.

Examples:

Example: To list object versions


# The following example return versions of an object with specific key name prefix. The request limits the number of items
# returned to two. If there are are more than two object version, S3 returns NextToken in the response. You can specify
# this token value in your next request to fetch next set of object versions.

resp = client.list_buckets({
})

resp.to_h outputs the following:
{
  buckets: [
    {
      creation_date: Time.parse("2012-02-15T21: 03: 02.000Z"), 
      name: "examplebucket", 
    }, 
    {
      creation_date: Time.parse("2011-07-24T19: 33: 50.000Z"), 
      name: "examplebucket2", 
    }, 
    {
      creation_date: Time.parse("2010-12-17T00: 56: 49.000Z"), 
      name: "examplebucket3", 
    }, 
  ], 
  owner: {
    display_name: "own-display-name", 
    id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31", 
  }, 
}

Response structure


resp.buckets #=> Array
resp.buckets[0].name #=> String
resp.buckets[0].creation_date #=> Time
resp.owner.display_name #=> String
resp.owner.id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Returns:

See Also:



3319
3320
3321
3322
 
# File 'lib/aws-sdk-s3/client.rb', line 3319

def list_buckets(params = {}, options = {})
  req = build_request(:list_buckets, params)
  req.send_request(options)
end

#list_multipart_uploads(params = {}) ⇒ Types::ListMultipartUploadsOutput

This operation lists in-progress multipart uploads.

Examples:

Example: To list in-progress multipart uploads on a bucket


# The following example lists in-progress multipart uploads on a specific bucket.

resp = client.list_multipart_uploads({
  bucket: "examplebucket", 
})

resp.to_h outputs the following:
{
  uploads: [
    {
      initiated: Time.parse("2014-05-01T05:40:58.000Z"), 
      initiator: {
        display_name: "display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      key: "JavaFile", 
      owner: {
        display_name: "display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      storage_class: "STANDARD", 
      upload_id: "examplelUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--", 
    }, 
    {
      initiated: Time.parse("2014-05-01T05:41:27.000Z"), 
      initiator: {
        display_name: "display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      key: "JavaFile", 
      owner: {
        display_name: "display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      storage_class: "STANDARD", 
      upload_id: "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--", 
    }, 
  ], 
}

Example: List next set of multipart uploads when previous result is truncated


# The following example specifies the upload-id-marker and key-marker from previous truncated response to retrieve next
# setup of multipart uploads.

resp = client.list_multipart_uploads({
  bucket: "examplebucket", 
  key_marker: "nextkeyfrompreviousresponse", 
  max_uploads: 2, 
  upload_id_marker: "valuefrompreviousresponse", 
})

resp.to_h outputs the following:
{
  bucket: "acl1", 
  is_truncated: true, 
  key_marker: "", 
  max_uploads: 2, 
  next_key_marker: "someobjectkey", 
  next_upload_id_marker: "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--", 
  upload_id_marker: "", 
  uploads: [
    {
      initiated: Time.parse("2014-05-01T05:40:58.000Z"), 
      initiator: {
        display_name: "ownder-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      key: "JavaFile", 
      owner: {
        display_name: "mohanataws", 
        id: "852b113e7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      storage_class: "STANDARD", 
      upload_id: "gZ30jIqlUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--", 
    }, 
    {
      initiated: Time.parse("2014-05-01T05:41:27.000Z"), 
      initiator: {
        display_name: "ownder-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      key: "JavaFile", 
      owner: {
        display_name: "ownder-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      storage_class: "STANDARD", 
      upload_id: "b7tZSqIlo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.list_multipart_uploads({
  bucket: "BucketName", # required
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  key_marker: "KeyMarker",
  max_uploads: 1,
  prefix: "Prefix",
  upload_id_marker: "UploadIdMarker",
})

Response structure


resp.bucket #=> String
resp.key_marker #=> String
resp.upload_id_marker #=> String
resp.next_key_marker #=> String
resp.prefix #=> String
resp.delimiter #=> String
resp.next_upload_id_marker #=> String
resp.max_uploads #=> Integer
resp.is_truncated #=> Boolean
resp.uploads #=> Array
resp.uploads[0].upload_id #=> String
resp.uploads[0].key #=> String
resp.uploads[0].initiated #=> Time
resp.uploads[0].storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA"
resp.uploads[0].owner.display_name #=> String
resp.uploads[0].owner.id #=> String
resp.uploads[0].initiator.id #=> String
resp.uploads[0].initiator.display_name #=> String
resp.common_prefixes #=> Array
resp.common_prefixes[0].prefix #=> String
resp.encoding_type #=> String, one of "url"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :delimiter (String) —

    Character you use to group keys.

  • :encoding_type (String) —

    Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.

  • :key_marker (String) —

    Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin.

  • :max_uploads (Integer) —

    Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.

  • :prefix (String) —

    Lists in-progress uploads only for those keys that begin with the specified prefix.

  • :upload_id_marker (String) —

    Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored.

Returns:

See Also:



3508
3509
3510
3511
 
# File 'lib/aws-sdk-s3/client.rb', line 3508

def list_multipart_uploads(params = {}, options = {})
  req = build_request(:list_multipart_uploads, params)
  req.send_request(options)
end

#list_object_versions(params = {}) ⇒ Types::ListObjectVersionsOutput

Returns metadata about all of the versions of objects in a bucket.

Examples:

Example: To list object versions


# The following example return versions of an object with specific key name prefix. The request limits the number of items
# returned to two. If there are are more than two object version, S3 returns NextToken in the response. You can specify
# this token value in your next request to fetch next set of object versions.

resp = client.list_object_versions({
  bucket: "examplebucket", 
  prefix: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  versions: [
    {
      etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
      is_latest: true, 
      key: "HappyFace.jpg", 
      last_modified: Time.parse("2016-12-15T01:19:41.000Z"), 
      owner: {
        display_name: "owner-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      size: 3191, 
      storage_class: "STANDARD", 
      version_id: "null", 
    }, 
    {
      etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
      is_latest: false, 
      key: "HappyFace.jpg", 
      last_modified: Time.parse("2016-12-13T00:58:26.000Z"), 
      owner: {
        display_name: "owner-display-name", 
        id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      size: 3191, 
      storage_class: "STANDARD", 
      version_id: "PHtexPGjH2y.zBgT8LmB7wwLI2mpbz.k", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.list_object_versions({
  bucket: "BucketName", # required
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  key_marker: "KeyMarker",
  max_keys: 1,
  prefix: "Prefix",
  version_id_marker: "VersionIdMarker",
})

Response structure


resp.is_truncated #=> Boolean
resp.key_marker #=> String
resp.version_id_marker #=> String
resp.next_key_marker #=> String
resp.next_version_id_marker #=> String
resp.versions #=> Array
resp.versions[0].etag #=> String
resp.versions[0].size #=> Integer
resp.versions[0].storage_class #=> String, one of "STANDARD"
resp.versions[0].key #=> String
resp.versions[0].version_id #=> String
resp.versions[0].is_latest #=> Boolean
resp.versions[0].last_modified #=> Time
resp.versions[0].owner.display_name #=> String
resp.versions[0].owner.id #=> String
resp.delete_markers #=> Array
resp.delete_markers[0].owner.display_name #=> String
resp.delete_markers[0].owner.id #=> String
resp.delete_markers[0].key #=> String
resp.delete_markers[0].version_id #=> String
resp.delete_markers[0].is_latest #=> Boolean
resp.delete_markers[0].last_modified #=> Time
resp.name #=> String
resp.prefix #=> String
resp.delimiter #=> String
resp.max_keys #=> Integer
resp.common_prefixes #=> Array
resp.common_prefixes[0].prefix #=> String
resp.encoding_type #=> String, one of "url"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :delimiter (String) —

    A delimiter is a character you use to group keys.

  • :encoding_type (String) —

    Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.

  • :key_marker (String) —

    Specifies the key to start with when listing objects in a bucket.

  • :max_keys (Integer) —

    Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.

  • :prefix (String) —

    Limits the response to keys that begin with the specified prefix.

  • :version_id_marker (String) —

    Specifies the object version you want to start listing from.

Returns:

See Also:



3649
3650
3651
3652
 
# File 'lib/aws-sdk-s3/client.rb', line 3649

def list_object_versions(params = {}, options = {})
  req = build_request(:list_object_versions, params)
  req.send_request(options)
end

#list_objects(params = {}) ⇒ Types::ListObjectsOutput

Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

Examples:

Example: To list objects in a bucket


# The following example list two objects in a bucket.

resp = client.list_objects({
  bucket: "examplebucket", 
  max_keys: 2, 
})

resp.to_h outputs the following:
{
  contents: [
    {
      etag: "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"", 
      key: "example1.jpg", 
      last_modified: Time.parse("2014-11-21T19:40:05.000Z"), 
      owner: {
        display_name: "myname", 
        id: "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      size: 11, 
      storage_class: "STANDARD", 
    }, 
    {
      etag: "\"9c8af9a76df052144598c115ef33e511\"", 
      key: "example2.jpg", 
      last_modified: Time.parse("2013-11-15T01:10:49.000Z"), 
      owner: {
        display_name: "myname", 
        id: "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
      }, 
      size: 713193, 
      storage_class: "STANDARD", 
    }, 
  ], 
  next_marker: "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ==", 
}

Request syntax with placeholder values


resp = client.list_objects({
  bucket: "BucketName", # required
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  marker: "Marker",
  max_keys: 1,
  prefix: "Prefix",
  request_payer: "requester", # accepts requester
})

Response structure


resp.is_truncated #=> Boolean
resp.marker #=> String
resp.next_marker #=> String
resp.contents #=> Array
resp.contents[0].key #=> String
resp.contents[0].last_modified #=> Time
resp.contents[0].etag #=> String
resp.contents[0].size #=> Integer
resp.contents[0].storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.contents[0].owner.display_name #=> String
resp.contents[0].owner.id #=> String
resp.name #=> String
resp.prefix #=> String
resp.delimiter #=> String
resp.max_keys #=> Integer
resp.common_prefixes #=> Array
resp.common_prefixes[0].prefix #=> String
resp.encoding_type #=> String, one of "url"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :delimiter (String) —

    A delimiter is a character you use to group keys.

  • :encoding_type (String) —

    Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.

  • :marker (String) —

    Specifies the key to start with when listing objects in a bucket.

  • :max_keys (Integer) —

    Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.

  • :prefix (String) —

    Limits the response to keys that begin with the specified prefix.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the list objects request. Bucket owners need not specify this parameter in their requests.

Returns:

See Also:



3775
3776
3777
3778
 
# File 'lib/aws-sdk-s3/client.rb', line 3775

def list_objects(params = {}, options = {})
  req = build_request(:list_objects, params)
  req.send_request(options)
end

#list_objects_v2(params = {}) ⇒ Types::ListObjectsV2Output

Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. Note: ListObjectsV2 is the revised List Objects API and we recommend you use this revised API for new application development.

Examples:

Example: To get object list


# The following example retrieves object list. The request specifies max keys to limit response to include only 2 object
# keys. 

resp = client.list_objects_v2({
  bucket: "examplebucket", 
  max_keys: 2, 
})

resp.to_h outputs the following:
{
  contents: [
    {
      etag: "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"", 
      key: "happyface.jpg", 
      last_modified: Time.parse("2014-11-21T19:40:05.000Z"), 
      size: 11, 
      storage_class: "STANDARD", 
    }, 
    {
      etag: "\"becf17f89c30367a9a44495d62ed521a-1\"", 
      key: "test.jpg", 
      last_modified: Time.parse("2014-05-02T04:51:50.000Z"), 
      size: 4192256, 
      storage_class: "STANDARD", 
    }, 
  ], 
  is_truncated: true, 
  key_count: 2, 
  max_keys: 2, 
  name: "examplebucket", 
  next_continuation_token: "1w41l63U0xa8q7smH50vCxyTQqdxo69O3EmK28Bi5PcROI4wI/EyIJg==", 
  prefix: "", 
}

Request syntax with placeholder values


resp = client.list_objects_v2({
  bucket: "BucketName", # required
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  max_keys: 1,
  prefix: "Prefix",
  continuation_token: "Token",
  fetch_owner: false,
  start_after: "StartAfter",
  request_payer: "requester", # accepts requester
})

Response structure


resp.is_truncated #=> Boolean
resp.contents #=> Array
resp.contents[0].key #=> String
resp.contents[0].last_modified #=> Time
resp.contents[0].etag #=> String
resp.contents[0].size #=> Integer
resp.contents[0].storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "GLACIER", "STANDARD_IA", "ONEZONE_IA"
resp.contents[0].owner.display_name #=> String
resp.contents[0].owner.id #=> String
resp.name #=> String
resp.prefix #=> String
resp.delimiter #=> String
resp.max_keys #=> Integer
resp.common_prefixes #=> Array
resp.common_prefixes[0].prefix #=> String
resp.encoding_type #=> String, one of "url"
resp.key_count #=> Integer
resp.continuation_token #=> String
resp.next_continuation_token #=> String
resp.start_after #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    Name of the bucket to list.

  • :delimiter (String) —

    A delimiter is a character you use to group keys.

  • :encoding_type (String) —

    Encoding type used by Amazon S3 to encode object keys in the response.

  • :max_keys (Integer) —

    Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.

  • :prefix (String) —

    Limits the response to keys that begin with the specified prefix.

  • :continuation_token (String) —

    ContinuationToken indicates Amazon S3 that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key

  • :fetch_owner (Boolean) —

    The owner field is not present in listV2 by default, if you want to return owner field with each key in the result then set the fetch owner field to true

  • :start_after (String) —

    StartAfter is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this specified key. StartAfter can be any key in the bucket

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the list objects request in V2 style. Bucket owners need not specify this parameter in their requests.

Returns:

See Also:



3915
3916
3917
3918
 
# File 'lib/aws-sdk-s3/client.rb', line 3915

def list_objects_v2(params = {}, options = {})
  req = build_request(:list_objects_v2, params)
  req.send_request(options)
end

#list_parts(params = {}) ⇒ Types::ListPartsOutput

Lists the parts that have been uploaded for a specific multipart upload.

Examples:

Example: To list parts of a multipart upload.


# The following example lists parts uploaded for a specific multipart upload.

resp = client.list_parts({
  bucket: "examplebucket", 
  key: "bigobject", 
  upload_id: "example7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--", 
})

resp.to_h outputs the following:
{
  initiator: {
    display_name: "owner-display-name", 
    id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
  }, 
  owner: {
    display_name: "owner-display-name", 
    id: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc", 
  }, 
  parts: [
    {
      etag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"", 
      last_modified: Time.parse("2016-12-16T00:11:42.000Z"), 
      part_number: 1, 
      size: 26246026, 
    }, 
    {
      etag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"", 
      last_modified: Time.parse("2016-12-16T00:15:01.000Z"), 
      part_number: 2, 
      size: 26246026, 
    }, 
  ], 
  storage_class: "STANDARD", 
}

Request syntax with placeholder values


resp = client.list_parts({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  max_parts: 1,
  part_number_marker: 1,
  upload_id: "MultipartUploadId", # required
  request_payer: "requester", # accepts requester
})

Response structure


resp.abort_date #=> Time
resp.abort_rule_id #=> String
resp.bucket #=> String
resp.key #=> String
resp.upload_id #=> String
resp.part_number_marker #=> Integer
resp.next_part_number_marker #=> Integer
resp.max_parts #=> Integer
resp.is_truncated #=> Boolean
resp.parts #=> Array
resp.parts[0].part_number #=> Integer
resp.parts[0].last_modified #=> Time
resp.parts[0].etag #=> String
resp.parts[0].size #=> Integer
resp.initiator.id #=> String
resp.initiator.display_name #=> String
resp.owner.display_name #=> String
resp.owner.id #=> String
resp.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA"
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :max_parts (Integer) —

    Sets the maximum number of parts to return.

  • :part_number_marker (Integer) —

    Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.

  • :upload_id (required, String) —

    Upload ID identifying the multipart upload whose parts are being listed.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



4038
4039
4040
4041
 
# File 'lib/aws-sdk-s3/client.rb', line 4038

def list_parts(params = {}, options = {})
  req = build_request(:list_parts, params)
  req.send_request(options)
end

#put_bucket_accelerate_configuration(params = {}) ⇒ Struct

Sets the accelerate configuration of an existing bucket.

Examples:

Request syntax with placeholder values


resp = client.put_bucket_accelerate_configuration({
  bucket: "BucketName", # required
  accelerate_configuration: { # required
    status: "Enabled", # accepts Enabled, Suspended
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    Name of the bucket for which the accelerate configuration is set.

  • :accelerate_configuration (required, Types::AccelerateConfiguration) —

    Specifies the Accelerate Configuration you want to set for the bucket.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4066
4067
4068
4069
 
# File 'lib/aws-sdk-s3/client.rb', line 4066

def put_bucket_accelerate_configuration(params = {}, options = {})
  req = build_request(:put_bucket_accelerate_configuration, params)
  req.send_request(options)
end

#put_bucket_acl(params = {}) ⇒ Struct

Sets the permissions on a bucket using access control lists (ACL).

Examples:

Example: Put bucket acl


# The following example replaces existing ACL on a bucket. The ACL grants the bucket owner (specified using the owner ID)
# and write permission to the LogDelivery group. Because this is a replace operation, you must specify all the grants in
# your request. To incrementally add or remove ACL grants, you might use the console.

resp = client.put_bucket_acl({
  bucket: "examplebucket", 
  grant_full_control: "id=examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484", 
  grant_write: "uri=http://acs.amazonaws.com/groups/s3/LogDelivery", 
})

Request syntax with placeholder values


resp = client.put_bucket_acl({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read
  access_control_policy: {
    grants: [
      {
        grantee: {
          display_name: "DisplayName",
          email_address: "EmailAddress",
          id: "ID",
          type: "CanonicalUser", # required, accepts CanonicalUser, AmazonCustomerByEmail, Group
          uri: "URI",
        },
        permission: "FULL_CONTROL", # accepts FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP
      },
    ],
    owner: {
      display_name: "DisplayName",
      id: "ID",
    },
  },
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write: "GrantWrite",
  grant_write_acp: "GrantWriteACP",
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the bucket.

  • :access_control_policy (Types::AccessControlPolicy)
  • :bucket (required, String)
  • :content_md5 (String)
  • :grant_full_control (String) —

    Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.

  • :grant_read (String) —

    Allows grantee to list the objects in the bucket.

  • :grant_read_acp (String) —

    Allows grantee to read the bucket ACL.

  • :grant_write (String) —

    Allows grantee to create, overwrite, and delete any object in the bucket.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable bucket.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4149
4150
4151
4152
 
# File 'lib/aws-sdk-s3/client.rb', line 4149

def put_bucket_acl(params = {}, options = {})
  req = build_request(:put_bucket_acl, params)
  req.send_request(options)
end

#put_bucket_analytics_configuration(params = {}) ⇒ Struct

Sets an analytics configuration for the bucket (specified by the analytics configuration ID).

Examples:

Request syntax with placeholder values


resp = client.put_bucket_analytics_configuration({
  bucket: "BucketName", # required
  id: "AnalyticsId", # required
  analytics_configuration: { # required
    id: "AnalyticsId", # required
    filter: {
      prefix: "Prefix",
      tag: {
        key: "ObjectKey", # required
        value: "Value", # required
      },
      and: {
        prefix: "Prefix",
        tags: [
          {
            key: "ObjectKey", # required
            value: "Value", # required
          },
        ],
      },
    },
    storage_class_analysis: { # required
      data_export: {
        output_schema_version: "V_1", # required, accepts V_1
        destination: { # required
          s3_bucket_destination: { # required
            format: "CSV", # required, accepts CSV
            bucket_account_id: "AccountId",
            bucket: "BucketName", # required
            prefix: "Prefix",
          },
        },
      },
    },
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket to which an analytics configuration is stored.

  • :id (required, String) —

    The identifier used to represent an analytics configuration.

  • :analytics_configuration (required, Types::AnalyticsConfiguration) —

    The configuration and any analyses for the analytics filter.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4211
4212
4213
4214
 
# File 'lib/aws-sdk-s3/client.rb', line 4211

def put_bucket_analytics_configuration(params = {}, options = {})
  req = build_request(:put_bucket_analytics_configuration, params)
  req.send_request(options)
end

#put_bucket_cors(params = {}) ⇒ Struct

Sets the cors configuration for a bucket.

Examples:

Example: To set cors configuration on a bucket.


# The following example enables PUT, POST, and DELETE requests from www.example.com, and enables GET requests from any
# domain.

resp = client.put_bucket_cors({
  bucket: "", 
  cors_configuration: {
    cors_rules: [
      {
        allowed_headers: [
          "*", 
        ], 
        allowed_methods: [
          "PUT", 
          "POST", 
          "DELETE", 
        ], 
        allowed_origins: [
          "http://www.example.com", 
        ], 
        expose_headers: [
          "x-amz-server-side-encryption", 
        ], 
        max_age_seconds: 3000, 
      }, 
      {
        allowed_headers: [
          "Authorization", 
        ], 
        allowed_methods: [
          "GET", 
        ], 
        allowed_origins: [
          "*", 
        ], 
        max_age_seconds: 3000, 
      }, 
    ], 
  }, 
  content_md5: "", 
})

Request syntax with placeholder values


resp = client.put_bucket_cors({
  bucket: "BucketName", # required
  cors_configuration: { # required
    cors_rules: [ # required
      {
        allowed_headers: ["AllowedHeader"],
        allowed_methods: ["AllowedMethod"], # required
        allowed_origins: ["AllowedOrigin"], # required
        expose_headers: ["ExposeHeader"],
        max_age_seconds: 1,
      },
    ],
  },
  content_md5: "ContentMD5",
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4292
4293
4294
4295
 
# File 'lib/aws-sdk-s3/client.rb', line 4292

def put_bucket_cors(params = {}, options = {})
  req = build_request(:put_bucket_cors, params)
  req.send_request(options)
end

#put_bucket_encryption(params = {}) ⇒ Struct

Creates a new server-side encryption configuration (or replaces an existing one, if present).

Examples:

Request syntax with placeholder values


resp = client.put_bucket_encryption({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  server_side_encryption_configuration: { # required
    rules: [ # required
      {
        apply_server_side_encryption_by_default: {
          sse_algorithm: "AES256", # required, accepts AES256, aws:kms
          kms_master_key_id: "SSEKMSKeyId",
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket for which the server-side encryption configuration is set.

  • :content_md5 (String) —

    The base64-encoded 128-bit MD5 digest of the server-side encryption configuration.

  • :server_side_encryption_configuration (required, Types::ServerSideEncryptionConfiguration) —

    Container for server-side encryption configuration rules. Currently S3 supports one rule only.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4335
4336
4337
4338
 
# File 'lib/aws-sdk-s3/client.rb', line 4335

def put_bucket_encryption(params = {}, options = {})
  req = build_request(:put_bucket_encryption, params)
  req.send_request(options)
end

#put_bucket_inventory_configuration(params = {}) ⇒ Struct

Adds an inventory configuration (identified by the inventory ID) from the bucket.

Examples:

Request syntax with placeholder values


resp = client.put_bucket_inventory_configuration({
  bucket: "BucketName", # required
  id: "InventoryId", # required
  inventory_configuration: { # required
    destination: { # required
      s3_bucket_destination: { # required
        account_id: "AccountId",
        bucket: "BucketName", # required
        format: "CSV", # required, accepts CSV, ORC
        prefix: "Prefix",
        encryption: {
          sses3: {
          },
          ssekms: {
            key_id: "SSEKMSKeyId", # required
          },
        },
      },
    },
    is_enabled: false, # required
    filter: {
      prefix: "Prefix", # required
    },
    id: "InventoryId", # required
    included_object_versions: "All", # required, accepts All, Current
    optional_fields: ["Size"], # accepts Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, ReplicationStatus, EncryptionStatus
    schedule: { # required
      frequency: "Daily", # required, accepts Daily, Weekly
    },
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket where the inventory configuration will be stored.

  • :id (required, String) —

    The ID used to identify the inventory configuration.

  • :inventory_configuration (required, Types::InventoryConfiguration) —

    Specifies the inventory configuration.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4393
4394
4395
4396
 
# File 'lib/aws-sdk-s3/client.rb', line 4393

def put_bucket_inventory_configuration(params = {}, options = {})
  req = build_request(:put_bucket_inventory_configuration, params)
  req.send_request(options)
end

#put_bucket_lifecycle(params = {}) ⇒ Struct

Deprecated, see the PutBucketLifecycleConfiguration operation.

Examples:

Request syntax with placeholder values


resp = client.put_bucket_lifecycle({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  lifecycle_configuration: {
    rules: [ # required
      {
        expiration: {
          date: Time.now,
          days: 1,
          expired_object_delete_marker: false,
        },
        id: "ID",
        prefix: "Prefix", # required
        status: "Enabled", # required, accepts Enabled, Disabled
        transition: {
          date: Time.now,
          days: 1,
          storage_class: "GLACIER", # accepts GLACIER, STANDARD_IA, ONEZONE_IA
        },
        noncurrent_version_transition: {
          noncurrent_days: 1,
          storage_class: "GLACIER", # accepts GLACIER, STANDARD_IA, ONEZONE_IA
        },
        noncurrent_version_expiration: {
          noncurrent_days: 1,
        },
        abort_incomplete_multipart_upload: {
          days_after_initiation: 1,
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4448
4449
4450
4451
 
# File 'lib/aws-sdk-s3/client.rb', line 4448

def put_bucket_lifecycle(params = {}, options = {})
  req = build_request(:put_bucket_lifecycle, params)
  req.send_request(options)
end

#put_bucket_lifecycle_configuration(params = {}) ⇒ Struct

Sets lifecycle configuration for your bucket. If a lifecycle configuration exists, it replaces it.

Examples:

Example: Put bucket lifecycle


# The following example replaces existing lifecycle configuration, if any, on the specified bucket. 

resp = client.put_bucket_lifecycle_configuration({
  bucket: "examplebucket", 
  lifecycle_configuration: {
    rules: [
      {
        expiration: {
          days: 3650, 
        }, 
        filter: {
          prefix: "documents/", 
        }, 
        id: "TestOnly", 
        status: "Enabled", 
        transitions: [
          {
            days: 365, 
            storage_class: "GLACIER", 
          }, 
        ], 
      }, 
    ], 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_lifecycle_configuration({
  bucket: "BucketName", # required
  lifecycle_configuration: {
    rules: [ # required
      {
        expiration: {
          date: Time.now,
          days: 1,
          expired_object_delete_marker: false,
        },
        id: "ID",
        prefix: "Prefix",
        filter: {
          prefix: "Prefix",
          tag: {
            key: "ObjectKey", # required
            value: "Value", # required
          },
          and: {
            prefix: "Prefix",
            tags: [
              {
                key: "ObjectKey", # required
                value: "Value", # required
              },
            ],
          },
        },
        status: "Enabled", # required, accepts Enabled, Disabled
        transitions: [
          {
            date: Time.now,
            days: 1,
            storage_class: "GLACIER", # accepts GLACIER, STANDARD_IA, ONEZONE_IA
          },
        ],
        noncurrent_version_transitions: [
          {
            noncurrent_days: 1,
            storage_class: "GLACIER", # accepts GLACIER, STANDARD_IA, ONEZONE_IA
          },
        ],
        noncurrent_version_expiration: {
          noncurrent_days: 1,
        },
        abort_incomplete_multipart_upload: {
          days_after_initiation: 1,
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4550
4551
4552
4553
 
# File 'lib/aws-sdk-s3/client.rb', line 4550

def put_bucket_lifecycle_configuration(params = {}, options = {})
  req = build_request(:put_bucket_lifecycle_configuration, params)
  req.send_request(options)
end

#put_bucket_logging(params = {}) ⇒ Struct

Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. To set the logging status of a bucket, you must be the bucket owner.

Examples:

Example: Set logging configuration for a bucket


# The following example sets logging policy on a bucket. For the Log Delivery group to deliver logs to the destination
# bucket, it needs permission for the READ_ACP action which the policy grants.

resp = client.put_bucket_logging({
  bucket: "sourcebucket", 
  bucket_logging_status: {
    logging_enabled: {
      target_bucket: "targetbucket", 
      target_grants: [
        {
          grantee: {
            type: "Group", 
            uri: "http://acs.amazonaws.com/groups/global/AllUsers", 
          }, 
          permission: "READ", 
        }, 
      ], 
      target_prefix: "MyBucketLogs/", 
    }, 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_logging({
  bucket: "BucketName", # required
  bucket_logging_status: { # required
    logging_enabled: {
      target_bucket: "TargetBucket", # required
      target_grants: [
        {
          grantee: {
            display_name: "DisplayName",
            email_address: "EmailAddress",
            id: "ID",
            type: "CanonicalUser", # required, accepts CanonicalUser, AmazonCustomerByEmail, Group
            uri: "URI",
          },
          permission: "FULL_CONTROL", # accepts FULL_CONTROL, READ, WRITE
        },
      ],
      target_prefix: "TargetPrefix", # required
    },
  },
  content_md5: "ContentMD5",
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4621
4622
4623
4624
 
# File 'lib/aws-sdk-s3/client.rb', line 4621

def put_bucket_logging(params = {}, options = {})
  req = build_request(:put_bucket_logging, params)
  req.send_request(options)
end

#put_bucket_metrics_configuration(params = {}) ⇒ Struct

Sets a metrics configuration (specified by the metrics configuration ID) for the bucket.

Examples:

Request syntax with placeholder values


resp = client.put_bucket_metrics_configuration({
  bucket: "BucketName", # required
  id: "MetricsId", # required
  metrics_configuration: { # required
    id: "MetricsId", # required
    filter: {
      prefix: "Prefix",
      tag: {
        key: "ObjectKey", # required
        value: "Value", # required
      },
      and: {
        prefix: "Prefix",
        tags: [
          {
            key: "ObjectKey", # required
            value: "Value", # required
          },
        ],
      },
    },
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String) —

    The name of the bucket for which the metrics configuration is set.

  • :id (required, String) —

    The ID used to identify the metrics configuration.

  • :metrics_configuration (required, Types::MetricsConfiguration) —

    Specifies the metrics configuration.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4670
4671
4672
4673
 
# File 'lib/aws-sdk-s3/client.rb', line 4670

def put_bucket_metrics_configuration(params = {}, options = {})
  req = build_request(:put_bucket_metrics_configuration, params)
  req.send_request(options)
end

#put_bucket_notification(params = {}) ⇒ Struct

Deprecated, see the PutBucketNotificationConfiguraiton operation.

Examples:

Request syntax with placeholder values


resp = client.put_bucket_notification({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  notification_configuration: { # required
    topic_configuration: {
      id: "NotificationId",
      events: ["s3:ReducedRedundancyLostObject"], # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      event: "s3:ReducedRedundancyLostObject", # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      topic: "TopicArn",
    },
    queue_configuration: {
      id: "NotificationId",
      event: "s3:ReducedRedundancyLostObject", # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      events: ["s3:ReducedRedundancyLostObject"], # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      queue: "QueueArn",
    },
    cloud_function_configuration: {
      id: "NotificationId",
      event: "s3:ReducedRedundancyLostObject", # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      events: ["s3:ReducedRedundancyLostObject"], # accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
      cloud_function: "CloudFunction",
      invocation_role: "CloudFunctionInvocationRole",
    },
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4717
4718
4719
4720
 
# File 'lib/aws-sdk-s3/client.rb', line 4717

def put_bucket_notification(params = {}, options = {})
  req = build_request(:put_bucket_notification, params)
  req.send_request(options)
end

#put_bucket_notification_configuration(params = {}) ⇒ Struct

Enables notifications of specified events for a bucket.

Examples:

Example: Set notification configuration for a bucket


# The following example sets notification configuration on a bucket to publish the object created events to an SNS topic.

resp = client.put_bucket_notification_configuration({
  bucket: "examplebucket", 
  notification_configuration: {
    topic_configurations: [
      {
        events: [
          "s3:ObjectCreated:*", 
        ], 
        topic_arn: "arn:aws:sns:us-west-2:123456789012:s3-notification-topic", 
      }, 
    ], 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_notification_configuration({
  bucket: "BucketName", # required
  notification_configuration: { # required
    topic_configurations: [
      {
        id: "NotificationId",
        topic_arn: "TopicArn", # required
        events: ["s3:ReducedRedundancyLostObject"], # required, accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
        filter: {
          key: {
            filter_rules: [
              {
                name: "prefix", # accepts prefix, suffix
                value: "FilterRuleValue",
              },
            ],
          },
        },
      },
    ],
    queue_configurations: [
      {
        id: "NotificationId",
        queue_arn: "QueueArn", # required
        events: ["s3:ReducedRedundancyLostObject"], # required, accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
        filter: {
          key: {
            filter_rules: [
              {
                name: "prefix", # accepts prefix, suffix
                value: "FilterRuleValue",
              },
            ],
          },
        },
      },
    ],
    lambda_function_configurations: [
      {
        id: "NotificationId",
        lambda_function_arn: "LambdaFunctionArn", # required
        events: ["s3:ReducedRedundancyLostObject"], # required, accepts s3:ReducedRedundancyLostObject, s3:ObjectCreated:*, s3:ObjectCreated:Put, s3:ObjectCreated:Post, s3:ObjectCreated:Copy, s3:ObjectCreated:CompleteMultipartUpload, s3:ObjectRemoved:*, s3:ObjectRemoved:Delete, s3:ObjectRemoved:DeleteMarkerCreated
        filter: {
          key: {
            filter_rules: [
              {
                name: "prefix", # accepts prefix, suffix
                value: "FilterRuleValue",
              },
            ],
          },
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :notification_configuration (required, Types::NotificationConfiguration) —

    Container for specifying the notification configuration of the bucket. If this element is empty, notifications are turned off on the bucket.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4814
4815
4816
4817
 
# File 'lib/aws-sdk-s3/client.rb', line 4814

def put_bucket_notification_configuration(params = {}, options = {})
  req = build_request(:put_bucket_notification_configuration, params)
  req.send_request(options)
end

#put_bucket_policy(params = {}) ⇒ Struct

Replaces a policy on a bucket. If the bucket already has a policy, the one in this request completely replaces it.

Examples:

Example: Set bucket policy


# The following example sets a permission policy on a bucket.

resp = client.put_bucket_policy({
  bucket: "examplebucket", 
  policy: "{\"Version\": \"2012-10-17\", \"Statement\": [{ \"Sid\": \"id-1\",\"Effect\": \"Allow\",\"Principal\": {\"AWS\": \"arn:aws:iam::123456789012:root\"}, \"Action\": [ \"s3:PutObject\",\"s3:PutObjectAcl\"], \"Resource\": [\"arn:aws:s3:::acl3/*\" ] } ]}", 
})

Request syntax with placeholder values


resp = client.put_bucket_policy({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  confirm_remove_self_bucket_access: false,
  policy: "Policy", # required
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :content_md5 (String)
  • :confirm_remove_self_bucket_access (Boolean) —

    Set this parameter to true to confirm that you want to remove your permissions to change this bucket policy in the future.

  • :policy (required, String) —

    The bucket policy as a JSON document.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4858
4859
4860
4861
 
# File 'lib/aws-sdk-s3/client.rb', line 4858

def put_bucket_policy(params = {}, options = {})
  req = build_request(:put_bucket_policy, params)
  req.send_request(options)
end

#put_bucket_replication(params = {}) ⇒ Struct

Creates a new replication configuration (or replaces an existing one, if present).

Examples:

Example: Set replication configuration on a bucket


# The following example sets replication configuration on a bucket.

resp = client.put_bucket_replication({
  bucket: "examplebucket", 
  replication_configuration: {
    role: "arn:aws:iam::123456789012:role/examplerole", 
    rules: [
      {
        destination: {
          bucket: "arn:aws:s3:::destinationbucket", 
          storage_class: "STANDARD", 
        }, 
        prefix: "", 
        status: "Enabled", 
      }, 
    ], 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_replication({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  replication_configuration: { # required
    role: "Role", # required
    rules: [ # required
      {
        id: "ID",
        prefix: "Prefix", # required
        status: "Enabled", # required, accepts Enabled, Disabled
        source_selection_criteria: {
          sse_kms_encrypted_objects: {
            status: "Enabled", # required, accepts Enabled, Disabled
          },
        },
        destination: { # required
          bucket: "BucketName", # required
          account: "AccountId",
          storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA
          access_control_translation: {
            owner: "Destination", # required, accepts Destination
          },
          encryption_configuration: {
            replica_kms_key_id: "ReplicaKmsKeyID",
          },
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :content_md5 (String)
  • :replication_configuration (required, Types::ReplicationConfiguration) —

    Container for replication rules. You can add as many as 1,000 rules. Total replication configuration size can be up to 2 MB.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4935
4936
4937
4938
 
# File 'lib/aws-sdk-s3/client.rb', line 4935

def put_bucket_replication(params = {}, options = {})
  req = build_request(:put_bucket_replication, params)
  req.send_request(options)
end

#put_bucket_request_payment(params = {}) ⇒ Struct

Sets the request payment configuration for a bucket. By default, the bucket owner pays for downloads from the bucket. This configuration parameter enables the bucket owner (only) to specify that the person requesting the download will be charged for the download. Documentation on requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html

Examples:

Example: Set request payment configuration on a bucket.


# The following example sets request payment configuration on a bucket so that person requesting the download is charged.

resp = client.put_bucket_request_payment({
  bucket: "examplebucket", 
  request_payment_configuration: {
    payer: "Requester", 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_request_payment({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  request_payment_configuration: { # required
    payer: "Requester", # required, accepts Requester, BucketOwner
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4981
4982
4983
4984
 
# File 'lib/aws-sdk-s3/client.rb', line 4981

def put_bucket_request_payment(params = {}, options = {})
  req = build_request(:put_bucket_request_payment, params)
  req.send_request(options)
end

#put_bucket_tagging(params = {}) ⇒ Struct

Sets the tags for a bucket.

Examples:

Example: Set tags on a bucket


# The following example sets tags on a bucket. Any existing tags are replaced.

resp = client.put_bucket_tagging({
  bucket: "examplebucket", 
  tagging: {
    tag_set: [
      {
        key: "Key1", 
        value: "Value1", 
      }, 
      {
        key: "Key2", 
        value: "Value2", 
      }, 
    ], 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_tagging({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  tagging: { # required
    tag_set: [ # required
      {
        key: "ObjectKey", # required
        value: "Value", # required
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :content_md5 (String)
  • :tagging (required, Types::Tagging)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



5036
5037
5038
5039
 
# File 'lib/aws-sdk-s3/client.rb', line 5036

def put_bucket_tagging(params = {}, options = {})
  req = build_request(:put_bucket_tagging, params)
  req.send_request(options)
end

#put_bucket_versioning(params = {}) ⇒ Struct

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Examples:

Example: Set versioning configuration on a bucket


# The following example sets versioning configuration on bucket. The configuration enables versioning on the bucket.

resp = client.put_bucket_versioning({
  bucket: "examplebucket", 
  versioning_configuration: {
    mfa_delete: "Disabled", 
    status: "Enabled", 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_versioning({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  mfa: "MFA",
  versioning_configuration: { # required
    mfa_delete: "Enabled", # accepts Enabled, Disabled
    status: "Enabled", # accepts Enabled, Suspended
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :content_md5 (String)
  • :mfa (String) —

    The concatenation of the authentication device’s serial number, a space, and the value that is displayed on your authentication device.

  • :versioning_configuration (required, Types::VersioningConfiguration)

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



5085
5086
5087
5088
 
# File 'lib/aws-sdk-s3/client.rb', line 5085

def put_bucket_versioning(params = {}, options = {})
  req = build_request(:put_bucket_versioning, params)
  req.send_request(options)
end

#put_bucket_website(params = {}) ⇒ Struct

Set the website configuration for a bucket.

Examples:

Example: Set website configuration on a bucket


# The following example adds website configuration to a bucket.

resp = client.put_bucket_website({
  bucket: "examplebucket", 
  content_md5: "", 
  website_configuration: {
    error_document: {
      key: "error.html", 
    }, 
    index_document: {
      suffix: "index.html", 
    }, 
  }, 
})

Request syntax with placeholder values


resp = client.put_bucket_website({
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  website_configuration: { # required
    error_document: {
      key: "ObjectKey", # required
    },
    index_document: {
      suffix: "Suffix", # required
    },
    redirect_all_requests_to: {
      host_name: "HostName", # required
      protocol: "http", # accepts http, https
    },
    routing_rules: [
      {
        condition: {
          http_error_code_returned_equals: "HttpErrorCodeReturnedEquals",
          key_prefix_equals: "KeyPrefixEquals",
        },
        redirect: { # required
          host_name: "HostName",
          http_redirect_code: "HttpRedirectCode",
          protocol: "http", # accepts http, https
          replace_key_prefix_with: "ReplaceKeyPrefixWith",
          replace_key_with: "ReplaceKeyWith",
        },
      },
    ],
  },
})

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



5156
5157
5158
5159
 
# File 'lib/aws-sdk-s3/client.rb', line 5156

def put_bucket_website(params = {}, options = {})
  req = build_request(:put_bucket_website, params)
  req.send_request(options)
end

#put_object(params = {}) ⇒ Types::PutObjectOutput

Adds an object to a bucket.

Examples:

Example: To upload an object and specify server-side encryption and object tags


# The following example uploads and object. The request specifies the optional server-side encryption option. The request
# also specifies optional object tags. If the bucket is versioning enabled, S3 returns version ID in response.

resp = client.put_object({
  body: "filetoupload", 
  bucket: "examplebucket", 
  key: "exampleobject", 
  server_side_encryption: "AES256", 
  tagging: "key1=value1&key2=value2", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  server_side_encryption: "AES256", 
  version_id: "Ri.vC6qVlA4dEnjgRV4ZHsHoFIjqEMNt", 
}

Example: To upload an object and specify canned ACL.


# The following example uploads and object. The request specifies optional canned ACL (access control list) to all READ
# access to authenticated users. If the bucket is versioning enabled, S3 returns version ID in response.

resp = client.put_object({
  acl: "authenticated-read", 
  body: "filetoupload", 
  bucket: "examplebucket", 
  key: "exampleobject", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  version_id: "Kirh.unyZwjQ69YxcQLA8z4F5j3kJJKr", 
}

Example: To upload an object


# The following example uploads an object to a versioning-enabled bucket. The source file is specified using Windows file
# syntax. S3 returns VersionId of the newly created object.

resp = client.put_object({
  body: "HappyFace.jpg", 
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  version_id: "tpf3zF08nBplQK1XLOefGskR7mGDwcDk", 
}

Example: To create an object.


# The following example creates an object. If the bucket is versioning enabled, S3 returns version ID in response.

resp = client.put_object({
  body: "filetoupload", 
  bucket: "examplebucket", 
  key: "objectkey", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  version_id: "Bvq0EDKxOcXLJXNo_Lkz37eM3R4pfzyQ", 
}

Example: To upload an object and specify optional tags


# The following example uploads an object. The request specifies optional object tags. The bucket is versioned, therefore
# S3 returns version ID of the newly created object.

resp = client.put_object({
  body: "c:\\HappyFace.jpg", 
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
  tagging: "key1=value1&key2=value2", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  version_id: "psM2sYY4.o1501dSx8wMvnkOzSBB.V4a", 
}

Example: To upload object and specify user-defined metadata


# The following example creates an object. The request also specifies optional metadata. If the bucket is versioning
# enabled, S3 returns version ID in response.

resp = client.put_object({
  body: "filetoupload", 
  bucket: "examplebucket", 
  key: "exampleobject", 
  metadata: {
    "metadata1" => "value1", 
    "metadata2" => "value2", 
  }, 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  version_id: "pSKidl4pHBiNwukdbcPXAIs.sshFFOc0", 
}

Example: To upload an object (specify optional headers)


# The following example uploads an object. The request specifies optional request headers to directs S3 to use specific
# storage class and use server-side encryption.

resp = client.put_object({
  body: "HappyFace.jpg", 
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
  server_side_encryption: "AES256", 
  storage_class: "STANDARD_IA", 
})

resp.to_h outputs the following:
{
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  server_side_encryption: "AES256", 
  version_id: "CG612hodqujkf8FaaNfp8U..FIhLROcp", 
}

Streaming a file from disk

# upload file from disk in a single request, may not exceed 5GB
File.open('/source/file/path', 'rb') do |file|
  s3.put_object(bucket: 'bucket-name', key: 'object-key', body: file)
end

Request syntax with placeholder values


resp = client.put_object({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  body: source_file,
  bucket: "BucketName", # required
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_length: 1,
  content_md5: "ContentMD5",
  content_type: "ContentType",
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  key: "ObjectKey", # required
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
})

Response structure


resp.expiration #=> String
resp.etag #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.version_id #=> String
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :body (String, IO) —

    Object data.

  • :bucket (required, String) —

    Name of the bucket to which the PUT operation was initiated.

  • :cache_control (String) —

    Specifies caching behavior along the request/reply chain.

  • :content_disposition (String) —

    Specifies presentational information for the object.

  • :content_encoding (String) —

    Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

  • :content_language (String) —

    The language the content is in.

  • :content_length (Integer) —

    Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.

  • :content_md5 (String) —

    The base64-encoded 128-bit MD5 digest of the part data.

  • :content_type (String) —

    A standard MIME type describing the format of the object data.

  • :expires (Time, DateTime, Date, Integer, String) —

    The date and time at which the object is no longer cacheable.

  • :grant_full_control (String) —

    Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

  • :grant_read (String) —

    Allows grantee to read the object data and its metadata.

  • :grant_read_acp (String) —

    Allows grantee to read the object ACL.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable object.

  • :key (required, String) —

    Object key for which the PUT operation was initiated.

  • :metadata (Hash<String,String>) —

    A map of metadata to store with the object in S3.

  • :server_side_encryption (String) —

    The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

  • :storage_class (String) —

    The type of storage to use for the object. Defaults to ‘STANDARD’.

  • :website_redirect_location (String) —

    If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :ssekms_key_id (String) —

    Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :tagging (String) —

    The tag-set for the object. The tag-set must be encoded as URL Query parameters

Returns:

See Also:



5460
5461
5462
5463
 
# File 'lib/aws-sdk-s3/client.rb', line 5460

def put_object(params = {}, options = {})
  req = build_request(:put_object, params)
  req.send_request(options)
end

#put_object_acl(params = {}) ⇒ Types::PutObjectAclOutput

uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a bucket

Examples:

Example: To grant permissions using object ACL


# The following example adds grants to an object ACL. The first permission grants user1 and user2 FULL_CONTROL and the
# AllUsers group READ permission.

resp = client.put_object_acl({
  access_control_policy: {
  }, 
  bucket: "examplebucket", 
  grant_full_control: "[email protected],[email protected]", 
  grant_read: "uri=http://acs.amazonaws.com/groups/global/AllUsers", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.put_object_acl({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
  access_control_policy: {
    grants: [
      {
        grantee: {
          display_name: "DisplayName",
          email_address: "EmailAddress",
          id: "ID",
          type: "CanonicalUser", # required, accepts CanonicalUser, AmazonCustomerByEmail, Group
          uri: "URI",
        },
        permission: "FULL_CONTROL", # accepts FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP
      },
    ],
    owner: {
      display_name: "DisplayName",
      id: "ID",
    },
  },
  bucket: "BucketName", # required
  content_md5: "ContentMD5",
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write: "GrantWrite",
  grant_write_acp: "GrantWriteACP",
  key: "ObjectKey", # required
  request_payer: "requester", # accepts requester
  version_id: "ObjectVersionId",
})

Response structure


resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :acl (String) —

    The canned ACL to apply to the object.

  • :access_control_policy (Types::AccessControlPolicy)
  • :bucket (required, String)
  • :content_md5 (String)
  • :grant_full_control (String) —

    Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.

  • :grant_read (String) —

    Allows grantee to list the objects in the bucket.

  • :grant_read_acp (String) —

    Allows grantee to read the bucket ACL.

  • :grant_write (String) —

    Allows grantee to create, overwrite, and delete any object in the bucket.

  • :grant_write_acp (String) —

    Allows grantee to write the ACL for the applicable bucket.

  • :key (required, String)
  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

  • :version_id (String) —

    VersionId used to reference a specific version of the object.

Returns:

See Also:



5571
5572
5573
5574
 
# File 'lib/aws-sdk-s3/client.rb', line 5571

def put_object_acl(params = {}, options = {})
  req = build_request(:put_object_acl, params)
  req.send_request(options)
end

#put_object_tagging(params = {}) ⇒ Types::PutObjectTaggingOutput

Sets the supplied tag-set to an object that already exists in a bucket

Examples:

Example: To add tags to an existing object


# The following example adds tags to an existing object.

resp = client.put_object_tagging({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
  tagging: {
    tag_set: [
      {
        key: "Key3", 
        value: "Value3", 
      }, 
      {
        key: "Key4", 
        value: "Value4", 
      }, 
    ], 
  }, 
})

resp.to_h outputs the following:
{
  version_id: "null", 
}

Request syntax with placeholder values


resp = client.put_object_tagging({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  version_id: "ObjectVersionId",
  content_md5: "ContentMD5",
  tagging: { # required
    tag_set: [ # required
      {
        key: "ObjectKey", # required
        value: "Value", # required
      },
    ],
  },
})

Response structure


resp.version_id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :version_id (String)
  • :content_md5 (String)
  • :tagging (required, Types::Tagging)

Returns:

See Also:



5644
5645
5646
5647
 
# File 'lib/aws-sdk-s3/client.rb', line 5644

def put_object_tagging(params = {}, options = {})
  req = build_request(:put_object_tagging, params)
  req.send_request(options)
end

#restore_object(params = {}) ⇒ Types::RestoreObjectOutput

Restores an archived copy of an object back into Amazon S3

Examples:

Example: To restore an archived object


# The following example restores for one day an archived copy of an object back into Amazon S3 bucket.

resp = client.restore_object({
  bucket: "examplebucket", 
  key: "archivedobjectkey", 
  restore_request: {
    days: 1, 
    glacier_job_parameters: {
      tier: "Expedited", 
    }, 
  }, 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.restore_object({
  bucket: "BucketName", # required
  key: "ObjectKey", # required
  version_id: "ObjectVersionId",
  restore_request: {
    days: 1,
    glacier_job_parameters: {
      tier: "Standard", # required, accepts Standard, Bulk, Expedited
    },
    type: "SELECT", # accepts SELECT
    tier: "Standard", # accepts Standard, Bulk, Expedited
    description: "Description",
    select_parameters: {
      input_serialization: { # required
        csv: {
          file_header_info: "USE", # accepts USE, IGNORE, NONE
          comments: "Comments",
          quote_escape_character: "QuoteEscapeCharacter",
          record_delimiter: "RecordDelimiter",
          field_delimiter: "FieldDelimiter",
          quote_character: "QuoteCharacter",
        },
        compression_type: "NONE", # accepts NONE, GZIP
        json: {
          type: "DOCUMENT", # accepts DOCUMENT, LINES
        },
      },
      expression_type: "SQL", # required, accepts SQL
      expression: "Expression", # required
      output_serialization: { # required
        csv: {
          quote_fields: "ALWAYS", # accepts ALWAYS, ASNEEDED
          quote_escape_character: "QuoteEscapeCharacter",
          record_delimiter: "RecordDelimiter",
          field_delimiter: "FieldDelimiter",
          quote_character: "QuoteCharacter",
        },
        json: {
          record_delimiter: "RecordDelimiter",
        },
      },
    },
    output_location: {
      s3: {
        bucket_name: "BucketName", # required
        prefix: "LocationPrefix", # required
        encryption: {
          encryption_type: "AES256", # required, accepts AES256, aws:kms
          kms_key_id: "SSEKMSKeyId",
          kms_context: "KMSContext",
        },
        canned_acl: "private", # accepts private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control
        access_control_list: [
          {
            grantee: {
              display_name: "DisplayName",
              email_address: "EmailAddress",
              id: "ID",
              type: "CanonicalUser", # required, accepts CanonicalUser, AmazonCustomerByEmail, Group
              uri: "URI",
            },
            permission: "FULL_CONTROL", # accepts FULL_CONTROL, WRITE, WRITE_ACP, READ, READ_ACP
          },
        ],
        tagging: {
          tag_set: [ # required
            {
              key: "ObjectKey", # required
              value: "Value", # required
            },
          ],
        },
        user_metadata: [
          {
            name: "MetadataKey",
            value: "MetadataValue",
          },
        ],
        storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA
      },
    },
  },
  request_payer: "requester", # accepts requester
})

Response structure


resp.request_charged #=> String, one of "requester"
resp.restore_output_path #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :key (required, String)
  • :version_id (String)
  • :restore_request (Types::RestoreRequest) —

    Container for restore job parameters.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



5788
5789
5790
5791
 
# File 'lib/aws-sdk-s3/client.rb', line 5788

def restore_object(params = {}, options = {})
  req = build_request(:restore_object, params)
  req.send_request(options)
end

#upload_part(params = {}) ⇒ Types::UploadPartOutput

Uploads a part in a multipart upload.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Examples:

Example: To upload a part


# The following example uploads part 1 of a multipart upload. The example specifies a file name for the part data. The
# Upload ID is same that is returned by the initiate multipart upload.

resp = client.upload_part({
  body: "fileToUpload", 
  bucket: "examplebucket", 
  key: "examplelargeobject", 
  part_number: 1, 
  upload_id: "xadcOB_7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--", 
})

resp.to_h outputs the following:
{
  etag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"", 
}

Request syntax with placeholder values


resp = client.upload_part({
  body: source_file,
  bucket: "BucketName", # required
  content_length: 1,
  content_md5: "ContentMD5",
  key: "ObjectKey", # required
  part_number: 1, # required
  upload_id: "MultipartUploadId", # required
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
})

Response structure


resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.etag #=> String
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :body (String, IO) —

    Object data.

  • :bucket (required, String) —

    Name of the bucket to which the multipart upload was initiated.

  • :content_length (Integer) —

    Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.

  • :content_md5 (String) —

    The base64-encoded 128-bit MD5 digest of the part data.

  • :key (required, String) —

    Object key for which the multipart upload was initiated.

  • :part_number (required, Integer) —

    Part number of part being uploaded. This is a positive integer between 1 and 10,000.

  • :upload_id (required, String) —

    Upload ID identifying the multipart upload whose part is being uploaded.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



5907
5908
5909
5910
 
# File 'lib/aws-sdk-s3/client.rb', line 5907

def upload_part(params = {}, options = {})
  req = build_request(:upload_part, params)
  req.send_request(options)
end

#upload_part_copy(params = {}) ⇒ Types::UploadPartCopyOutput

Uploads a part by copying data from an existing object as data source.

Examples:

Example: To upload a part by copying byte range from an existing object as data source


# The following example uploads a part of a multipart upload by copying a specified byte range from an existing object as
# data source.

resp = client.upload_part_copy({
  bucket: "examplebucket", 
  copy_source: "/bucketname/sourceobjectkey", 
  copy_source_range: "bytes=1-100000", 
  key: "examplelargeobject", 
  part_number: 2, 
  upload_id: "exampleuoh_10OhKhT7YukE9bjzTPRiuaCotmZM_pFngJFir9OZNrSr5cWa3cq3LZSUsfjI4FI7PkP91We7Nrw--", 
})

resp.to_h outputs the following:
{
  copy_part_result: {
    etag: "\"65d16d19e65a7508a51f043180edcc36\"", 
    last_modified: Time.parse("2016-12-29T21:44:28.000Z"), 
  }, 
}

Example: To upload a part by copying data from an existing object as data source


# The following example uploads a part of a multipart upload by copying data from an existing object as data source.

resp = client.upload_part_copy({
  bucket: "examplebucket", 
  copy_source: "/bucketname/sourceobjectkey", 
  key: "examplelargeobject", 
  part_number: 1, 
  upload_id: "exampleuoh_10OhKhT7YukE9bjzTPRiuaCotmZM_pFngJFir9OZNrSr5cWa3cq3LZSUsfjI4FI7PkP91We7Nrw--", 
})

resp.to_h outputs the following:
{
  copy_part_result: {
    etag: "\"b0c6f0e7e054ab8fa2536a2677f8734d\"", 
    last_modified: Time.parse("2016-12-29T21:24:43.000Z"), 
  }, 
}

Request syntax with placeholder values


resp = client.upload_part_copy({
  bucket: "BucketName", # required
  copy_source: "CopySource", # required
  copy_source_if_match: "CopySourceIfMatch",
  copy_source_if_modified_since: Time.now,
  copy_source_if_none_match: "CopySourceIfNoneMatch",
  copy_source_if_unmodified_since: Time.now,
  copy_source_range: "CopySourceRange",
  key: "ObjectKey", # required
  part_number: 1, # required
  upload_id: "MultipartUploadId", # required
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  copy_source_sse_customer_algorithm: "CopySourceSSECustomerAlgorithm",
  copy_source_sse_customer_key: "CopySourceSSECustomerKey",
  copy_source_sse_customer_key_md5: "CopySourceSSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
})

Response structure


resp.copy_source_version_id #=> String
resp.copy_part_result.etag #=> String
resp.copy_part_result.last_modified #=> Time
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.request_charged #=> String, one of "requester"

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :bucket (required, String)
  • :copy_source (required, String) —

    The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.

  • :copy_source_if_match (String) —

    Copies the object if its entity tag (ETag) matches the specified tag.

  • :copy_source_if_modified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it has been modified since the specified time.

  • :copy_source_if_none_match (String) —

    Copies the object if its entity tag (ETag) is different than the specified ETag.

  • :copy_source_if_unmodified_since (Time, DateTime, Date, Integer, String) —

    Copies the object if it hasn’t been modified since the specified time.

  • :copy_source_range (String) —

    The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source. You can copy a range only if the source object is greater than 5 GB.

  • :key (required, String)
  • :part_number (required, Integer) —

    Part number of part being copied. This is a positive integer between 1 and 10,000.

  • :upload_id (required, String) —

    Upload ID identifying the multipart upload whose part is being copied.

  • :sse_customer_algorithm (String) —

    Specifies the algorithm to use to when encrypting the object (e.g., AES256).

  • :sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.

  • :sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :copy_source_sse_customer_algorithm (String) —

    Specifies the algorithm to use when decrypting the source object (e.g., AES256).

  • :copy_source_sse_customer_key (String) —

    Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.

  • :copy_source_sse_customer_key_md5 (String) —

    Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.

  • :request_payer (String) —

    Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

Returns:

See Also:



6079
6080
6081
6082
 
# File 'lib/aws-sdk-s3/client.rb', line 6079

def upload_part_copy(params = {}, options = {})
  req = build_request(:upload_part_copy, params)
  req.send_request(options)
end

#wait_until(waiter_name, params = {}, options = {}) {|w.waiter| ... } ⇒ Boolean

Polls an API operation until a resource enters a desired state.

## Basic Usage

A waiter will call an API operation until:

  • It is successful

  • It enters a terminal state

  • It makes the maximum number of attempts

In between attempts, the waiter will sleep.

# polls in a loop, sleeping between attempts
client.waiter_until(waiter_name, params)

## Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You can pass configuration as the final arguments hash.

# poll for ~25 seconds
client.wait_until(waiter_name, params, {
  max_attempts: 5,
  delay: 5,
})

## Callbacks

You can be notified before each polling attempt and before each delay. If you throw ‘:success` or `:failure` from these callbacks, it will terminate the waiter.

started_at = Time.now
client.wait_until(waiter_name, params, {

  # disable max attempts
  max_attempts: nil,

  # poll for 1 hour, instead of a number of attempts
  before_wait: -> (attempts, response) do
    throw :failure if Time.now - started_at > 3600
  end
})

## Handling Errors

When a waiter is unsuccessful, it will raise an error. All of the failure errors extend from Waiters::Errors::WaiterFailed.

begin
  client.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

## Valid Waiters

The following table lists the valid waiter names, the operations they call, and the default ‘:delay` and `:max_attempts` values.

| waiter_name | params | :delay | :max_attempts | | —————– | ————– | ——– | ————- | | bucket_exists | #head_bucket | 5 | 20 | | bucket_not_exists | #head_bucket | 5 | 20 | | object_exists | #head_object | 5 | 20 | | object_not_exists | #head_object | 5 | 20 |

Parameters:

  • waiter_name (Symbol)
  • params (Hash) (defaults to: {}) —

    ({})

  • options (Hash) (defaults to: {}) —

    ({})

Options Hash (options):

  • :max_attempts (Integer)
  • :delay (Integer)
  • :before_attempt (Proc)
  • :before_wait (Proc)

Yields:

  • (w.waiter)

Returns:

  • (Boolean) —

    Returns ‘true` if the waiter was successful.

Raises:

  • (Errors::FailureStateError) —

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

  • (Errors::TooManyAttemptsError) —

    Raised when the configured maximum number of attempts have been made, and the waiter is not yet successful.

  • (Errors::UnexpectedError) —

    Raised when an error is encounted while polling for a resource that is not expected.

  • (Errors::NoSuchWaiterError) —

    Raised when you request to wait for an unknown state.



6192
6193
6194
6195
6196
 
# File 'lib/aws-sdk-s3/client.rb', line 6192

def wait_until(waiter_name, params = {}, options = {})
  w = waiter(waiter_name, options)
  yield(w.waiter) if block_given? # deprecated
  w.wait(params)
end

#waiter_names ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated. 


6200
6201
6202
 
# File 'lib/aws-sdk-s3/client.rb', line 6200

def waiter_names
  waiters.keys
end