Class: Aws::S3::Client
- Inherits:
-
Seahorse::Client::Base
- Object
- Seahorse::Client::Base
- Aws::S3::Client
- Includes:
- ClientStubs
- Defined in:
- gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb
Overview
An API client for S3. To construct a client, you need to configure a :region
and :credentials
.
client = Aws::S3::Client.new(
region: region_name,
credentials: credentials,
# ...
)
For details on configuring region and credentials see the developer guide.
See #initialize for a full list of supported configuration options.
Instance Attribute Summary
Attributes inherited from Seahorse::Client::Base
API Operations collapse
-
#abort_multipart_upload(params = {}) ⇒ Types::AbortMultipartUploadOutput
This operation aborts a multipart upload.
-
#complete_multipart_upload(params = {}) ⇒ Types::CompleteMultipartUploadOutput
Completes a multipart upload by assembling previously uploaded parts.
-
#copy_object(params = {}) ⇒ Types::CopyObjectOutput
Creates a copy of an object that is already stored in Amazon S3.
-
#create_bucket(params = {}) ⇒ Types::CreateBucketOutput
This action creates an Amazon S3 bucket. -
#create_multipart_upload(params = {}) ⇒ Types::CreateMultipartUploadOutput
This action initiates a multipart upload and returns an upload ID.
-
#create_session(params = {}) ⇒ Types::CreateSessionOutput
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint API operations on directory buckets.
-
#delete_bucket(params = {}) ⇒ Struct
Deletes the S3 bucket.
-
#delete_bucket_analytics_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_cors(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_encryption(params = {}) ⇒ Struct
This implementation of the DELETE action resets the default encryption for the bucket as server-side encryption with Amazon S3 managed keys (SSE-S3).
-
#delete_bucket_intelligent_tiering_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_inventory_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_lifecycle(params = {}) ⇒ Struct
Deletes the lifecycle configuration from the specified bucket.
-
#delete_bucket_metrics_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_ownership_controls(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_policy(params = {}) ⇒ Struct
Deletes the policy of a specified bucket.
-
#delete_bucket_replication(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_tagging(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_bucket_website(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#delete_object(params = {}) ⇒ Types::DeleteObjectOutput
Removes an object from a bucket.
-
#delete_object_tagging(params = {}) ⇒ Types::DeleteObjectTaggingOutput
This operation is not supported for directory buckets. -
#delete_objects(params = {}) ⇒ Types::DeleteObjectsOutput
This operation enables you to delete multiple objects from a bucket using a single HTTP request.
-
#delete_public_access_block(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#get_bucket_accelerate_configuration(params = {}) ⇒ Types::GetBucketAccelerateConfigurationOutput
This operation is not supported for directory buckets. -
#get_bucket_acl(params = {}) ⇒ Types::GetBucketAclOutput
This operation is not supported for directory buckets. -
#get_bucket_analytics_configuration(params = {}) ⇒ Types::GetBucketAnalyticsConfigurationOutput
This operation is not supported for directory buckets. -
#get_bucket_cors(params = {}) ⇒ Types::GetBucketCorsOutput
This operation is not supported for directory buckets. -
#get_bucket_encryption(params = {}) ⇒ Types::GetBucketEncryptionOutput
Returns the default encryption configuration for an Amazon S3 bucket.
-
#get_bucket_intelligent_tiering_configuration(params = {}) ⇒ Types::GetBucketIntelligentTieringConfigurationOutput
This operation is not supported for directory buckets. -
#get_bucket_inventory_configuration(params = {}) ⇒ Types::GetBucketInventoryConfigurationOutput
This operation is not supported for directory buckets. -
#get_bucket_lifecycle(params = {}) ⇒ Types::GetBucketLifecycleOutput
For an updated version of this API, see [GetBucketLifecycleConfiguration][1].
-
#get_bucket_lifecycle_configuration(params = {}) ⇒ Types::GetBucketLifecycleConfigurationOutput
Returns the lifecycle configuration information set on the bucket.
-
#get_bucket_location(params = {}) ⇒ Types::GetBucketLocationOutput
This operation is not supported for directory buckets. -
#get_bucket_logging(params = {}) ⇒ Types::GetBucketLoggingOutput
This operation is not supported for directory buckets. -
#get_bucket_metrics_configuration(params = {}) ⇒ Types::GetBucketMetricsConfigurationOutput
This operation is not supported for directory buckets. -
#get_bucket_notification(params = {}) ⇒ Types::NotificationConfigurationDeprecated
This operation is not supported for directory buckets. -
#get_bucket_notification_configuration(params = {}) ⇒ Types::NotificationConfiguration
This operation is not supported for directory buckets. -
#get_bucket_ownership_controls(params = {}) ⇒ Types::GetBucketOwnershipControlsOutput
This operation is not supported for directory buckets. -
#get_bucket_policy(params = {}) ⇒ Types::GetBucketPolicyOutput
Returns the policy of a specified bucket.
-
#get_bucket_policy_status(params = {}) ⇒ Types::GetBucketPolicyStatusOutput
This operation is not supported for directory buckets. -
#get_bucket_replication(params = {}) ⇒ Types::GetBucketReplicationOutput
This operation is not supported for directory buckets. -
#get_bucket_request_payment(params = {}) ⇒ Types::GetBucketRequestPaymentOutput
This operation is not supported for directory buckets. -
#get_bucket_tagging(params = {}) ⇒ Types::GetBucketTaggingOutput
This operation is not supported for directory buckets. -
#get_bucket_versioning(params = {}) ⇒ Types::GetBucketVersioningOutput
This operation is not supported for directory buckets. -
#get_bucket_website(params = {}) ⇒ Types::GetBucketWebsiteOutput
This operation is not supported for directory buckets. -
#get_object(params = {}) ⇒ Types::GetObjectOutput
Retrieves an object from Amazon S3.
-
#get_object_acl(params = {}) ⇒ Types::GetObjectAclOutput
This operation is not supported for directory buckets. -
#get_object_attributes(params = {}) ⇒ Types::GetObjectAttributesOutput
Retrieves all the metadata from an object without returning the object itself.
-
#get_object_legal_hold(params = {}) ⇒ Types::GetObjectLegalHoldOutput
This operation is not supported for directory buckets. -
#get_object_lock_configuration(params = {}) ⇒ Types::GetObjectLockConfigurationOutput
This operation is not supported for directory buckets. -
#get_object_retention(params = {}) ⇒ Types::GetObjectRetentionOutput
This operation is not supported for directory buckets. -
#get_object_tagging(params = {}) ⇒ Types::GetObjectTaggingOutput
This operation is not supported for directory buckets. -
#get_object_torrent(params = {}) ⇒ Types::GetObjectTorrentOutput
This operation is not supported for directory buckets. -
#get_public_access_block(params = {}) ⇒ Types::GetPublicAccessBlockOutput
This operation is not supported for directory buckets. -
#head_bucket(params = {}) ⇒ Types::HeadBucketOutput
You can use this operation to determine if a bucket exists and if you have permission to access it.
-
#head_object(params = {}) ⇒ Types::HeadObjectOutput
The
HEAD
operation retrieves metadata from an object without returning the object itself. -
#list_bucket_analytics_configurations(params = {}) ⇒ Types::ListBucketAnalyticsConfigurationsOutput
This operation is not supported for directory buckets. -
#list_bucket_intelligent_tiering_configurations(params = {}) ⇒ Types::ListBucketIntelligentTieringConfigurationsOutput
This operation is not supported for directory buckets. -
#list_bucket_inventory_configurations(params = {}) ⇒ Types::ListBucketInventoryConfigurationsOutput
This operation is not supported for directory buckets. -
#list_bucket_metrics_configurations(params = {}) ⇒ Types::ListBucketMetricsConfigurationsOutput
This operation is not supported for directory buckets. -
#list_buckets(params = {}) ⇒ Types::ListBucketsOutput
This operation is not supported for directory buckets. -
#list_directory_buckets(params = {}) ⇒ Types::ListDirectoryBucketsOutput
Returns a list of all Amazon S3 directory buckets owned by the authenticated sender of the request.
-
#list_multipart_uploads(params = {}) ⇒ Types::ListMultipartUploadsOutput
This operation lists in-progress multipart uploads in a bucket.
-
#list_object_versions(params = {}) ⇒ Types::ListObjectVersionsOutput
This operation is not supported for directory buckets. -
#list_objects(params = {}) ⇒ Types::ListObjectsOutput
This operation is not supported for directory buckets. -
#list_objects_v2(params = {}) ⇒ Types::ListObjectsV2Output
Returns some or all (up to 1,000) of the objects in a bucket with each request.
-
#list_parts(params = {}) ⇒ Types::ListPartsOutput
Lists the parts that have been uploaded for a specific multipart upload.
-
#put_bucket_accelerate_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_acl(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_analytics_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_cors(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_encryption(params = {}) ⇒ Struct
This operation configures default encryption and Amazon S3 Bucket Keys for an existing bucket.
-
#put_bucket_intelligent_tiering_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_inventory_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_lifecycle(params = {}) ⇒ Struct
For an updated version of this API, see [PutBucketLifecycleConfiguration][1].
-
#put_bucket_lifecycle_configuration(params = {}) ⇒ Types::PutBucketLifecycleConfigurationOutput
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.
-
#put_bucket_logging(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_metrics_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_notification(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_notification_configuration(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_ownership_controls(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_policy(params = {}) ⇒ Struct
Applies an Amazon S3 bucket policy to an Amazon S3 bucket.
-
#put_bucket_replication(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_request_payment(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_tagging(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_versioning(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_bucket_website(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#put_object(params = {}) ⇒ Types::PutObjectOutput
Adds an object to a bucket.
-
#put_object_acl(params = {}) ⇒ Types::PutObjectAclOutput
This operation is not supported for directory buckets. -
#put_object_legal_hold(params = {}) ⇒ Types::PutObjectLegalHoldOutput
This operation is not supported for directory buckets. -
#put_object_lock_configuration(params = {}) ⇒ Types::PutObjectLockConfigurationOutput
This operation is not supported for directory buckets. -
#put_object_retention(params = {}) ⇒ Types::PutObjectRetentionOutput
This operation is not supported for directory buckets. -
#put_object_tagging(params = {}) ⇒ Types::PutObjectTaggingOutput
This operation is not supported for directory buckets. -
#put_public_access_block(params = {}) ⇒ Struct
This operation is not supported for directory buckets. -
#restore_object(params = {}) ⇒ Types::RestoreObjectOutput
This operation is not supported for directory buckets. -
#select_object_content(params = {}) ⇒ Types::SelectObjectContentOutput
This operation is not supported for directory buckets. -
#upload_part(params = {}) ⇒ Types::UploadPartOutput
Uploads a part in a multipart upload.
-
#upload_part_copy(params = {}) ⇒ Types::UploadPartCopyOutput
Uploads a part by copying data from an existing object as data source.
-
#write_get_object_response(params = {}) ⇒ Struct
This operation is not supported for directory buckets.
Instance Method Summary collapse
-
#initialize(options) ⇒ Client
constructor
A new instance of Client.
-
#wait_until(waiter_name, params = {}, options = {}) {|w.waiter| ... } ⇒ Boolean
Polls an API operation until a resource enters a desired state.
Methods included from ClientStubs
#api_requests, #stub_data, #stub_responses
Methods inherited from Seahorse::Client::Base
add_plugin, api, clear_plugins, define, new, #operation_names, plugins, remove_plugin, set_api, set_plugins
Methods included from Seahorse::Client::HandlerBuilder
#handle, #handle_request, #handle_response
Constructor Details
#initialize(options) ⇒ Client
Returns a new instance of Client.
551 552 553 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 551 def initialize(*args) super end |
Instance Method Details
#abort_multipart_upload(params = {}) ⇒ Types::AbortMultipartUploadOutput
This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.
To verify that all parts have been removed and prevent getting charged for the part storage, you should call the ListParts API operation and ensure that the parts list is empty.
ListMultipartUploads
operation to list the in-progress multipart uploads in the bucket
and use the AbortMultipartUpload
operation to abort all the
in-progress multipart uploads.
- Directory buckets - For directory buckets, you must make
requests for this API operation to the Zonal endpoint. These
endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - For information about permissions required to use the multipart upload, see Multipart Upload and Permissions in the Amazon S3 User Guide.
Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to AbortMultipartUpload
:
756 757 758 759 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 756 def abort_multipart_upload(params = {}, = {}) req = build_request(:abort_multipart_upload, params) req.send_request() end |
#complete_multipart_upload(params = {}) ⇒ Types::CompleteMultipartUploadOutput
Completes a multipart upload by assembling previously uploaded parts.
You first initiate the multipart upload and then upload all parts
using the UploadPart operation or the UploadPartCopy
operation. After successfully uploading all relevant parts of an
upload, you call this CompleteMultipartUpload
operation to complete
the upload. Upon receiving this request, Amazon S3 concatenates all
the parts in ascending order by part number to create a new object. In
the CompleteMultipartUpload request, you must provide the parts list
and ensure that the parts list is complete. The
CompleteMultipartUpload API operation concatenates the parts that you
provide in the list. For each part in the list, you must provide the
PartNumber
value and the ETag
value that are returned after that
part was uploaded.
The processing of a CompleteMultipartUpload request could take several
minutes to finalize. After Amazon S3 begins processing the request, it
sends an HTTP response header that specifies a 200 OK
response.
While processing is in progress, Amazon S3 periodically sends white
space characters to keep the connection from timing out. A request
could fail after the initial 200 OK
response has been sent. This
means that a 200 OK
response can contain either a success or an
error. The error response might be embedded in the 200 OK
response.
If you call this API operation directly, make sure to design your
application to parse the contents of the response and handle it
appropriately. If you use Amazon Web Services SDKs, SDKs handle this
condition. The SDKs detect the embedded error and apply error handling
per your configuration settings (including automatically retrying the
request as appropriate). If the condition persists, the SDKs throw an
exception (or, for the SDKs that don't use exceptions, they return an
error).
Note that if CompleteMultipartUpload
fails, applications should be
prepared to retry any failed requests (including 500 error responses).
For more information, see Amazon S3 Error Best Practices.
You can't use Content-Type: application/x-www-form-urlencoded
for
the CompleteMultipartUpload requests. Also, if you don't provide a
Content-Type
header, CompleteMultipartUpload
can still return a
200 OK
response.
For more information about multipart uploads, see Uploading Objects Using Multipart Upload in the Amazon S3 User Guide.
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
.
Path-style requests are not supported. For more information, see
Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - For information about permissions required to use the multipart upload API, see Multipart Upload and Permissions in the Amazon S3 User Guide.
If you provide an additional checksum value in your
MultipartUpload
requests and the object is encrypted with Key Management Service, you must have permission to use thekms:Decrypt
action for theCompleteMultipartUpload
request to succeed.Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.If the object is encrypted with SSE-KMS, you must also have the
kms:GenerateDataKey
andkms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the KMS key.
- Special errors
Error Code:
EntityTooSmall
Description: Your proposed upload is smaller than the minimum allowed object size. Each part must be at least 5 MB in size, except the last part.
HTTP Status Code: 400 Bad Request
Error Code:
InvalidPart
Description: One or more of the specified parts could not be found. The part might not have been uploaded, or the specified ETag might not have matched the uploaded part's ETag.
HTTP Status Code: 400 Bad Request
Error Code:
InvalidPartOrder
Description: The list of parts was not in ascending order. The parts list must be specified in order by part number.
HTTP Status Code: 400 Bad Request
Error Code:
NoSuchUpload
Description: The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed.
HTTP Status Code: 404 Not Found
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to CompleteMultipartUpload
:
1187 1188 1189 1190 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 1187 def complete_multipart_upload(params = {}, = {}) req = build_request(:complete_multipart_upload, params) req.send_request() end |
#copy_object(params = {}) ⇒ Types::CopyObjectOutput
Creates a copy of an object that is already stored in Amazon S3.
You can copy individual objects between general purpose buckets, between directory buckets, and between general purpose buckets and directory buckets.
Directory buckets - For directory buckets, you must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.VPC endpoints don't support cross-Region requests (including copies). If you're using VPC endpoints, your source and destination buckets should be in the same Amazon Web Services Region as your VPC endpoint.
Both the Region that you want to copy the object from and the Region that you want to copy the object to must be enabled for your account. For more information about how to enable a Region for your account, see Enable or disable a Region for standalone accounts in the Amazon Web Services Account Management Guide.
Amazon S3 transfer acceleration does not support cross-Region copies.
If you request a cross-Region copy using a transfer acceleration
endpoint, you get a 400 Bad Request
error. For more information, see
Transfer Acceleration.
- Authentication and authorization
All
CopyObject
requests must be authenticated and signed by using IAM credentials (access key ID and secret access key for the IAM identities). All headers with thex-amz-
prefix, includingx-amz-copy-source
, must be signed. For more information, see REST Authentication.Directory buckets - You must use the IAM credentials to authenticate and authorize your access to the
CopyObject
API operation, instead of using the temporary security credentials through theCreateSession
API operation.Amazon Web Services CLI or SDKs handles authentication and authorization on your behalf.
- Permissions
You must have read access to the source object and write access to the destination bucket.
General purpose bucket permissions - You must have permissions in an IAM policy based on the source and destination bucket types in a
CopyObject
operation.If the source object is in a general purpose bucket, you must have
s3:GetObject
permission to read the source object that is being copied.If the destination bucket is a general purpose bucket, you must have
s3:PutObject
permission to write the object copy to the destination bucket.
Directory bucket permissions - You must have permissions in a bucket policy or an IAM identity-based policy based on the source and destination bucket types in a
CopyObject
operation.If the source object that you want to copy is in a directory bucket, you must have the
s3express:CreateSession
permission in theAction
element of a policy to read the object. By default, the session is in theReadWrite
mode. If you want to restrict the access, you can explicitly set thes3express:SessionMode
condition key toReadOnly
on the copy source bucket.If the copy destination is a directory bucket, you must have the
s3express:CreateSession
permission in theAction
element of a policy to write the object to the destination. Thes3express:SessionMode
condition key can't be set toReadOnly
on the copy destination bucket. If the object is encrypted with SSE-KMS, you must also have thekms:GenerateDataKey
andkms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the KMS key.
For example policies, see Example bucket policies for S3 Express One Zone and Amazon Web Services Identity and Access Management (IAM) identity-based policies for S3 Express One Zone in the Amazon S3 User Guide.
- Response and special errors
When the request is an HTTP 1.1 request, the response is chunk encoded. When the request is not an HTTP 1.1 request, the response would not contain the
Content-Length
. You always need to read the entire response body to check if the copy succeeds.If the copy is successful, you receive a response with information about the copied object.
A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3 is copying the files. A
200 OK
response can contain either a success or an error.If the error occurs before the copy action starts, you receive a standard Amazon S3 error.
If the error occurs during the copy operation, the error response is embedded in the
200 OK
response. For example, in a cross-region copy, you may encounter throttling and receive a200 OK
response. For more information, see Resolve the Error 200 response when copying objects to Amazon S3. The200 OK
status code means the copy was accepted, but it doesn't mean the copy is complete. Another example is when you disconnect from Amazon S3 before the copy is complete, Amazon S3 might cancel the copy and you may receive a200 OK
response. You must stay connected to Amazon S3 until the entire response is successfully received and processed.If you call this API operation directly, make sure to design your application to parse the content of the response and handle it appropriately. If you use Amazon Web Services SDKs, SDKs handle this condition. The SDKs detect the embedded error and apply error handling per your configuration settings (including automatically retrying the request as appropriate). If the condition persists, the SDKs throw an exception (or, for the SDKs that don't use exceptions, they return an error).
- Charge
The copy request charge is based on the storage class and Region that you specify for the destination object. The request can also result in a data retrieval charge for the source if the source storage class bills for data retrieval. If the copy source is in a different region, the data transfer is billed to the copy source account. For pricing information, see Amazon S3 pricing.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to CopyObject
:
2230 2231 2232 2233 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 2230 def copy_object(params = {}, = {}) req = build_request(:copy_object, params) req.send_request() end |
#create_bucket(params = {}) ⇒ Types::CreateBucketOutput
CreateBucket
.
Creates a new S3 bucket. To create a bucket, you must set up Amazon S3 and have a valid Amazon Web Services Access Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating the bucket, you become the bucket owner.
There are two types of buckets: general purpose buckets and directory buckets. For more information about these bucket types, see Creating, configuring, and working with Amazon S3 buckets in the Amazon S3 User Guide.
CreateBucket
request to the s3.amazonaws.com
global endpoint, the request goes
to the us-east-1
Region. So 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 in the Amazon S3 User Guide.
- Directory buckets - For directory buckets, you must make
requests for this API operation to the Regional endpoint. These
endpoints support path-style requests in the format
https://s3express-control.region_code.amazonaws.com/bucket-name
. Virtual-hosted-style requests aren't supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - In addition to the
s3:CreateBucket
permission, the following permissions are required in a policy when yourCreateBucket
request includes specific headers:Access control lists (ACLs) - In your
CreateBucket
request, if you specify an access control list (ACL) and set it topublic-read
,public-read-write
,authenticated-read
, or if you explicitly specify any other custom ACLs, boths3:CreateBucket
ands3:PutBucketAcl
permissions are required. In yourCreateBucket
request, if you set the ACL toprivate
, or if you don't specify any ACLs, only thes3:CreateBucket
permission is required.Object Lock - In your
CreateBucket
request, if you setx-amz-bucket-object-lock-enabled
to true, thes3:PutBucketObjectLockConfiguration
ands3:PutBucketVersioning
permissions are required.S3 Object Ownership - If your
CreateBucket
request includes thex-amz-object-ownership
header, then thes3:PutBucketOwnershipControls
permission is required.To set an ACL on a bucket as part of a
CreateBucket
request, you must explicitly set S3 Object Ownership for the bucket to a different value than the default,BucketOwnerEnforced
. Additionally, if your desired bucket ACL grants public access, you must first create the bucket (without the bucket ACL) and then explicitly disable Block Public Access on the bucket before usingPutBucketAcl
to set the ACL. If you try to create a bucket with a public ACL, the request will fail.For the majority of modern use cases in S3, we recommend that you keep all Block Public Access settings enabled and keep ACLs disabled. If you would like to share data with users outside of your account, you can use bucket policies as needed. For more information, see Controlling ownership of objects and disabling ACLs for your bucket and Blocking public access to your Amazon S3 storage in the Amazon S3 User Guide.
S3 Block Public Access - If your specific use case requires granting public access to your S3 resources, you can disable Block Public Access. Specifically, you can create a new bucket with Block Public Access enabled, then separately call the
DeletePublicAccessBlock
API. To use this operation, you must have thes3:PutBucketPublicAccessBlock
permission. For more information about S3 Block Public Access, see Blocking public access to your Amazon S3 storage in the Amazon S3 User Guide.
Directory bucket permissions - You must have the
s3express:CreateBucket
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.The permissions for ACLs, Object Lock, S3 Object Ownership, and S3 Block Public Access are not supported for directory buckets. For directory buckets, all Block Public Access settings are enabled at the bucket level and S3 Object Ownership is set to Bucket owner enforced (ACLs disabled). These settings can't be modified.
For more information about permissions for creating and working with directory buckets, see Directory buckets in the Amazon S3 User Guide. For more information about supported S3 features for directory buckets, see Features of S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following operations are related to CreateBucket
:
2549 2550 2551 2552 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 2549 def create_bucket(params = {}, = {}) req = build_request(:create_bucket, params) req.send_request() end |
#create_multipart_upload(params = {}) ⇒ Types::CreateMultipartUploadOutput
This action initiates a multipart upload and returns an upload ID. This upload ID is used to associate all of the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests (see UploadPart). You also include this upload ID in the final request to either complete or abort the multipart upload request. For more information about multipart uploads, see Multipart Upload Overview in the Amazon S3 User Guide.
If you have configured a lifecycle rule to abort incomplete multipart uploads, the created multipart upload must be completed within the number of days specified in the bucket lifecycle configuration. Otherwise, the incomplete multipart upload becomes eligible for an abort action and Amazon S3 aborts the multipart upload. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Configuration.
- Directory buckets - For directory buckets, you must make
requests for this API operation to the Zonal endpoint. These
endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Request signing
For request signing, multipart upload is just a series of regular requests. You initiate a multipart upload, send one or more requests to upload parts, and then complete the multipart upload process. You sign each request individually. There is nothing special about signing multipart upload requests. For more information about signing, see Authenticating Requests (Amazon Web Services Signature Version 4) in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - To perform a multipart upload with encryption using an Key Management Service (KMS) KMS key, the requester must have permission to the
kms:Decrypt
andkms:GenerateDataKey
actions on the key. The requester must also have permissions for thekms:GenerateDataKey
action for theCreateMultipartUpload
API. Then, the requester needs permissions for thekms:Decrypt
action on theUploadPart
andUploadPartCopy
APIs. These permissions are required because Amazon S3 must decrypt and read data from the encrypted file parts before it completes the multipart upload. For more information, see Multipart upload API and permissions and Protecting data using server-side encryption with Amazon Web Services KMS in the Amazon S3 User Guide.Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.
- Encryption
General purpose buckets - Server-side encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its data centers and decrypts it when you access it. Amazon S3 automatically encrypts all new objects that are uploaded to an S3 bucket. When doing a multipart upload, if you don't specify encryption information in your request, the encryption setting of the uploaded parts is set to the default encryption configuration of the destination bucket. By default, all buckets have a base level of encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). If the destination bucket has a default encryption configuration that uses server-side encryption with an Key Management Service (KMS) key (SSE-KMS), or a customer-provided encryption key (SSE-C), Amazon S3 uses the corresponding KMS key, or a customer-provided key to encrypt the uploaded parts. When you perform a CreateMultipartUpload operation, if you want to use a different type of encryption setting for the uploaded parts, you can request that Amazon S3 encrypts the object with a different encryption key (such as an Amazon S3 managed key, a KMS key, or a customer-provided key). When the encryption setting in your request is different from the default encryption configuration of the destination bucket, the encryption setting in your request takes precedence. If you choose to provide your own encryption key, the request headers you provide in UploadPart and UploadPartCopy requests must match the headers you used in the
CreateMultipartUpload
request.Use KMS keys (SSE-KMS) that include the Amazon Web Services managed key (
aws/s3
) and KMS customer managed keys stored in Key Management Service (KMS) – If you want Amazon Web Services to manage the keys used to encrypt data, specify the following headers in the request.x-amz-server-side-encryption
x-amz-server-side-encryption-aws-kms-key-id
x-amz-server-side-encryption-context
* If you specify x-amz-server-side-encryption:aws:kms
, but don't providex-amz-server-side-encryption-aws-kms-key-id
, Amazon S3 uses the Amazon Web Services managed key (aws/s3
key) in KMS to protect the data.To perform a multipart upload with encryption by using an Amazon Web Services KMS key, the requester must have permission to the
kms:Decrypt
andkms:GenerateDataKey*
actions on the key. These permissions are required because Amazon S3 must decrypt and read data from the encrypted file parts before it completes the multipart upload. For more information, see Multipart upload API and permissions and Protecting data using server-side encryption with Amazon Web Services KMS in the Amazon S3 User Guide.If your Identity and Access Management (IAM) user or role is in the same Amazon Web Services account as the KMS key, then you must have these permissions on the key policy. If your IAM user or role is in a different account from the key, then you must have the permissions on both the key policy and your IAM user or role.
All
GET
andPUT
requests for an object protected by KMS fail if you don't make them by using Secure Sockets Layer (SSL), Transport Layer Security (TLS), or Signature Version 4. For information about configuring any of the officially supported Amazon Web Services SDKs and Amazon Web Services CLI, see Specifying the Signature Version in Request Authentication in the Amazon S3 User Guide.
For more information about server-side encryption with KMS keys (SSE-KMS), see Protecting Data Using Server-Side Encryption with KMS keys in the Amazon S3 User Guide.
Use customer-provided encryption keys (SSE-C) – If you want to manage your own encryption keys, provide all the following headers in the request.
x-amz-server-side-encryption-customer-algorithm
x-amz-server-side-encryption-customer-key
x-amz-server-side-encryption-customer-key-MD5
For more information about server-side encryption with customer-provided encryption keys (SSE-C), see Protecting data using server-side encryption with customer-provided encryption keys (SSE-C) in the Amazon S3 User Guide.
Directory buckets - For directory buckets, there are only two supported options for server-side encryption: server-side encryption with Amazon S3 managed keys (SSE-S3) (
AES256
) and server-side encryption with KMS keys (SSE-KMS) (aws:kms
). We recommend that the bucket's default encryption uses the desired encryption configuration and you don't override the bucket default encryption in yourCreateSession
requests orPUT
object requests. Then, new objects are automatically encrypted with the desired encryption settings. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide. For more information about the encryption overriding behaviors in directory buckets, see Specifying server-side encryption with KMS for new object uploads.In the Zonal endpoint API calls (except CopyObject and UploadPartCopy) using the REST API, the encryption request headers must match the encryption settings that are specified in the
CreateSession
request. You can't override the values of the encryption settings (x-amz-server-side-encryption
,x-amz-server-side-encryption-aws-kms-key-id
,x-amz-server-side-encryption-context
, andx-amz-server-side-encryption-bucket-key-enabled
) that are specified in theCreateSession
request. You don't need to explicitly specify these encryption settings values in Zonal endpoint API calls, and Amazon S3 will use the encryption settings values from theCreateSession
request to protect new objects in the directory bucket.When you use the CLI or the Amazon Web Services SDKs, for CreateSession
, the session token refreshes automatically to avoid service interruptions when a session expires. The CLI or the Amazon Web Services SDKs use the bucket's default encryption configuration for theCreateSession
request. It's not supported to override the encryption settings values in theCreateSession
request. So in the Zonal endpoint API calls (except CopyObject and UploadPartCopy), the encryption request headers must match the default encryption configuration of the directory bucket.For directory buckets, when you perform a CreateMultipartUpload
operation and anUploadPartCopy
operation, the request headers you provide in theCreateMultipartUpload
request must match the default encryption configuration of the destination bucket.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to CreateMultipartUpload
:
3493 3494 3495 3496 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 3493 def create_multipart_upload(params = {}, = {}) req = build_request(:create_multipart_upload, params) req.send_request() end |
#create_session(params = {}) ⇒ Types::CreateSessionOutput
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint API operations on directory buckets. For more information about Zonal endpoint API operations that include the Availability Zone in the request endpoint, see S3 Express One Zone APIs in the Amazon S3 User Guide.
To make Zonal endpoint API requests on a directory bucket, use the
CreateSession
API operation. Specifically, you grant
s3express:CreateSession
permission to a bucket in a bucket policy or
an IAM identity-based policy. Then, you use IAM credentials to make
the CreateSession
API request on the bucket, which returns temporary
security credentials that include the access key ID, secret access
key, session token, and expiration. These credentials have associated
permissions to access the Zonal endpoint API operations. After the
session is created, you don’t need to use other policies to grant
permissions to each Zonal endpoint API individually. Instead, in your
Zonal endpoint API requests, you sign your requests by applying the
temporary security credentials of the session to the request headers
and following the SigV4 protocol for authentication. You also apply
the session token to the x-amz-s3session-token
request header for
authorization. Temporary security credentials are scoped to the bucket
and expire after 5 minutes. After the expiration time, any calls that
you make with those credentials will fail. You must use IAM
credentials again to make a CreateSession
API request that generates
a new set of temporary credentials for use. Temporary credentials
cannot be extended or refreshed beyond the original specified
interval.
If you use Amazon Web Services SDKs, SDKs handle the session token refreshes automatically to avoid service interruptions when a session expires. We recommend that you use the Amazon Web Services SDKs to initiate and manage requests to the CreateSession API. For more information, see Performance guidelines and design patterns in the Amazon S3 User Guide.
https://bucket_name.s3express-az_id.region.amazonaws.com
.
Path-style requests are not supported. For more information, see
Regional and Zonal endpoints in the Amazon S3 User Guide.
CopyObject
API operation - Unlike other Zonal endpoint API operations, theCopyObject
API operation doesn't use the temporary security credentials returned from theCreateSession
API operation for authentication and authorization. For information about authentication and authorization of theCopyObject
API operation on directory buckets, see CopyObject.HeadBucket
API operation - Unlike other Zonal endpoint API operations, theHeadBucket
API operation doesn't use the temporary security credentials returned from theCreateSession
API operation for authentication and authorization. For information about authentication and authorization of theHeadBucket
API operation on directory buckets, see HeadBucket.
- Permissions
To obtain temporary security credentials, you must create a bucket policy or an IAM identity-based policy that grants
s3express:CreateSession
permission to the bucket. In a policy, you can have thes3express:SessionMode
condition key to control who can create aReadWrite
orReadOnly
session. For more information aboutReadWrite
orReadOnly
sessions, seex-amz-create-session-mode
. For example policies, see Example bucket policies for S3 Express One Zone and Amazon Web Services Identity and Access Management (IAM) identity-based policies for S3 Express One Zone in the Amazon S3 User Guide.To grant cross-account access to Zonal endpoint API operations, the bucket policy should also grant both accounts the
s3express:CreateSession
permission.If you want to encrypt objects with SSE-KMS, you must also have the
kms:GenerateDataKey
and thekms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the target KMS key.- Encryption
For directory buckets, there are only two supported options for server-side encryption: server-side encryption with Amazon S3 managed keys (SSE-S3) (
AES256
) and server-side encryption with KMS keys (SSE-KMS) (aws:kms
). We recommend that the bucket's default encryption uses the desired encryption configuration and you don't override the bucket default encryption in yourCreateSession
requests orPUT
object requests. Then, new objects are automatically encrypted with the desired encryption settings. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide. For more information about the encryption overriding behaviors in directory buckets, see Specifying server-side encryption with KMS for new object uploads.For Zonal endpoint (object-level) API operations except CopyObject and UploadPartCopy, you authenticate and authorize requests through CreateSession for low latency. To encrypt new objects in a directory bucket with SSE-KMS, you must specify SSE-KMS as the directory bucket's default encryption configuration with a KMS key (specifically, a customer managed key). Then, when a session is created for Zonal endpoint API operations, new objects are automatically encrypted and decrypted with SSE-KMS and S3 Bucket Keys during the session.
Only 1 customer managed key is supported per directory bucket for the lifetime of the bucket. The Amazon Web Services managed key ( aws/s3
) isn't supported. After you specify SSE-KMS as your bucket's default encryption configuration with a customer managed key, you can't change the customer managed key for the bucket's SSE-KMS configuration.In the Zonal endpoint API calls (except CopyObject and UploadPartCopy) using the REST API, you can't override the values of the encryption settings (
x-amz-server-side-encryption
,x-amz-server-side-encryption-aws-kms-key-id
,x-amz-server-side-encryption-context
, andx-amz-server-side-encryption-bucket-key-enabled
) from theCreateSession
request. You don't need to explicitly specify these encryption settings values in Zonal endpoint API calls, and Amazon S3 will use the encryption settings values from theCreateSession
request to protect new objects in the directory bucket.When you use the CLI or the Amazon Web Services SDKs, for CreateSession
, the session token refreshes automatically to avoid service interruptions when a session expires. The CLI or the Amazon Web Services SDKs use the bucket's default encryption configuration for theCreateSession
request. It's not supported to override the encryption settings values in theCreateSession
request. Also, in the Zonal endpoint API calls (except CopyObject and UploadPartCopy), it's not supported to override the values of the encryption settings from theCreateSession
request.- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
3782 3783 3784 3785 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 3782 def create_session(params = {}, = {}) req = build_request(:create_session, params) req.send_request() end |
#delete_bucket(params = {}) ⇒ 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.
- Directory buckets - For directory buckets, you must make
requests for this API operation to the Regional endpoint. These
endpoints support path-style requests in the format
https://s3express-control.region_code.amazonaws.com/bucket-name
. Virtual-hosted-style requests aren't supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - You must have the
s3:DeleteBucket
permission on the specified bucket in a policy.Directory bucket permissions - You must have the
s3express:DeleteBucket
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following operations are related to DeleteBucket
:
3887 3888 3889 3890 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 3887 def delete_bucket(params = {}, = {}) req = build_request(:delete_bucket, params) req.send_request() end |
#delete_bucket_analytics_configuration(params = {}) ⇒ Struct
Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).
To use this operation, you must have permissions to perform the
s3:PutAnalyticsConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.
For information about the Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis.
The following operations are related to
DeleteBucketAnalyticsConfiguration
:
3953 3954 3955 3956 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 3953 def delete_bucket_analytics_configuration(params = {}, = {}) req = build_request(:delete_bucket_analytics_configuration, params) req.send_request() end |
#delete_bucket_cors(params = {}) ⇒ Struct
Deletes the cors
configuration information set for the bucket.
To use this operation, you must have permission to perform the
s3:PutBucketCORS
action. The bucket owner has this permission by
default and can grant this permission to others.
For information about cors
, see Enabling Cross-Origin Resource
Sharing in the Amazon S3 User Guide.
Related Resources
4013 4014 4015 4016 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4013 def delete_bucket_cors(params = {}, = {}) req = build_request(:delete_bucket_cors, params) req.send_request() end |
#delete_bucket_encryption(params = {}) ⇒ Struct
This implementation of the DELETE action resets the default encryption for the bucket as server-side encryption with Amazon S3 managed keys (SSE-S3).
- Directory buckets - For directory buckets, there are only two supported options for server-side encryption: SSE-S3 and SSE-KMS. For information about the default encryption configuration in directory buckets, see Setting default server-side encryption behavior for directory buckets.
- Permissions
General purpose bucket permissions - The
s3:PutEncryptionConfiguration
permission is required in a policy. The bucket owner has this permission by default. The bucket owner can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Operations and Managing Access Permissions to Your Amazon S3 Resources.Directory bucket permissions - To grant access to this API operation, you must have the
s3express:PutEncryptionConfiguration
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following operations are related to DeleteBucketEncryption
:
4117 4118 4119 4120 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4117 def delete_bucket_encryption(params = {}, = {}) req = build_request(:delete_bucket_encryption, params) req.send_request() end |
#delete_bucket_intelligent_tiering_configuration(params = {}) ⇒ Struct
Deletes the S3 Intelligent-Tiering configuration from the specified bucket.
The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to the most cost-effective storage access tier, without performance impact or operational overhead. S3 Intelligent-Tiering delivers automatic cost savings in three low latency and high throughput access tiers. To get the lowest storage cost on data that can be accessed in minutes to hours, you can choose to activate additional archiving capabilities.
The S3 Intelligent-Tiering storage class is the ideal storage class for data with unknown, changing, or unpredictable access patterns, independent of object size or retention period. If the size of an object is less than 128 KB, it is not monitored and not eligible for auto-tiering. Smaller objects can be stored, but they are always charged at the Frequent Access tier rates in the S3 Intelligent-Tiering storage class.
For more information, see Storage class for automatically optimizing frequently and infrequently accessed objects.
Operations related to DeleteBucketIntelligentTieringConfiguration
include:
4184 4185 4186 4187 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4184 def delete_bucket_intelligent_tiering_configuration(params = {}, = {}) req = build_request(:delete_bucket_intelligent_tiering_configuration, params) req.send_request() end |
#delete_bucket_inventory_configuration(params = {}) ⇒ Struct
Deletes an inventory configuration (identified by the inventory ID) from the bucket.
To use this operation, you must have permissions to perform the
s3:PutInventoryConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.
For information about the Amazon S3 inventory feature, see Amazon S3 Inventory.
Operations related to DeleteBucketInventoryConfiguration
include:
4249 4250 4251 4252 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4249 def delete_bucket_inventory_configuration(params = {}, = {}) req = build_request(:delete_bucket_inventory_configuration, params) req.send_request() end |
#delete_bucket_lifecycle(params = {}) ⇒ Struct
Deletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and Amazon S3 no longer automatically deletes any objects on the basis of rules contained in the deleted lifecycle configuration.
- Permissions
General purpose bucket permissions - By default, all Amazon S3 resources are private, including buckets, objects, and related subresources (for example, lifecycle configuration and website configuration). Only the resource owner (that is, the Amazon Web Services account that created it) can access the resource. The resource owner can optionally grant access permissions to others by writing an access policy. For this operation, a user must have the
s3:PutLifecycleConfiguration
permission.For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources. ^
Directory bucket permissions - You must have the
s3express:PutLifecycleConfiguration
permission in an IAM identity-based policy to use this operation. Cross-account access to this API operation isn't supported. The resource owner can optionally grant access permissions to others by creating a role or user for them as long as they are within the same account as the owner and resource.For more information about directory bucket policies and permissions, see Authorizing Regional endpoint APIs with IAM in the Amazon S3 User Guide.
Directory buckets - For directory buckets, you must make requests for this API operation to the Regional endpoint. These endpoints support path-style requests in the format https://s3express-control.region_code.amazonaws.com/bucket-name
. Virtual-hosted-style requests aren't supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.^
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
For more information about the object expiration, see Elements to Describe Lifecycle Actions.
Related actions include:
4355 4356 4357 4358 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4355 def delete_bucket_lifecycle(params = {}, = {}) req = build_request(:delete_bucket_lifecycle, params) req.send_request() end |
#delete_bucket_metrics_configuration(params = {}) ⇒ Struct
Deletes a metrics configuration for the Amazon CloudWatch request metrics (specified by the metrics configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.
To use this operation, you must have permissions to perform the
s3:PutMetricsConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.
For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon CloudWatch.
The following operations are related to
DeleteBucketMetricsConfiguration
:
4425 4426 4427 4428 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4425 def delete_bucket_metrics_configuration(params = {}, = {}) req = build_request(:delete_bucket_metrics_configuration, params) req.send_request() end |
#delete_bucket_ownership_controls(params = {}) ⇒ Struct
Removes OwnershipControls
for an Amazon S3 bucket. To use this
operation, you must have the s3:PutBucketOwnershipControls
permission. For more information about Amazon S3 permissions, see
Specifying Permissions in a Policy.
For information about Amazon S3 Object Ownership, see Using Object Ownership.
The following operations are related to
DeleteBucketOwnershipControls
:
GetBucketOwnershipControls
PutBucketOwnershipControls
4475 4476 4477 4478 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4475 def delete_bucket_ownership_controls(params = {}, = {}) req = build_request(:delete_bucket_ownership_controls, params) req.send_request() end |
#delete_bucket_policy(params = {}) ⇒ Struct
Deletes the policy of a specified bucket.
https://s3express-control.region_code.amazonaws.com/bucket-name
.
Virtual-hosted-style requests aren't supported. For more information,
see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
If you are using an identity other than the root user of the Amazon Web Services account that owns the bucket, the calling identity must both have the
DeleteBucketPolicy
permissions on the specified bucket and belong to the bucket owner's account in order to use this operation.If you don't have
DeleteBucketPolicy
permissions, Amazon S3 returns a403 Access Denied
error. If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's account, Amazon S3 returns a405 Method Not Allowed
error.To ensure that bucket owners don't inadvertently lock themselves out of their own buckets, the root principal in a bucket owner's Amazon Web Services account can perform the
GetBucketPolicy
,PutBucketPolicy
, andDeleteBucketPolicy
API actions, even if their bucket policy explicitly denies the root principal's access. Bucket owner root principals can only be blocked from performing these API actions by VPC endpoint policies and Amazon Web Services Organizations policies.General purpose bucket permissions - The
s3:DeleteBucketPolicy
permission is required in a policy. For more information about general purpose buckets bucket policies, see Using Bucket Policies and User Policies in the Amazon S3 User Guide.Directory bucket permissions - To grant access to this API operation, you must have the
s3express:DeleteBucketPolicy
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following operations are related to DeleteBucketPolicy
4599 4600 4601 4602 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4599 def delete_bucket_policy(params = {}, = {}) req = build_request(:delete_bucket_policy, params) req.send_request() end |
#delete_bucket_replication(params = {}) ⇒ Struct
Deletes the replication configuration from the bucket.
To use this operation, you must have permissions to perform the
s3:PutReplicationConfiguration
action. The bucket owner has these
permissions by default and can grant it to others. For more
information about permissions, see Permissions Related to Bucket
Subresource Operations and Managing Access Permissions to Your
Amazon S3 Resources.
For information about replication configuration, see Replication in the Amazon S3 User Guide.
The following operations are related to DeleteBucketReplication
:
4669 4670 4671 4672 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4669 def delete_bucket_replication(params = {}, = {}) req = build_request(:delete_bucket_replication, params) req.send_request() end |
#delete_bucket_tagging(params = {}) ⇒ Struct
Deletes the tags from the bucket.
To use this operation, you must have permission to perform the
s3:PutBucketTagging
action. By default, the bucket owner has this
permission and can grant this permission to others.
The following operations are related to DeleteBucketTagging
:
4725 4726 4727 4728 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4725 def delete_bucket_tagging(params = {}, = {}) req = build_request(:delete_bucket_tagging, params) req.send_request() end |
#delete_bucket_website(params = {}) ⇒ Struct
This action removes the website configuration for a bucket. Amazon S3
returns a 200 OK
response upon successfully deleting a website
configuration on the specified bucket. You will get a 200 OK
response if the website configuration you are trying to delete does
not exist on the bucket. Amazon S3 returns a 404
response if the
bucket specified in the request does not exist.
This DELETE action requires the S3:DeleteBucketWebsite
permission.
By default, only the bucket owner can delete the website configuration
attached to a bucket. However, bucket owners can grant other users
permission to delete the website configuration by writing a bucket
policy granting them the S3:DeleteBucketWebsite
permission.
For more information about hosting websites, see Hosting Websites on Amazon S3.
The following operations are related to DeleteBucketWebsite
:
4793 4794 4795 4796 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 4793 def delete_bucket_website(params = {}, = {}) req = build_request(:delete_bucket_website, params) req.send_request() end |
#delete_object(params = {}) ⇒ Types::DeleteObjectOutput
Removes an object from a bucket. The behavior depends on the bucket's versioning state. For more information, see Best practices to consider before deleting an object.
To remove a specific version, you must use the versionId
query
parameter. Using this query parameter permanently deletes the version.
If the object deleted is a delete marker, Amazon S3 sets the response
header x-amz-delete-marker
to true. If the object you want to delete
is in a bucket where the bucket versioning configuration is MFA delete
enabled, you must include the x-amz-mfa
request header in the DELETE
versionId
request. Requests that include x-amz-mfa
must use HTTPS.
For more information about MFA delete and to see example requests, see
Using MFA delete and Sample request in the Amazon S3 User
Guide.
null
value of the version ID is
supported by directory buckets. You can only specify null
to the
versionId
query parameter in the request.
For directory buckets, you must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.MFA delete is not supported by directory buckets.
- Permissions
General purpose bucket permissions - The following permissions are required in your policies when your
DeleteObjects
request includes specific headers.s3:DeleteObject
- To delete an object from a bucket, you must always have thes3:DeleteObject
permission.You can also use PutBucketLifecycle to delete objects in Amazon S3. s3:DeleteObjectVersion
- To delete a specific version of an object from a versioning-enabled bucket, you must have thes3:DeleteObjectVersion
permission.If you want to block users or accounts from removing or deleting objects from your bucket, you must deny them the
s3:DeleteObject
,s3:DeleteObjectVersion
, ands3:PutLifeCycleConfiguration
permissions.
- Directory buckets permissions - To grant access to this API operation on a directory bucket, we recommend that you use the CreateSession API operation for session-based authorization.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following action is related to DeleteObject
:
^
5066 5067 5068 5069 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5066 def delete_object(params = {}, = {}) req = build_request(:delete_object, params) req.send_request() end |
#delete_object_tagging(params = {}) ⇒ Types::DeleteObjectTaggingOutput
Removes the entire tag set from the specified object. For more information about managing object tags, see Object Tagging.
To use this operation, you must have permission to perform the
s3:DeleteObjectTagging
action.
To delete tags of a specific object version, add the versionId
query
parameter in the request. You will need permission for the
s3:DeleteObjectVersionTagging
action.
The following operations are related to DeleteObjectTagging
:
5190 5191 5192 5193 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5190 def delete_object_tagging(params = {}, = {}) req = build_request(:delete_object_tagging, params) req.send_request() end |
#delete_objects(params = {}) ⇒ 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 can contain 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.
- Directory buckets - For directory buckets, you must make
requests for this API operation to the Zonal endpoint. These
endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
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 in a quiet mode, the operation does not return any information about the delete in the response body.
When performing this action 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 in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - The following permissions are required in your policies when your
DeleteObjects
request includes specific headers.s3:DeleteObject
- To delete an object from a bucket, you must always specify thes3:DeleteObject
permission.s3:DeleteObjectVersion
- To delete a specific version of an object from a versioning-enabled bucket, you must specify thes3:DeleteObjectVersion
permission.
- Directory bucket permissions - To grant access to this API
operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.
- Content-MD5 request header
General purpose bucket - The Content-MD5 request 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.
Directory bucket - The Content-MD5 request header or a additional checksum request header (including
x-amz-checksum-crc32
,x-amz-checksum-crc32c
,x-amz-checksum-sha1
, orx-amz-checksum-sha256
) is required for all Multi-Object Delete requests.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to DeleteObjects
:
5565 5566 5567 5568 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5565 def delete_objects(params = {}, = {}) req = build_request(:delete_objects, params) req.send_request() end |
#delete_public_access_block(params = {}) ⇒ Struct
Removes the PublicAccessBlock
configuration for an Amazon S3 bucket.
To use this operation, you must have the
s3:PutBucketPublicAccessBlock
permission. For more information about
permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3
Resources.
The following operations are related to DeletePublicAccessBlock
:
5622 5623 5624 5625 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5622 def delete_public_access_block(params = {}, = {}) req = build_request(:delete_public_access_block, params) req.send_request() end |
#get_bucket_accelerate_configuration(params = {}) ⇒ Types::GetBucketAccelerateConfigurationOutput
This implementation of the GET action uses the accelerate
subresource to return the Transfer Acceleration state of a bucket,
which is either Enabled
or Suspended
. Amazon S3 Transfer
Acceleration is a bucket-level feature that enables you to perform
faster data transfers to and from Amazon S3.
To use this operation, you must have permission to perform the
s3:GetAccelerateConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to your Amazon S3 Resources in the Amazon S3 User
Guide.
You set the Transfer Acceleration state of an existing bucket to
Enabled
or Suspended
by using the
PutBucketAccelerateConfiguration operation.
A GET accelerate
request does not return a state value for a bucket
that has no transfer acceleration state. A bucket has no Transfer
Acceleration state if a state has never been set on the bucket.
For more information about transfer acceleration, see Transfer Acceleration in the Amazon S3 User Guide.
The following operations are related to
GetBucketAccelerateConfiguration
:
^
5718 5719 5720 5721 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5718 def get_bucket_accelerate_configuration(params = {}, = {}) req = build_request(:get_bucket_accelerate_configuration, params) req.send_request() end |
#get_bucket_acl(params = {}) ⇒ Types::GetBucketAclOutput
This implementation of the GET
action uses the acl
subresource to
return the access control list (ACL) of a bucket. To use GET
to
return the ACL of the bucket, you must have the READ_ACP
access to
the bucket. If READ_ACP
permission is granted to the anonymous user,
you can return the ACL of the bucket without using an authorization
header.
When you use this API operation with an access point, provide the alias of the access point in place of the bucket name.
When you use this API operation with an Object Lambda access point,
provide the alias of the Object Lambda access point in place of the
bucket name. If the Object Lambda access point alias in a request is
not valid, the error code InvalidAccessPointAliasError
is returned.
For more information about InvalidAccessPointAliasError
, see List
of Error Codes.
bucket-owner-full-control
ACL with the owner being the account that
created the bucket. For more information, see Controlling object
ownership and disabling ACLs in the Amazon S3 User Guide.
The following operations are related to GetBucketAcl
:
^
5814 5815 5816 5817 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5814 def get_bucket_acl(params = {}, = {}) req = build_request(:get_bucket_acl, params) req.send_request() end |
#get_bucket_analytics_configuration(params = {}) ⇒ Types::GetBucketAnalyticsConfigurationOutput
This implementation of the GET action returns an analytics configuration (identified by the analytics configuration ID) from the bucket.
To use this operation, you must have permissions to perform the
s3:GetAnalyticsConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources in the Amazon S3 User
Guide.
For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in the Amazon S3 User Guide.
The following operations are related to
GetBucketAnalyticsConfiguration
:
5900 5901 5902 5903 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 5900 def get_bucket_analytics_configuration(params = {}, = {}) req = build_request(:get_bucket_analytics_configuration, params) req.send_request() end |
#get_bucket_cors(params = {}) ⇒ Types::GetBucketCorsOutput
Returns the Cross-Origin Resource Sharing (CORS) configuration information set for the bucket.
To use this operation, you must have permission to perform the
s3:GetBucketCORS
action. By default, the bucket owner has this
permission and can grant it to others.
When you use this API operation with an access point, provide the alias of the access point in place of the bucket name.
When you use this API operation with an Object Lambda access point,
provide the alias of the Object Lambda access point in place of the
bucket name. If the Object Lambda access point alias in a request is
not valid, the error code InvalidAccessPointAliasError
is returned.
For more information about InvalidAccessPointAliasError
, see List
of Error Codes.
For more information about CORS, see Enabling Cross-Origin Resource Sharing.
The following operations are related to GetBucketCors
:
6020 6021 6022 6023 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6020 def get_bucket_cors(params = {}, = {}) req = build_request(:get_bucket_cors, params) req.send_request() end |
#get_bucket_encryption(params = {}) ⇒ Types::GetBucketEncryptionOutput
Returns the default encryption configuration for an Amazon S3 bucket. By default, all buckets have a default encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3).
- Directory buckets - For directory buckets, there are only two supported options for server-side encryption: SSE-S3 and SSE-KMS. For information about the default encryption configuration in directory buckets, see Setting default server-side encryption behavior for directory buckets.
- Permissions
General purpose bucket permissions - The
s3:GetEncryptionConfiguration
permission is required in a policy. The bucket owner has this permission by default. The bucket owner can grant this permission to others. For more information about permissions, see Permissions Related to Bucket Operations and Managing Access Permissions to Your Amazon S3 Resources.Directory bucket permissions - To grant access to this API operation, you must have the
s3express:GetEncryptionConfiguration
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following operations are related to GetBucketEncryption
:
6133 6134 6135 6136 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6133 def get_bucket_encryption(params = {}, = {}) req = build_request(:get_bucket_encryption, params) req.send_request() end |
#get_bucket_intelligent_tiering_configuration(params = {}) ⇒ Types::GetBucketIntelligentTieringConfigurationOutput
Gets the S3 Intelligent-Tiering configuration from the specified bucket.
The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to the most cost-effective storage access tier, without performance impact or operational overhead. S3 Intelligent-Tiering delivers automatic cost savings in three low latency and high throughput access tiers. To get the lowest storage cost on data that can be accessed in minutes to hours, you can choose to activate additional archiving capabilities.
The S3 Intelligent-Tiering storage class is the ideal storage class for data with unknown, changing, or unpredictable access patterns, independent of object size or retention period. If the size of an object is less than 128 KB, it is not monitored and not eligible for auto-tiering. Smaller objects can be stored, but they are always charged at the Frequent Access tier rates in the S3 Intelligent-Tiering storage class.
For more information, see Storage class for automatically optimizing frequently and infrequently accessed objects.
Operations related to GetBucketIntelligentTieringConfiguration
include:
6217 6218 6219 6220 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6217 def get_bucket_intelligent_tiering_configuration(params = {}, = {}) req = build_request(:get_bucket_intelligent_tiering_configuration, params) req.send_request() end |
#get_bucket_inventory_configuration(params = {}) ⇒ Types::GetBucketInventoryConfigurationOutput
Returns an inventory configuration (identified by the inventory configuration ID) from the bucket.
To use this operation, you must have permissions to perform the
s3:GetInventoryConfiguration
action. The bucket owner has this
permission by default and can grant this permission to others. For
more information about permissions, see Permissions Related to Bucket
Subresource Operations and Managing Access Permissions to Your
Amazon S3 Resources.
For information about the Amazon S3 inventory feature, see Amazon S3 Inventory.
The following operations are related to
GetBucketInventoryConfiguration
:
6300 6301 6302 6303 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6300 def get_bucket_inventory_configuration(params = {}, = {}) req = build_request(:get_bucket_inventory_configuration, params) req.send_request() end |
#get_bucket_lifecycle(params = {}) ⇒ Types::GetBucketLifecycleOutput
For an updated version of this API, see
GetBucketLifecycleConfiguration. If you configured a bucket
lifecycle using the filter
element, you should see the updated
version of this topic. This topic is provided for backward
compatibility.
Returns the lifecycle configuration information set on the bucket. For information about lifecycle configuration, see Object Lifecycle Management.
To use this operation, you must have permission to perform the
s3:GetLifecycleConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.
GetBucketLifecycle
has the following special error:
Error code:
NoSuchLifecycleConfiguration
Description: The lifecycle configuration does not exist.
HTTP Status Code: 404 Not Found
SOAP Fault Code Prefix: Client
The following operations are related to GetBucketLifecycle
:
6418 6419 6420 6421 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6418 def get_bucket_lifecycle(params = {}, = {}) req = build_request(:get_bucket_lifecycle, params) req.send_request() end |
#get_bucket_lifecycle_configuration(params = {}) ⇒ Types::GetBucketLifecycleConfigurationOutput
Returns the lifecycle configuration information set on the bucket. For information about lifecycle configuration, see Object Lifecycle Management.
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name prefix, one or more object tags, object size, or any combination of these. Accordingly, this section describes the latest API, which is compatible with the new functionality. The previous version of the API supported filtering based only on an object key name prefix, which is supported for general purpose buckets for backward compatibility. For the related API description, see GetBucketLifecycle.
- Permissions
General purpose bucket permissions - By default, all Amazon S3 resources are private, including buckets, objects, and related subresources (for example, lifecycle configuration and website configuration). Only the resource owner (that is, the Amazon Web Services account that created it) can access the resource. The resource owner can optionally grant access permissions to others by writing an access policy. For this operation, a user must have the
s3:GetLifecycleConfiguration
permission.For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources. ^
Directory bucket permissions - You must have the
s3express:GetLifecycleConfiguration
permission in an IAM identity-based policy to use this operation. Cross-account access to this API operation isn't supported. The resource owner can optionally grant access permissions to others by creating a role or user for them as long as they are within the same account as the owner and resource.For more information about directory bucket policies and permissions, see Authorizing Regional endpoint APIs with IAM in the Amazon S3 User Guide.
Directory buckets - For directory buckets, you must make requests for this API operation to the Regional endpoint. These endpoints support path-style requests in the format https://s3express-control.region_code.amazonaws.com/bucket-name
. Virtual-hosted-style requests aren't supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
GetBucketLifecycleConfiguration
has the following special error:
Error code:
NoSuchLifecycleConfiguration
Description: The lifecycle configuration does not exist.
HTTP Status Code: 404 Not Found
SOAP Fault Code Prefix: Client
The following operations are related to
GetBucketLifecycleConfiguration
:
6600 6601 6602 6603 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6600 def get_bucket_lifecycle_configuration(params = {}, = {}) req = build_request(:get_bucket_lifecycle_configuration, params) req.send_request() end |
#get_bucket_location(params = {}) ⇒ Types::GetBucketLocationOutput
Returns the Region the bucket resides in. You set the bucket's Region
using the LocationConstraint
request parameter in a CreateBucket
request. For more information, see CreateBucket.
When you use this API operation with an access point, provide the alias of the access point in place of the bucket name.
When you use this API operation with an Object Lambda access point,
provide the alias of the Object Lambda access point in place of the
bucket name. If the Object Lambda access point alias in a request is
not valid, the error code InvalidAccessPointAliasError
is returned.
For more information about InvalidAccessPointAliasError
, see List
of Error Codes.
The following operations are related to GetBucketLocation
:
6697 6698 6699 6700 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6697 def get_bucket_location(params = {}, = {}) req = build_request(:get_bucket_location, params) req.send_request() 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.
The following operations are related to GetBucketLogging
:
6756 6757 6758 6759 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6756 def get_bucket_logging(params = {}, = {}) req = build_request(:get_bucket_logging, params) req.send_request() end |
#get_bucket_metrics_configuration(params = {}) ⇒ Types::GetBucketMetricsConfigurationOutput
Gets a metrics configuration (specified by the metrics configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.
To use this operation, you must have permissions to perform the
s3:GetMetricsConfiguration
action. The bucket owner has this
permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.
For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon CloudWatch.
The following operations are related to
GetBucketMetricsConfiguration
:
6842 6843 6844 6845 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6842 def get_bucket_metrics_configuration(params = {}, = {}) req = build_request(:get_bucket_metrics_configuration, params) req.send_request() end |
#get_bucket_notification(params = {}) ⇒ Types::NotificationConfigurationDeprecated
No longer used, see GetBucketNotificationConfiguration.
6973 6974 6975 6976 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 6973 def get_bucket_notification(params = {}, = {}) req = build_request(:get_bucket_notification, params) req.send_request() end |
#get_bucket_notification_configuration(params = {}) ⇒ Types::NotificationConfiguration
Returns the notification configuration of a bucket.
If notifications are not enabled on the bucket, the action returns an
empty NotificationConfiguration
element.
By default, you must be the bucket owner to read the notification
configuration of a bucket. However, the bucket owner can use a bucket
policy to grant permission to other users to read this configuration
with the s3:GetBucketNotification
permission.
When you use this API operation with an access point, provide the alias of the access point in place of the bucket name.
When you use this API operation with an Object Lambda access point,
provide the alias of the Object Lambda access point in place of the
bucket name. If the Object Lambda access point alias in a request is
not valid, the error code InvalidAccessPointAliasError
is returned.
For more information about InvalidAccessPointAliasError
, see List
of Error Codes.
For more information about setting and reading the notification configuration on a bucket, see Setting Up Notification of Bucket Events. For more information about bucket policies, see Using Bucket Policies.
The following action is related to GetBucketNotification
:
^
7088 7089 7090 7091 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7088 def get_bucket_notification_configuration(params = {}, = {}) req = build_request(:get_bucket_notification_configuration, params) req.send_request() end |
#get_bucket_ownership_controls(params = {}) ⇒ Types::GetBucketOwnershipControlsOutput
Retrieves OwnershipControls
for an Amazon S3 bucket. To use this
operation, you must have the s3:GetBucketOwnershipControls
permission. For more information about Amazon S3 permissions, see
Specifying permissions in a policy.
For information about Amazon S3 Object Ownership, see Using Object Ownership.
The following operations are related to GetBucketOwnershipControls
:
PutBucketOwnershipControls
DeleteBucketOwnershipControls
7145 7146 7147 7148 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7145 def get_bucket_ownership_controls(params = {}, = {}) req = build_request(:get_bucket_ownership_controls, params) req.send_request() end |
#get_bucket_policy(params = {}) ⇒ Types::GetBucketPolicyOutput
Returns the policy of a specified bucket.
https://s3express-control.region_code.amazonaws.com/bucket-name
.
Virtual-hosted-style requests aren't supported. For more information,
see Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
If you are using an identity other than the root user of the Amazon Web Services account that owns the bucket, the calling identity must both have the
GetBucketPolicy
permissions on the specified bucket and belong to the bucket owner's account in order to use this operation.If you don't have
GetBucketPolicy
permissions, Amazon S3 returns a403 Access Denied
error. If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's account, Amazon S3 returns a405 Method Not Allowed
error.To ensure that bucket owners don't inadvertently lock themselves out of their own buckets, the root principal in a bucket owner's Amazon Web Services account can perform the
GetBucketPolicy
,PutBucketPolicy
, andDeleteBucketPolicy
API actions, even if their bucket policy explicitly denies the root principal's access. Bucket owner root principals can only be blocked from performing these API actions by VPC endpoint policies and Amazon Web Services Organizations policies.General purpose bucket permissions - The
s3:GetBucketPolicy
permission is required in a policy. For more information about general purpose buckets bucket policies, see Using Bucket Policies and User Policies in the Amazon S3 User Guide.Directory bucket permissions - To grant access to this API operation, you must have the
s3express:GetBucketPolicy
permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone in the Amazon S3 User Guide.
- Example bucket policies
General purpose buckets example bucket policies - See Bucket policy examples in the Amazon S3 User Guide.
Directory bucket example bucket policies - See Example bucket policies for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
s3express-control.region.amazonaws.com
.
The following action is related to GetBucketPolicy
:
^
7305 7306 7307 7308 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7305 def get_bucket_policy(params = {}, = {}, &block) req = build_request(:get_bucket_policy, params) req.send_request(, &block) end |
#get_bucket_policy_status(params = {}) ⇒ Types::GetBucketPolicyStatusOutput
Retrieves the policy status for an Amazon S3 bucket, indicating
whether the bucket is public. In order to use this operation, you must
have the s3:GetBucketPolicyStatus
permission. For more information
about Amazon S3 permissions, see Specifying Permissions in a
Policy.
For more information about when Amazon S3 considers a bucket public, see The Meaning of "Public".
The following operations are related to GetBucketPolicyStatus
:
7370 7371 7372 7373 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7370 def get_bucket_policy_status(params = {}, = {}) req = build_request(:get_bucket_policy_status, params) req.send_request() end |
#get_bucket_replication(params = {}) ⇒ Types::GetBucketReplicationOutput
Returns the replication configuration of a bucket.
For information about replication configuration, see Replication in the Amazon S3 User Guide.
This action requires permissions for the
s3:GetReplicationConfiguration
action. For more information about
permissions, see Using Bucket Policies and User Policies.
If you include the Filter
element in a replication configuration,
you must also include the DeleteMarkerReplication
and Priority
elements. The response also returns those elements.
For information about GetBucketReplication
errors, see List of
replication-related error codes
The following operations are related to GetBucketReplication
:
7493 7494 7495 7496 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7493 def get_bucket_replication(params = {}, = {}) req = build_request(:get_bucket_replication, params) req.send_request() end |
#get_bucket_request_payment(params = {}) ⇒ Types::GetBucketRequestPaymentOutput
Returns the request payment configuration of a bucket. To use this version of the operation, you must be the bucket owner. For more information, see Requester Pays Buckets.
The following operations are related to GetBucketRequestPayment
:
^
7559 7560 7561 7562 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7559 def get_bucket_request_payment(params = {}, = {}) req = build_request(:get_bucket_request_payment, params) req.send_request() end |
#get_bucket_tagging(params = {}) ⇒ Types::GetBucketTaggingOutput
Returns the tag set associated with the bucket.
To use this operation, you must have permission to perform the
s3:GetBucketTagging
action. By default, the bucket owner has this
permission and can grant this permission to others.
GetBucketTagging
has the following special error:
Error code:
NoSuchTagSet
- Description: There is no tag set associated with the bucket.
^
The following operations are related to GetBucketTagging
:
7645 7646 7647 7648 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7645 def get_bucket_tagging(params = {}, = {}) req = build_request(:get_bucket_tagging, params) req.send_request() end |
#get_bucket_versioning(params = {}) ⇒ Types::GetBucketVersioningOutput
Returns the versioning state of a bucket.
To retrieve the versioning state of a bucket, you must be the bucket owner.
This implementation also returns the MFA Delete status of the
versioning state. If the MFA Delete status is enabled
, the bucket
owner must use an authentication device to change the versioning state
of the bucket.
The following operations are related to GetBucketVersioning
:
7722 7723 7724 7725 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7722 def get_bucket_versioning(params = {}, = {}) req = build_request(:get_bucket_versioning, params) req.send_request() end |
#get_bucket_website(params = {}) ⇒ Types::GetBucketWebsiteOutput
Returns the website configuration for a bucket. To host website on Amazon S3, you can configure a bucket as website by adding a website configuration. For more information about hosting websites, see Hosting Websites on Amazon S3.
This GET action requires the S3:GetBucketWebsite
permission. By
default, only the bucket owner can read the bucket website
configuration. However, bucket owners can allow other users to read
the website configuration by writing a bucket policy granting them the
S3:GetBucketWebsite
permission.
The following operations are related to GetBucketWebsite
:
7814 7815 7816 7817 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 7814 def get_bucket_website(params = {}, = {}) req = build_request(:get_bucket_website, params) req.send_request() end |
#get_object(params = {}) ⇒ Types::GetObjectOutput
Retrieves an object from Amazon S3.
In the GetObject
request, specify the full key name for the object.
General purpose buckets - Both the virtual-hosted-style requests
and the path-style requests are supported. For a virtual hosted-style
request example, if you have the object
photos/2006/February/sample.jpg
, specify the object key name as
/photos/2006/February/sample.jpg
. For a path-style request example,
if you have the object photos/2006/February/sample.jpg
in the bucket
named examplebucket
, specify the object key name as
/examplebucket/photos/2006/February/sample.jpg
. For more information
about request types, see HTTP Host Header Bucket Specification in
the Amazon S3 User Guide.
Directory buckets - Only virtual-hosted-style requests are
supported. For a virtual hosted-style request example, if you have the
object photos/2006/February/sample.jpg
in the bucket named
examplebucket--use1-az5--x-s3
, specify the object key name as
/photos/2006/February/sample.jpg
. Also, when you make requests to
this API operation, your requests are sent to the Zonal endpoint.
These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
.
Path-style requests are not supported. For more information, see
Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - You must have the required permissions in a policy. To use
GetObject
, you must have theREAD
access to the object (or version). If you grantREAD
access to the anonymous user, theGetObject
operation returns the object without using an authorization header. For more information, see Specifying permissions in a policy in the Amazon S3 User Guide.If you include a
versionId
in your request header, you must have thes3:GetObjectVersion
permission to access a specific version of an object. Thes3:GetObject
permission is not required in this scenario.If you request the current version of an object without a specific
versionId
in the request header, only thes3:GetObject
permission is required. Thes3:GetObjectVersion
permission is not required in this scenario.If the object that you request doesn’t exist, the error that Amazon S3 returns depends on whether you also have the
s3:ListBucket
permission.If you have the
s3:ListBucket
permission on the bucket, Amazon S3 returns an HTTP status code404 Not Found
error.If you don’t have the
s3:ListBucket
permission, Amazon S3 returns an HTTP status code403 Access Denied
error.
Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.If the object is encrypted using SSE-KMS, you must also have the
kms:GenerateDataKey
andkms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the KMS key.
- Storage classes
If the object you are retrieving is stored in the S3 Glacier Flexible Retrieval storage class, the S3 Glacier Deep Archive storage class, the S3 Intelligent-Tiering Archive Access tier, or the S3 Intelligent-Tiering Deep Archive Access tier, before you can retrieve the object you must first restore a copy using RestoreObject. Otherwise, this operation returns an
InvalidObjectState
error. For information about restoring archived objects, see Restoring Archived Objects in the Amazon S3 User Guide.Directory buckets - For directory buckets, only the S3 Express One Zone storage class is supported to store newly created objects. Unsupported storage class values won't write a destination object and will respond with the HTTP status code
400 Bad Request
.- Encryption
Encryption request headers, like
x-amz-server-side-encryption
, should not be sent for theGetObject
requests, if your object uses server-side encryption with Amazon S3 managed encryption keys (SSE-S3), server-side encryption with Key Management Service (KMS) keys (SSE-KMS), or dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS). If you include the header in yourGetObject
requests for the object that uses these types of keys, you’ll get an HTTP400 Bad Request
error.Directory buckets - For directory buckets, there are only two supported options for server-side encryption: SSE-S3 and SSE-KMS. SSE-C isn't supported. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide.
- Overriding response header values through the request
There are times when you want to override certain response header values of a
GetObject
response. For example, you might override theContent-Disposition
response header value through yourGetObject
request.You can override values for a set of response headers. These modified response header values are included only in a successful response, that is, when the HTTP status code
200 OK
is returned. The headers you can override using the following query parameters in the request are a subset of the headers that Amazon S3 accepts when you create an object.The response headers that you can override for the
GetObject
response areCache-Control
,Content-Disposition
,Content-Encoding
,Content-Language
,Content-Type
, andExpires
.To override values for a set of response headers in the
GetObject
response, you can use the following query parameters in the request.response-cache-control
response-content-disposition
response-content-encoding
response-content-language
response-content-type
response-expires
When you use these parameters, you must sign the request by using either an Authorization header or a presigned URL. These parameters cannot be used with an unsigned (anonymous) request. - HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following operations are related to GetObject
:
8479 8480 8481 8482 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 8479 def get_object(params = {}, = {}, &block) req = build_request(:get_object, params) req.send_request(, &block) end |
#get_object_acl(params = {}) ⇒ Types::GetObjectAclOutput
Returns the access control list (ACL) of an object. To use this
operation, you must have s3:GetObjectAcl
permissions or READ_ACP
access to the object. For more information, see Mapping of ACL
permissions and access policy permissions in the Amazon S3 User
Guide
This functionality is not supported for Amazon S3 on Outposts.
By default, GET returns ACL information about the current version of an object. To return ACL information about a different version, use the versionId subresource.
bucket-owner-full-control
ACL with the owner being the account that
created the bucket. For more information, see Controlling object
ownership and disabling ACLs in the Amazon S3 User Guide.
The following operations are related to GetObjectAcl
:
8663 8664 8665 8666 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 8663 def get_object_acl(params = {}, = {}) req = build_request(:get_object_acl, params) req.send_request() end |
#get_object_attributes(params = {}) ⇒ Types::GetObjectAttributesOutput
Retrieves all the metadata from an object without returning the object itself. This operation is useful if you're interested only in an object's metadata.
GetObjectAttributes
combines the functionality of HeadObject
and
ListParts
. All of the data returned with each of those individual
calls can be returned with a single call to GetObjectAttributes
.
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
.
Path-style requests are not supported. For more information, see
Regional and Zonal endpoints in the Amazon S3 User Guide.
- Permissions
General purpose bucket permissions - To use
GetObjectAttributes
, you must have READ access to the object. The permissions that you need to use this operation depend on whether the bucket is versioned. If the bucket is versioned, you need both thes3:GetObjectVersion
ands3:GetObjectVersionAttributes
permissions for this operation. If the bucket is not versioned, you need thes3:GetObject
ands3:GetObjectAttributes
permissions. For more information, see Specifying Permissions in a Policy in the Amazon S3 User Guide. If the object that you request does not exist, the error Amazon S3 returns depends on whether you also have thes3:ListBucket
permission.If you have the
s3:ListBucket
permission on the bucket, Amazon S3 returns an HTTP status code404 Not Found
("no such key") error.If you don't have the
s3:ListBucket
permission, Amazon S3 returns an HTTP status code403 Forbidden
("access denied") error.
Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.If the object is encrypted with SSE-KMS, you must also have the
kms:GenerateDataKey
andkms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the KMS key.
- Encryption
Encryption request headers, like x-amz-server-side-encryption
, should not be sent forHEAD
requests if your object uses server-side encryption with Key Management Service (KMS) keys (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or server-side encryption with Amazon S3 managed encryption keys (SSE-S3). Thex-amz-server-side-encryption
header is used when youPUT
an object to S3 and want to specify the encryption method. If you include this header in aGET
request for an object that uses these types of keys, you’ll get an HTTP400 Bad Request
error. It's because the encryption method can't be changed when you retrieve the object.If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in Amazon S3, then when you retrieve the metadata from the object, you must use the following headers to provide the encryption key for the server to be able to retrieve the object's metadata. The headers are:
x-amz-server-side-encryption-customer-algorithm
x-amz-server-side-encryption-customer-key
x-amz-server-side-encryption-customer-key-MD5
For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon S3 User Guide.
Directory bucket permissions - For directory buckets, there are only two supported options for server-side encryption: server-side encryption with Amazon S3 managed keys (SSE-S3) ( AES256
) and server-side encryption with KMS keys (SSE-KMS) (aws:kms
). We recommend that the bucket's default encryption uses the desired encryption configuration and you don't override the bucket default encryption in yourCreateSession
requests orPUT
object requests. Then, new objects are automatically encrypted with the desired encryption settings. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide. For more information about the encryption overriding behaviors in directory buckets, see Specifying server-side encryption with KMS for new object uploads.- Versioning
Directory buckets - S3 Versioning isn't enabled and supported for directory buckets. For this API operation, only the
null
value of the version ID is supported by directory buckets. You can only specifynull
to theversionId
query parameter in the request.- Conditional request headers
Consider the following when using request headers:
If both of the
If-Match
andIf-Unmodified-Since
headers are present in the request as follows, then Amazon S3 returns the HTTP status code200 OK
and the data requested:If-Match
condition evaluates totrue
.If-Unmodified-Since
condition evaluates tofalse
. For more information about conditional requests, see RFC 7232.
If both of the
If-None-Match
andIf-Modified-Since
headers are present in the request as follows, then Amazon S3 returns the HTTP status code304 Not Modified
:If-None-Match
condition evaluates tofalse
.If-Modified-Since
condition evaluates totrue
. For more information about conditional requests, see RFC 7232.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following actions are related to GetObjectAttributes
:
9022 9023 9024 9025 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9022 def get_object_attributes(params = {}, = {}) req = build_request(:get_object_attributes, params) req.send_request() end |
#get_object_legal_hold(params = {}) ⇒ Types::GetObjectLegalHoldOutput
Gets an object's current legal hold status. For more information, see Locking Objects.
This functionality is not supported for Amazon S3 on Outposts.
The following action is related to GetObjectLegalHold
:
^
9118 9119 9120 9121 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9118 def get_object_legal_hold(params = {}, = {}) req = build_request(:get_object_legal_hold, params) req.send_request() end |
#get_object_lock_configuration(params = {}) ⇒ Types::GetObjectLockConfigurationOutput
Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket. For more information, see Locking Objects.
The following action is related to GetObjectLockConfiguration
:
^
9188 9189 9190 9191 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9188 def get_object_lock_configuration(params = {}, = {}) req = build_request(:get_object_lock_configuration, params) req.send_request() end |
#get_object_retention(params = {}) ⇒ Types::GetObjectRetentionOutput
Retrieves an object's retention settings. For more information, see Locking Objects.
This functionality is not supported for Amazon S3 on Outposts.
The following action is related to GetObjectRetention
:
^
9285 9286 9287 9288 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9285 def get_object_retention(params = {}, = {}) req = build_request(:get_object_retention, params) req.send_request() end |
#get_object_tagging(params = {}) ⇒ Types::GetObjectTaggingOutput
Returns the tag-set of an object. You send the GET request against the tagging subresource associated with the object.
To use this operation, you must have permission to perform the
s3:GetObjectTagging
action. By default, the GET action returns
information about current version of an object. For a versioned
bucket, you can have multiple versions of an object in your bucket. To
retrieve tags of any other version, use the versionId query parameter.
You also need permission for the s3:GetObjectVersionTagging
action.
By default, the bucket owner has this permission and can grant this permission to others.
For information about the Amazon S3 object tagging feature, see Object Tagging.
The following actions are related to GetObjectTagging
:
9454 9455 9456 9457 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9454 def get_object_tagging(params = {}, = {}) req = build_request(:get_object_tagging, params) req.send_request() end |
#get_object_torrent(params = {}) ⇒ Types::GetObjectTorrentOutput
Returns torrent files from a bucket. BitTorrent can save you bandwidth when you're distributing large files.
To use GET, you must have READ access to the object.
This functionality is not supported for Amazon S3 on Outposts.
The following action is related to GetObjectTorrent
:
^
9555 9556 9557 9558 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9555 def get_object_torrent(params = {}, = {}, &block) req = build_request(:get_object_torrent, params) req.send_request(, &block) end |
#get_public_access_block(params = {}) ⇒ Types::GetPublicAccessBlockOutput
Retrieves the PublicAccessBlock
configuration for an Amazon S3
bucket. To use this operation, you must have the
s3:GetBucketPublicAccessBlock
permission. For more information about
Amazon S3 permissions, see Specifying Permissions in a Policy.
When Amazon S3 evaluates the PublicAccessBlock
configuration for a
bucket or an object, it checks the PublicAccessBlock
configuration
for both the bucket (or the bucket that contains the object) and the
bucket owner's account. If the PublicAccessBlock
settings are
different between the bucket and the account, Amazon S3 uses the most
restrictive combination of the bucket-level and account-level
settings.
For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of "Public".
The following operations are related to GetPublicAccessBlock
:
9630 9631 9632 9633 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9630 def get_public_access_block(params = {}, = {}) req = build_request(:get_public_access_block, params) req.send_request() end |
#head_bucket(params = {}) ⇒ Types::HeadBucketOutput
You can use this operation to determine if a bucket exists and if you
have permission to access it. The action returns a 200 OK
if the
bucket exists and you have permission to access it.
HEAD
request returns a generic 400 Bad Request
, 403
Forbidden
or 404 Not Found
code. A message body is not included, so
you cannot determine the exception beyond these HTTP response codes.
- Authentication and authorization
General purpose buckets - Request to public buckets that grant the s3:ListBucket permission publicly do not need to be signed. All other
HeadBucket
requests must be authenticated and signed by using IAM credentials (access key ID and secret access key for the IAM identities). All headers with thex-amz-
prefix, includingx-amz-copy-source
, must be signed. For more information, see REST Authentication.Directory buckets - You must use IAM credentials to authenticate and authorize your access to the
HeadBucket
API operation, instead of using the temporary security credentials through theCreateSession
API operation.Amazon Web Services CLI or SDKs handles authentication and authorization on your behalf.
Permissions
:
General purpose bucket permissions - To use this operation, you must have permissions to perform the
s3:ListBucket
action. The bucket owner has this permission by default and can grant this permission to others. For more information about permissions, see Managing access permissions to your Amazon S3 resources in the Amazon S3 User Guide.Directory bucket permissions - You must have the
s3express:CreateSession
permission in theAction
element of a policy. By default, the session is in theReadWrite
mode. If you want to restrict the access, you can explicitly set thes3express:SessionMode
condition key toReadOnly
on the bucket.For more information about example bucket policies, see Example bucket policies for S3 Express One Zone and Amazon Web Services Identity and Access Management (IAM) identity-based policies for S3 Express One Zone in the Amazon S3 User Guide.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.You must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format https://bucket_name.s3express-az_id.region.amazonaws.com
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
The following waiters are defined for this operation (see #wait_until for detailed usage):
- bucket_exists
- bucket_not_exists
9806 9807 9808 9809 |
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/client.rb', line 9806 def head_bucket(params = {}, = {}) req = build_request(:head_bucket, params) req.send_request() 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
interested only in an object's metadata.
HEAD
request has the same options as a GET
operation on an
object. The response is identical to the GET
response except that
there is no response body. Because of this, if the HEAD
request
generates an error, it returns a generic code, such as 400 Bad
Request
, 403 Forbidden
, 404 Not Found
, 405 Method Not Allowed
,
412 Precondition Failed
, or 304 Not Modified
. It's not possible
to retrieve the exact exception of these error codes.
Request headers are limited to 8 KB in size. For more information, see Common Request Headers.
Permissions
:
General purpose bucket permissions - To use
HEAD
, you must have thes3:GetObject
permission. You need the relevant read object (or version) permission for this operation. For more information, see Actions, resources, and condition keys for Amazon S3 in the Amazon S3 User Guide. For more information about the permissions to S3 API operations by S3 resource types, see Required permissions for Amazon S3 API operations in the Amazon S3 User Guide.If the object you request doesn't exist, the error that Amazon S3 returns depends on whether you also have the
s3:ListBucket
permission.If you have the
s3:ListBucket
permission on the bucket, Amazon S3 returns an HTTP status code404 Not Found
error.If you don’t have the
s3:ListBucket
permission, Amazon S3 returns an HTTP status code403 Forbidden
error.
Directory bucket permissions - To grant access to this API operation on a directory bucket, we recommend that you use the
CreateSession
API operation for session-based authorization. Specifically, you grant thes3express:CreateSession
permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSession
API call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSession
API call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession
.If you enable
x-amz-checksum-mode
in the request and the object is encrypted with Amazon Web Services Key Management Service (Amazon Web Services KMS), you must also have thekms:GenerateDataKey
andkms:Decrypt
permissions in IAM identity-based policies and KMS key policies for the KMS key to retrieve the checksum of the object.
- Encryption
Encryption request headers, like x-amz-server-side-encryption
, should not be sent forHEAD
requests if your object uses server-side encryption with Key Management Service (KMS) keys (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or server-side encryption with Amazon S3 managed encryption keys (SSE-S3). Thex-amz-server-side-encryption
header is used when youPUT
an object to S3 and want to specify the encryption method. If you include this header in aHEAD
request for an object that uses these types of keys, you’ll get an HTTP400 Bad Request
error. It's because the encryption method can't be changed when you retrieve the object.If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in Amazon S3, then when you retrieve the metadata from the object, you must use the following headers to provide the encryption key for the server to be able to retrieve the object's metadata. The headers are:
x-amz-server-side-encryption-customer-algorithm
x-amz-server-side-encryption-customer-key
x-amz-server-side-encryption-customer-key-MD5
For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon S3 User Guide.
Directory bucket - For directory buckets, there are only two supported options for server-side encryption: SSE-S3 and SSE-KMS. SSE-C isn't supported. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide. - Versioning
If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and includes
x-amz-delete-marker: true
in the response.If the specified version is a delete marker, the response returns a
405 Method Not Allowed
error and theLast-Modified: timestamp
response header.
* Directory buckets - Delete marker is not supported for directory buckets. - Directory buckets - S3 Versioning isn't enabled and supported
for directory buckets. For this API operation, only the
null
value of the version ID is supported by directory buckets. You can only specifynull
to theversionId
query parameter in the request.
- HTTP Host header syntax
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.For directory buckets, you must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide.
The following actions are related to HeadObject
:
The following waiters are defined for this operation (see #wait_until for detailed usage):
- object_exists
- object_not_exists