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. 



6003
6004
6005
 
# File 'lib/aws-sdk-s3/client.rb', line 6003

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. 



6006
6007
6008
 
# File 'lib/aws-sdk-s3/client.rb', line 6006

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: {}) 


5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
 
# File 'lib/aws-sdk-s3/client.rb', line 5862

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.0.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
  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
  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_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:



965
966
967
968
 
# File 'lib/aws-sdk-s3/client.rb', line 965

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:



995
996
997
998
 
# File 'lib/aws-sdk-s3/client.rb', line 995

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:



1022
1023
1024
1025
 
# File 'lib/aws-sdk-s3/client.rb', line 1022

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:



1052
1053
1054
1055
 
# File 'lib/aws-sdk-s3/client.rb', line 1052

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:



1082
1083
1084
1085
 
# File 'lib/aws-sdk-s3/client.rb', line 1082

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:



1112
1113
1114
1115
 
# File 'lib/aws-sdk-s3/client.rb', line 1112

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:



1142
1143
1144
1145
 
# File 'lib/aws-sdk-s3/client.rb', line 1142

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:



1218
1219
1220
1221
 
# File 'lib/aws-sdk-s3/client.rb', line 1218

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:



1282
1283
1284
1285
 
# File 'lib/aws-sdk-s3/client.rb', line 1282

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:



1417
1418
1419
1420
 
# File 'lib/aws-sdk-s3/client.rb', line 1417

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:



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

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:



1482
1483
1484
1485
 
# File 'lib/aws-sdk-s3/client.rb', line 1482

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:



1528
1529
1530
1531
 
# File 'lib/aws-sdk-s3/client.rb', line 1528

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:



1591
1592
1593
1594
 
# File 'lib/aws-sdk-s3/client.rb', line 1591

def get_bucket_cors(params = {}, options = {})
  req = build_request(:get_bucket_cors, 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"
resp.inventory_configuration.destination.s3_bucket_destination.prefix #=> 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"
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:



1635
1636
1637
1638
 
# File 'lib/aws-sdk-s3/client.rb', line 1635

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"
resp.rules[0].noncurrent_version_transition.noncurrent_days #=> Integer
resp.rules[0].noncurrent_version_transition.storage_class #=> String, one of "GLACIER", "STANDARD_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:



1698
1699
1700
1701
 
# File 'lib/aws-sdk-s3/client.rb', line 1698

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"
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"
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:



1773
1774
1775
1776
 
# File 'lib/aws-sdk-s3/client.rb', line 1773

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:



1814
1815
1816
1817
 
# File 'lib/aws-sdk-s3/client.rb', line 1814

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:



1851
1852
1853
1854
 
# File 'lib/aws-sdk-s3/client.rb', line 1851

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:



1892
1893
1894
1895
 
# File 'lib/aws-sdk-s3/client.rb', line 1892

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:



1994
1995
1996
1997
 
# File 'lib/aws-sdk-s3/client.rb', line 1994

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:



2047
2048
2049
2050
 
# File 'lib/aws-sdk-s3/client.rb', line 2047

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:



2088
2089
2090
2091
 
# File 'lib/aws-sdk-s3/client.rb', line 2088

def get_bucket_policy(params = {}, options = {})
  req = build_request(:get_bucket_policy, params)
  req.send_request(options)
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].destination.bucket #=> String
resp.replication_configuration.rules[0].destination.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA"

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_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:



2188
2189
2190
2191
 
# File 'lib/aws-sdk-s3/client.rb', line 2188

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:



2240
2241
2242
2243
 
# File 'lib/aws-sdk-s3/client.rb', line 2240

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:



2284
2285
2286
2287
 
# File 'lib/aws-sdk-s3/client.rb', line 2284

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:



2344
2345
2346
2347
 
# File 'lib/aws-sdk-s3/client.rb', line 2344

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"
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:



2595
2596
2597
2598
 
# File 'lib/aws-sdk-s3/client.rb', line 2595

def get_object(params = {}, options = {})
  req = build_request(:get_object, params)
  req.send_request(options)
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:



2700
2701
2702
2703
 
# File 'lib/aws-sdk-s3/client.rb', line 2700

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:



2783
2784
2785
2786
 
# File 'lib/aws-sdk-s3/client.rb', line 2783

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:



2840
2841
2842
2843
 
# File 'lib/aws-sdk-s3/client.rb', line 2840

def get_object_torrent(params = {}, options = {})
  req = build_request(:get_object_torrent, params)
  req.send_request(options)
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:



2871
2872
2873
2874
 
# File 'lib/aws-sdk-s3/client.rb', line 2871

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"
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:



3041
3042
3043
3044
 
# File 'lib/aws-sdk-s3/client.rb', line 3041

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:



3094
3095
3096
3097
 
# File 'lib/aws-sdk-s3/client.rb', line 3094

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"
resp.inventory_configuration_list[0].destination.s3_bucket_destination.prefix #=> 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"
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:



3147
3148
3149
3150
 
# File 'lib/aws-sdk-s3/client.rb', line 3147

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:



3197
3198
3199
3200
 
# File 'lib/aws-sdk-s3/client.rb', line 3197

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:



3252
3253
3254
3255
 
# File 'lib/aws-sdk-s3/client.rb', line 3252

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"
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:



3440
3441
3442
3443
 
# File 'lib/aws-sdk-s3/client.rb', line 3440

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:



3579
3580
3581
3582
 
# File 'lib/aws-sdk-s3/client.rb', line 3579

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"
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:



3705
3706
3707
3708
 
# File 'lib/aws-sdk-s3/client.rb', line 3705

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"
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:



3844
3845
3846
3847
 
# File 'lib/aws-sdk-s3/client.rb', line 3844

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"
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:



3967
3968
3969
3970
 
# File 'lib/aws-sdk-s3/client.rb', line 3967

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:



3995
3996
3997
3998
 
# File 'lib/aws-sdk-s3/client.rb', line 3995

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:



4076
4077
4078
4079
 
# File 'lib/aws-sdk-s3/client.rb', line 4076

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:



4138
4139
4140
4141
 
# File 'lib/aws-sdk-s3/client.rb', line 4138

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:



4218
4219
4220
4221
 
# File 'lib/aws-sdk-s3/client.rb', line 4218

def put_bucket_cors(params = {}, options = {})
  req = build_request(:put_bucket_cors, 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
        prefix: "Prefix",
      },
    },
    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
    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:



4269
4270
4271
4272
 
# File 'lib/aws-sdk-s3/client.rb', line 4269

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
        },
        noncurrent_version_transition: {
          noncurrent_days: 1,
          storage_class: "GLACIER", # accepts GLACIER, STANDARD_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:



4324
4325
4326
4327
 
# File 'lib/aws-sdk-s3/client.rb', line 4324

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
          },
        ],
        noncurrent_version_transitions: [
          {
            noncurrent_days: 1,
            storage_class: "GLACIER", # accepts GLACIER, STANDARD_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:



4426
4427
4428
4429
 
# File 'lib/aws-sdk-s3/client.rb', line 4426

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",
      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",
    },
  },
  content_md5: "ContentMD5",
})

Parameters:

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

    ({})

Options Hash (params):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4496
4497
4498
4499
 
# File 'lib/aws-sdk-s3/client.rb', line 4496

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:



4545
4546
4547
4548
 
# File 'lib/aws-sdk-s3/client.rb', line 4545

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:



4592
4593
4594
4595
 
# File 'lib/aws-sdk-s3/client.rb', line 4592

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:



4689
4690
4691
4692
 
# File 'lib/aws-sdk-s3/client.rb', line 4689

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",
  policy: "Policy", # required
})

Parameters:

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

    ({})

Options Hash (params):

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

    The bucket policy as a JSON document.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:



4728
4729
4730
4731
 
# File 'lib/aws-sdk-s3/client.rb', line 4728

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
        destination: { # required
          bucket: "BucketName", # required
          storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA
        },
      },
    ],
  },
})

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:



4793
4794
4795
4796
 
# File 'lib/aws-sdk-s3/client.rb', line 4793

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:



4839
4840
4841
4842
 
# File 'lib/aws-sdk-s3/client.rb', line 4839

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:



4894
4895
4896
4897
 
# File 'lib/aws-sdk-s3/client.rb', line 4894

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:



4943
4944
4945
4946
 
# File 'lib/aws-sdk-s3/client.rb', line 4943

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:



5014
5015
5016
5017
 
# File 'lib/aws-sdk-s3/client.rb', line 5014

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
  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:



5312
5313
5314
5315
 
# File 'lib/aws-sdk-s3/client.rb', line 5312

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:



5422
5423
5424
5425
 
# File 'lib/aws-sdk-s3/client.rb', line 5422

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:



5495
5496
5497
5498
 
# File 'lib/aws-sdk-s3/client.rb', line 5495

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, # required
    glacier_job_parameters: {
      tier: "Standard", # required, accepts Standard, Bulk, Expedited
    },
  },
  request_payer: "requester", # accepts requester
})

Response structure


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

Parameters:

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

    ({})

Options Hash (params):

Returns:

See Also:



5564
5565
5566
5567
 
# File 'lib/aws-sdk-s3/client.rb', line 5564

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:



5682
5683
5684
5685
 
# File 'lib/aws-sdk-s3/client.rb', line 5682

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:



5853
5854
5855
5856
 
# File 'lib/aws-sdk-s3/client.rb', line 5853

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.



5966
5967
5968
5969
5970
 
# File 'lib/aws-sdk-s3/client.rb', line 5966

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. 


5974
5975
5976
 
# File 'lib/aws-sdk-s3/client.rb', line 5974

def waiter_names
  waiters.keys
end