You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::S3::Bucket

Inherits:
Resources::Resource show all
Defined in:
aws-sdk-resources/lib/aws-sdk-resources/services/s3/bucket.rb

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(name, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(name, options = {}) ⇒ Object

    Parameters:

    • name (String)

    Options Hash (options):

    • :client (Client)

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :name (required, String)
    • :client (Client)

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#creation_dateTime (readonly)

Date the bucket was created.

Returns:

  • (Time)

    Date the bucket was created.

#nameString (readonly)

Returns:

  • (String)

Instance Method Details

#aclBucketAcl

Returns:

#clear!void

This method returns an undefined value.

Deletes all objects and versioned objects from this bucket

Examples:


bucket.clear!


14
15
16
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/bucket.rb', line 14

def clear!
  object_versions.batch_delete!
end

#corsBucketCors

Returns:

#create(options = {}) ⇒ Types::CreateBucketOutput

Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a valid AWS Access Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating the bucket, you become the bucket owner.

Not every string is an acceptable bucket name. For information about bucket naming restrictions, see Working with Amazon S3 buckets.

If you want to create an Amazon S3 on Outposts bucket, see Create Bucket.

By default, the bucket is created in the US East (N. Virginia) Region. You can optionally specify a Region in the request body. You might choose a Region to optimize latency, minimize costs, or address regulatory requirements. For example, if you reside in Europe, you will probably find it advantageous to create buckets in the Europe (Ireland) Region. For more information, see Accessing a bucket.

If you send your create bucket request to the s3.amazonaws.com endpoint, the request goes to the us-east-1 Region. Accordingly, the signature calculations in Signature Version 4 must use us-east-1 as the Region, even if the location constraint in the request specifies another Region where the bucket is to be created. If you create a bucket in a Region other than US East (N. Virginia), your application must be able to handle 307 redirect. For more information, see Virtual hosting of buckets.

When creating a bucket using this operation, you can optionally specify the accounts or groups that should be granted specific permissions on the bucket. There are two ways to grant the appropriate permissions using the request headers.

  • Specify a canned ACL using the x-amz-acl request header. Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more information, see Canned ACL.

  • Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write, x-amz-grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For more information, see Access control list (ACL) overview.

    You specify each grantee as a type=value pair, where the type is one of the following:

    • id – if the value specified is the canonical user ID of an AWS account

    • uri – if you are granting permissions to a predefined group

    • emailAddress – if the value specified is the email address of an AWS account

      Using email addresses to specify a grantee is only supported in the following AWS Regions:

      • US East (N. Virginia)

      • US West (N. California)

      • US West (Oregon)

      • Asia Pacific (Singapore)

      • Asia Pacific (Sydney)

      • Asia Pacific (Tokyo)

      • Europe (Ireland)

      • South America (São Paulo)

      For a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the AWS General Reference.

    For example, the following x-amz-grant-read header grants the AWS accounts identified by account IDs permissions to read object data and its metadata:

    x-amz-grant-read: id="11112222333", id="444455556666"

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

The following operations are related to CreateBucket:

Examples:

Request syntax example with placeholder values


bucket.create({
  acl: "private", # accepts private, public-read, public-read-write, authenticated-read
  create_bucket_configuration: {
    location_constraint: "af-south-1", # accepts af-south-1, ap-east-1, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, cn-north-1, cn-northwest-1, EU, eu-central-1, eu-north-1, eu-south-1, eu-west-1, eu-west-2, eu-west-3, me-south-1, sa-east-1, us-east-2, us-gov-east-1, us-gov-west-1, us-west-1, us-west-2
  },
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write: "GrantWrite",
  grant_write_acp: "GrantWriteACP",
  object_lock_enabled_for_bucket: false,
})

Options Hash (options):

  • :acl (String)

    The canned ACL to apply to the bucket.

  • :create_bucket_configuration (Types::CreateBucketConfiguration)

    The configuration information for the bucket.

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

  • :object_lock_enabled_for_bucket (Boolean)

    Specifies whether you want S3 Object Lock to be enabled for the new bucket.

Returns:

See Also:

#delete(options = {}) ⇒ Struct

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

Related Resources

Examples:

Request syntax example with placeholder values


bucket.delete({
  expected_bucket_owner: "AccountId",
})

Options Hash (options):

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Returns:

  • (Struct)

    Returns an empty response.

See Also:

#delete!(options = { }) ⇒ void

This method returns an undefined value.

Deletes all objects and versioned objects from this bucket and then deletes the bucket.

Examples:


bucket.delete!

Parameters:

  • options (Hash) (defaults to: { })

    a customizable set of options

Options Hash (options):

  • :max_attempts (Integer) — default: 3

    Maximum number of times to attempt to delete the empty bucket before raising Aws::S3::Errors::BucketNotEmpty.

  • :initial_wait (Float) — default: 1.3

    Seconds to wait before retrying the call to delete the bucket, exponentially increased for each attempt.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/bucket.rb', line 34

def delete! options = { }
  options = {
    initial_wait: 1.3,
    max_attempts: 3,
  }.merge(options)

  attempts = 0
  begin
    clear!
    delete
  rescue Errors::BucketNotEmpty
    attempts += 1
    if attempts >= options[:max_attempts]
      raise
    else
      Kernel.sleep(options[:initial_wait] ** attempts)
      retry
    end
  end
end

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

This operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests, reducing per-request overhead.

The request contains a list of up to 1000 keys that you want to delete. In the XML, you provide the object key names, and optionally, version IDs if you want to delete a specific version of the object from a versioning-enabled bucket. For each key, Amazon S3 performs a delete operation and returns the result of that delete, success, or failure, in the response. Note that if the object specified in the request is not found, Amazon S3 returns the result as deleted.

The operation supports two modes for the response: verbose and quiet. By default, the operation uses verbose mode in which the response includes the result of deletion of each key in your request. In quiet mode the response includes only keys where the delete operation encountered an error. For a successful deletion, the operation does not return any information about the delete in the response body.

When performing this operation on an MFA Delete enabled bucket, that attempts to delete any versioned objects, you must include an MFA token. If you do not provide one, the entire request will fail, even if there are non-versioned objects you are trying to delete. If you provide an invalid token, whether there are versioned keys in the request or not, the entire Multi-Object Delete request will fail. For information about MFA Delete, see MFA Delete.

Finally, the Content-MD5 header is required for all Multi-Object Delete requests. Amazon S3 uses the header value to ensure that your request body has not been altered in transit.

The following operations are related to DeleteObjects:

Examples:

Request syntax example with placeholder values


bucket.delete_objects({
  delete: { # required
    objects: [ # required
      {
        key: "ObjectKey", # required
        version_id: "ObjectVersionId",
      },
    ],
    quiet: false,
  },
  mfa: "MFA",
  request_payer: "requester", # accepts requester
  bypass_governance_retention: false,
  expected_bucket_owner: "AccountId",
  use_accelerate_endpoint: false,
})

Options Hash (options):

  • :delete (required, Types::Delete)

    Container for the request.

  • :mfa (String)

    The concatenation of the authentication device\'s serial number, a space, and the value that is displayed on your authentication device. Required to permanently delete a versioned object if versioning is configured with MFA delete enabled.

  • :request_payer (String)

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

  • :bypass_governance_retention (Boolean)

    Specifies whether you want to delete this object even if it has a Governance-type Object Lock in place. You must have sufficient permissions to perform this operation.

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#exists?Boolean

Returns true if this Bucket exists. Returns false otherwise.

Returns:

  • (Boolean)

    Returns true if this Bucket exists. Returns false otherwise.

#lifecycleBucketLifecycle

Returns:

#lifecycle_configurationBucketLifecycleConfiguration

#loggingBucketLogging

Returns:

#multipart_uploads(options = {}) ⇒ Collection<MultipartUpload>

Returns a Collection of MultipartUpload resources. No API requests are made until you call an enumerable method on the collection. Client#list_multipart_uploads will be called multiple times until every MultipartUpload has been yielded.

Examples:

Request syntax example with placeholder values


bucket.multipart_uploads({
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  key_marker: "KeyMarker",
  max_uploads: 1,
  prefix: "Prefix",
  upload_id_marker: "UploadIdMarker",
  expected_bucket_owner: "AccountId",
  use_accelerate_endpoint: false,
})

Enumerating MultipartUpload resources.

bucket.multipart_uploads.each do |multipartupload|
  # yields each multipartupload
end

Enumerating MultipartUpload resources with a limit.

bucket.multipart_uploads.limit(10).each do |multipartupload|
  # yields at most 10 multipart_uploads
end

Options Hash (options):

  • :delimiter (String)

    Character you use to group keys.

    All keys that contain the same string between the prefix, if specified, and the first occurrence of the delimiter after the prefix are grouped under a single result element, CommonPrefixes. If you don\'t specify the prefix parameter, then the substring starts at the beginning of the key. The keys that are grouped under CommonPrefixes result element are not returned elsewhere in the response.

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

    If upload-id-marker is not specified, only the keys lexicographically greater than the specified key-marker will be included in the list.

    If upload-id-marker is specified, any multipart uploads for a key equal to the key-marker might also be included, provided those multipart uploads have upload IDs lexicographically greater than the specified upload-id-marker.

  • :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. You can use prefixes to separate a bucket into different grouping of keys. (You can think of using prefix to make groups in the same way you\'d use a folder in a file system.)

  • :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. Otherwise, any multipart uploads for a key equal to the key-marker might be included in the list only if they have an upload ID lexicographically greater than the specified upload-id-marker.

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#notificationBucketNotification

Returns:

#object(key) ⇒ Object

Parameters:

Returns:

See Also:

#object_versions(options = {}) ⇒ Collection<ObjectVersion>

Returns a Collection of ObjectVersion resources. No API requests are made until you call an enumerable method on the collection. Client#list_object_versions will be called multiple times until every ObjectVersion has been yielded.

Examples:

Request syntax example with placeholder values


bucket.object_versions({
  delimiter: "Delimiter",
  encoding_type: "url", # accepts url
  key_marker: "KeyMarker",
  max_keys: 1,
  prefix: "Prefix",
  version_id_marker: "VersionIdMarker",
  expected_bucket_owner: "AccountId",
  use_accelerate_endpoint: false,
})

Enumerating ObjectVersion resources.

bucket.object_versions.each do |objectversion|
  # yields each objectversion
end

Enumerating ObjectVersion resources with a limit.

bucket.object_versions.limit(10).each do |objectversion|
  # yields at most 10 object_versions
end

Batch operations callable on the returned collection


# calls Client#delete_objects on each batch
bucket.object_versions.batch_delete!

Options Hash (options):

  • :delimiter (String)

    A delimiter is a character that you specify to group keys. All keys that contain the same string between the prefix and the first occurrence of the delimiter are grouped under a single result element in CommonPrefixes. These groups are counted as one result against the max-keys limitation. These keys are not returned elsewhere in the response.

  • :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. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more. If additional keys satisfy the search criteria, but were not returned because max-keys was exceeded, the response contains <isTruncated>true</isTruncated>. To return the additional keys, see key-marker and version-id-marker.

  • :prefix (String)

    Use this parameter to select only those keys that begin with the specified prefix. You can use prefixes to separate a bucket into different groupings of keys. (You can think of using prefix to make groups in the same way you\'d use a folder in a file system.) You can use prefix with delimiter to roll up numerous objects into a single result under CommonPrefixes.

  • :version_id_marker (String)

    Specifies the object version you want to start listing from.

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#objects(options = {}) ⇒ Collection<ObjectSummary>

Returns a Collection of ObjectSummary resources. No API requests are made until you call an enumerable method on the collection. Client#list_objects_v2 will be called multiple times until every ObjectSummary has been yielded.

Examples:

Request syntax example with placeholder values


bucket.objects({
  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
  expected_bucket_owner: "AccountId",
  use_accelerate_endpoint: false,
})

Enumerating ObjectSummary resources.

bucket.objects.each do |objectsummary|
  # yields each objectsummary
end

Enumerating ObjectSummary resources with a limit.

bucket.objects.limit(10).each do |objectsummary|
  # yields at most 10 objects
end

Batch operations callable on the returned collection


# calls Client#delete_objects on each batch
bucket.objects.batch_delete!

Options Hash (options):

  • :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. By default the API returns up to 1,000 key names. 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.

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#policyBucketPolicy

Returns:

#presigned_post(options = {}) ⇒ PresignedPost

Note:

You must specify :key or :key_starts_with. All other options are optional.

Creates a PresignedPost that makes it easy to upload a file from a web browser direct to Amazon S3 using an HTML post form with a file field.

See the PresignedPost documentation for more information.

Options Hash (options):

Returns:

See Also:



91
92
93
94
95
96
97
98
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/bucket.rb', line 91

def presigned_post(options = {})
  PresignedPost.new(
    client.config.credentials,
    client.config.region,
    name,
    {url: url}.merge(options)
  )
end

#put_object(options = {}) ⇒ Object

Examples:

Request syntax example with placeholder values


bucket.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, # file/IO object, or string data
  cache_control: "CacheControl",
  content_disposition: "ContentDisposition",
  content_encoding: "ContentEncoding",
  content_language: "ContentLanguage",
  content_length: 1,
  content_md5: "ContentMD5",
  content_type: "ContentType",
  expires: Time.now,
  grant_full_control: "GrantFullControl",
  grant_read: "GrantRead",
  grant_read_acp: "GrantReadACP",
  grant_write_acp: "GrantWriteACP",
  key: "ObjectKey", # required
  metadata: {
    "MetadataKey" => "MetadataValue",
  },
  server_side_encryption: "AES256", # accepts AES256, aws:kms
  storage_class: "STANDARD", # accepts STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, DEEP_ARCHIVE, OUTPOSTS
  website_redirect_location: "WebsiteRedirectLocation",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  ssekms_key_id: "SSEKMSKeyId",
  ssekms_encryption_context: "SSEKMSEncryptionContext",
  request_payer: "requester", # accepts requester
  tagging: "TaggingHeader",
  object_lock_mode: "GOVERNANCE", # accepts GOVERNANCE, COMPLIANCE
  object_lock_retain_until_date: Time.now,
  object_lock_legal_hold_status: "ON", # accepts ON, OFF
  expected_bucket_owner: "AccountId",
  use_accelerate_endpoint: false,
})

Basic usage

object = bucket.put_object(options)
object.key
#=> "object-key"

Options Hash (options):

  • :acl (String)

    The canned ACL to apply to the object. For more information, see Canned ACL.

    This action is not supported by Amazon S3 on Outposts.

  • :body (IO, String)

    Object data.

  • :cache_control (String)

    Can be used to specify caching behavior along the request/reply chain. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.

  • :content_disposition (String)

    Specifies presentational information for the object. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.

  • :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. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11.

  • :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. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13.

  • :content_md5 (String)

    The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, we recommend using the Content-MD5 mechanism as an end-to-end integrity check. For more information about REST request authentication, see REST Authentication.

  • :content_type (String)

    A standard MIME type describing the format of the contents. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.

  • :expires (Time)

    The date and time at which the object is no longer cacheable. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.

  • :grant_full_control (String)

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

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read (String)

    Allows grantee to read the object data and its metadata.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_read_acp (String)

    Allows grantee to read the object ACL.

    This action is not supported by Amazon S3 on Outposts.

  • :grant_write_acp (String)

    Allows grantee to write the ACL for the applicable object.

    This action is not supported by Amazon S3 on Outposts.

  • :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 Amazon S3 (for example, AES256, aws:kms).

  • :storage_class (String)

    By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class. Amazon S3 on Outposts only uses the OUTPOSTS Storage Class. For more information, see Storage Classes in the Amazon S3 Service Developer Guide.

  • :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. For information about object metadata, see Object Key and Metadata.

    In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket:

    x-amz-website-redirect-location: /anotherPage.html

    In the following example, the request header sets the object redirect to another website:

    x-amz-website-redirect-location: http://www.example.com/

    For more information about website hosting in Amazon S3, see Hosting Websites on Amazon S3 and How to Configure Website Page Redirects.

  • :sse_customer_algorithm (String)

    Specifies the algorithm to use to when encrypting the object (for example, 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 S3 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 that the encryption key was transmitted without error.

  • :ssekms_key_id (String)

    If x-amz-server-side-encryption is present and has the value of aws:kms, this header specifies the ID of the AWS Key Management Service (AWS KMS) symmetrical customer managed customer master key (CMK) that was used for the object.

    If the value of x-amz-server-side-encryption is aws:kms, this header specifies the ID of the symmetric customer managed AWS KMS CMK that will be used for the object. If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed CMK in AWS to protect the data.

  • :ssekms_encryption_context (String)

    Specifies the AWS KMS Encryption Context to use for object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.

  • :request_payer (String)

    Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3 Developer Guide.

  • :tagging (String)

    The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, \"Key1=Value1\")

  • :object_lock_mode (String)

    The Object Lock mode that you want to apply to this object.

  • :object_lock_retain_until_date (Time)

    The date and time when you want this object\'s Object Lock to expire.

  • :object_lock_legal_hold_status (String)

    Specifies whether a legal hold will be applied to this object. For more information about S3 Object Lock, see Object Lock.

  • :expected_bucket_owner (String)

    The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

  • :use_accelerate_endpoint (Boolean)

    When true, the "https://BUCKETNAME.s3-accelerate.amazonaws.com" endpoint will be used.

Returns:

See Also:

#request_paymentBucketRequestPayment

#taggingBucketTagging

Returns:

#url(options = {}) ⇒ String

Returns a public URL for this bucket.

bucket = s3.bucket('bucket-name')
bucket.url
#=> "https://bucket-name.s3.amazonaws.com"

You can pass virtual_host: true to use the bucket name as the host name.

bucket = s3.bucket('my.bucket.com', virtual_host: true)
bucket.url
#=> "http://my.bucket.com"

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • :virtual_host (Boolean) — default: false

    When true, the bucket name will be used as the host name. This is useful when you have a CNAME configured for this bucket.

Returns:

  • (String)

    the URL for this bucket.



73
74
75
76
77
78
79
# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/bucket.rb', line 73

def url(options = {})
  if options[:virtual_host]
    "http://#{name}"
  else
    s3_bucket_url
  end
end

#versioningBucketVersioning

Returns:

#wait_until_exists {|waiter| ... } ⇒ Bucket

Waits until this Bucket is exists. This method waits by polling Client#head_bucket until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 5
#max_attempts 20

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

bucket.wait_until_exists

Yield Parameters:

Returns:

  • (Bucket)

    Returns a copy of this Bucket that is not loaded.

Raises:

See Also:

#wait_until_not_exists {|waiter| ... } ⇒ Bucket

Waits until this Bucket is not_exists. This method waits by polling Client#head_bucket until successful. An error is raised after a configurable number of failed checks.

This waiter uses the following defaults:

Configuration Default
#delay 5
#max_attempts 20

You can modify defaults and register callbacks by passing a block argument.

Examples:

Basic usage

bucket.wait_until_not_exists

Yield Parameters:

Returns:

  • (Bucket)

    Returns a copy of this Bucket that is not loaded.

Raises:

See Also:

#websiteBucketWebsite

Returns: