AbortMultipartUpload

$result = $client->abortMultipartUpload([/* ... */]);
$promise = $client->abortMultipartUploadAsync([/* ... */]);

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.

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 the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession 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 another CreateSession 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, see CreateSession .

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:

• CreateMultipartUpload

• UploadPart

• CompleteMultipartUpload

• ListParts

• ListMultipartUploads

Parameter Syntax

$result = $client->abortMultipartUpload([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'IfMatchInitiatedTime' => <integer || string || DateTime>,
    'Key' => '<string>', // REQUIRED
    'RequestPayer' => 'requester',
    'UploadId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'RequestCharged' => 'requester',
]

Result Details

Errors

NoSuchUpload:

The specified multipart upload does not exist.

Examples

Example 1: To abort a multipart upload

The following example aborts a multipart upload.

$result = $client->abortMultipartUpload([
    'Bucket' => 'examplebucket',
    'Key' => 'bigobject',
    'UploadId' => 'xadcOB_7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--',
]);

Result syntax:

[
]

CompleteMultipartUpload

$result = $client->completeMultipartUpload([/* ... */]);
$promise = $client->completeMultipartUploadAsync([/* ... */]);

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.

For more information about multipart uploads, see Uploading Objects Using Multipart Upload 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 the kms:Decrypt action for the CompleteMultipartUpload 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 the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession 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 another CreateSession 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, see CreateSession .

  If the object is encrypted with SSE-KMS, you must also have the kms:GenerateDataKey and kms: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:

• CreateMultipartUpload

• UploadPart

• AbortMultipartUpload

• ListParts

• ListMultipartUploads

Additional info on response behavior: if there is an internal error in S3 after the request was successfully recieved, a 200 response will be returned with an S3Exception embedded in it; this will still be caught and retried by RetryMiddleware.

Parameter Syntax

$result = $client->completeMultipartUpload([
    'Bucket' => '<string>', // REQUIRED
    'ChecksumCRC32' => '<string>',
    'ChecksumCRC32C' => '<string>',
    'ChecksumSHA1' => '<string>',
    'ChecksumSHA256' => '<string>',
    'ExpectedBucketOwner' => '<string>',
    'IfNoneMatch' => '<string>',
    'Key' => '<string>', // REQUIRED
    'MultipartUpload' => [
        'Parts' => [
            [
                'ChecksumCRC32' => '<string>',
                'ChecksumCRC32C' => '<string>',
                'ChecksumSHA1' => '<string>',
                'ChecksumSHA256' => '<string>',
                'ETag' => '<string>',
                'PartNumber' => <integer>,
            ],
            // ...
        ],
    ],
    'RequestPayer' => 'requester',
    'SSECustomerAlgorithm' => '<string>',
    'SSECustomerKey' => '<string>',
    'SSECustomerKeyMD5' => '<string>',
    'UploadId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Bucket' => '<string>',
    'BucketKeyEnabled' => true || false,
    'ChecksumCRC32' => '<string>',
    'ChecksumCRC32C' => '<string>',
    'ChecksumSHA1' => '<string>',
    'ChecksumSHA256' => '<string>',
    'ETag' => '<string>',
    'Expiration' => '<string>',
    'Key' => '<string>',
    'Location' => '<string>',
    'ObjectURL' => '<string>',
    'RequestCharged' => 'requester',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'VersionId' => '<string>',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To complete multipart upload

The following example completes a multipart upload.

$result = $client->completeMultipartUpload([
    'Bucket' => 'examplebucket',
    'Key' => 'bigobject',
    'MultipartUpload' => [
        'Parts' => [
            [
                'ETag' => '"d8c2eafd90c266e19ab9dcacc479f8af"',
                'PartNumber' => 1,
            ],
            [
                'ETag' => '"d8c2eafd90c266e19ab9dcacc479f8af"',
                'PartNumber' => 2,
            ],
        ],
    ],
    'UploadId' => '7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--',
]);

Result syntax:

[
    'Bucket' => 'acexamplebucket',
    'ETag' => '"4d9031c7644d8081c2829f4ea23c55f7-2"',
    'Key' => 'bigobject',
    'Location' => 'https://examplebucket.s3..amazonaws.com/bigobject',
]

CopyObject

$result = $client->copyObject([/* ... */]);
$promise = $client->copyObjectAsync([/* ... */]);

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.

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.

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 the x-amz- prefix, including x-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 the CreateSession 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 the Action element of a policy to read the object. By default, the session is in the ReadWrite mode. If you want to restrict the access, you can explicitly set the s3express:SessionMode condition key to ReadOnly on the copy source bucket.

  • If the copy destination is a directory bucket, you must have the s3express:CreateSession permission in the Action element of a policy to write the object to the destination. The s3express:SessionMode condition key can't be set to ReadOnly on the copy destination bucket.

  If the object is encrypted with SSE-KMS, you must also have the kms:GenerateDataKey and kms: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 a 200 OK response. For more information, see Resolve the Error 200 response when copying objects to Amazon S3. The 200 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 a 200 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:

• PutObject

• GetObject

Additional info on response behavior: if there is an internal error in S3 after the request was successfully recieved, a 200 response will be returned with an S3Exception embedded in it; this will still be caught and retried by RetryMiddleware.

Parameter Syntax

$result = $client->copyObject([
    'ACL' => 'private|public-read|public-read-write|authenticated-read|aws-exec-read|bucket-owner-read|bucket-owner-full-control',
    'Bucket' => '<string>', // REQUIRED
    'BucketKeyEnabled' => true || false,
    'CacheControl' => '<string>',
    'ChecksumAlgorithm' => 'CRC32|CRC32C|SHA1|SHA256',
    'ContentDisposition' => '<string>',
    'ContentEncoding' => '<string>',
    'ContentLanguage' => '<string>',
    'ContentType' => '<string>',
    'CopySource' => '<string>', // REQUIRED
    'CopySourceIfMatch' => '<string>',
    'CopySourceIfModifiedSince' => <integer || string || DateTime>,
    'CopySourceIfNoneMatch' => '<string>',
    'CopySourceIfUnmodifiedSince' => <integer || string || DateTime>,
    'CopySourceSSECustomerAlgorithm' => '<string>',
    'CopySourceSSECustomerKey' => '<string>',
    'CopySourceSSECustomerKeyMD5' => '<string>',
    'ExpectedBucketOwner' => '<string>',
    'ExpectedSourceBucketOwner' => '<string>',
    'Expires' => <integer || string || DateTime>,
    'GrantFullControl' => '<string>',
    'GrantRead' => '<string>',
    'GrantReadACP' => '<string>',
    'GrantWriteACP' => '<string>',
    'Key' => '<string>', // REQUIRED
    'Metadata' => ['<string>', ...],
    'MetadataDirective' => 'COPY|REPLACE',
    'ObjectLockLegalHoldStatus' => 'ON|OFF',
    'ObjectLockMode' => 'GOVERNANCE|COMPLIANCE',
    'ObjectLockRetainUntilDate' => <integer || string || DateTime>,
    'RequestPayer' => 'requester',
    'SSECustomerAlgorithm' => '<string>',
    'SSECustomerKey' => '<string>',
    'SSECustomerKeyMD5' => '<string>',
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'StorageClass' => 'STANDARD|REDUCED_REDUNDANCY|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|GLACIER|DEEP_ARCHIVE|OUTPOSTS|GLACIER_IR|SNOW|EXPRESS_ONEZONE',
    'Tagging' => '<string>',
    'TaggingDirective' => 'COPY|REPLACE',
    'WebsiteRedirectLocation' => '<string>',
]);

Parameter Details

Result Syntax

[
    'BucketKeyEnabled' => true || false,
    'CopyObjectResult' => [
        'ChecksumCRC32' => '<string>',
        'ChecksumCRC32C' => '<string>',
        'ChecksumSHA1' => '<string>',
        'ChecksumSHA256' => '<string>',
        'ETag' => '<string>',
        'LastModified' => <DateTime>,
    ],
    'CopySourceVersionId' => '<string>',
    'Expiration' => '<string>',
    'ObjectURL' => '<string>',
    'RequestCharged' => 'requester',
    'SSECustomerAlgorithm' => '<string>',
    'SSECustomerKeyMD5' => '<string>',
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'VersionId' => '<string>',
]

Result Details

Errors

ObjectNotInActiveTierError:

The source object of the COPY action is not in the active tier and is only stored in Amazon S3 Glacier.

Examples

Example 1: To copy an object

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

$result = $client->copyObject([
    'Bucket' => 'destinationbucket',
    'CopySource' => '/sourcebucket/HappyFacejpg',
    'Key' => 'HappyFaceCopyjpg',
]);

Result syntax:

[
    'CopyObjectResult' => [
        'ETag' => '"6805f2cfc46c0f04559748bb039d69ae"',
        'LastModified' => ,
    ],
]

CreateBucket

$result = $client->createBucket([/* ... */]);
$promise = $client->createBucketAsync([/* ... */]);

This action creates an Amazon S3 bucket. To create an Amazon S3 on Outposts bucket, see 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.

Permissions

• General purpose bucket permissions - In addition to the s3:CreateBucket permission, the following permissions are required in a policy when your CreateBucket request includes specific headers:

  • Access control lists (ACLs) - In your CreateBucket request, if you specify an access control list (ACL) and set it to public-read, public-read-write, authenticated-read, or if you explicitly specify any other custom ACLs, both s3:CreateBucket and s3:PutBucketAcl permissions are required. In your CreateBucket request, if you set the ACL to private, or if you don't specify any ACLs, only the s3:CreateBucket permission is required.

  • Object Lock - In your CreateBucket request, if you set x-amz-bucket-object-lock-enabled to true, the s3:PutBucketObjectLockConfiguration and s3:PutBucketVersioning permissions are required.

  • S3 Object Ownership - If your CreateBucket request includes the x-amz-object-ownership header, then the s3: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 using PutBucketAcl 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 the s3: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:

• PutObject

• DeleteBucket

Parameter Syntax

$result = $client->createBucket([
    'ACL' => 'private|public-read|public-read-write|authenticated-read',
    'Bucket' => '<string>', // REQUIRED
    'CreateBucketConfiguration' => [
        'Bucket' => [
            'DataRedundancy' => 'SingleAvailabilityZone',
            'Type' => 'Directory',
        ],
        'Location' => [
            'Name' => '<string>',
            'Type' => 'AvailabilityZone',
        ],
        'LocationConstraint' => 'ap-northeast-1|ap-southeast-2|ap-southeast-1|cn-north-1|eu-central-1|eu-west-1|us-east-1|us-west-1|us-west-2|sa-east-1',
    ],
    'GrantFullControl' => '<string>',
    'GrantRead' => '<string>',
    'GrantReadACP' => '<string>',
    'GrantWrite' => '<string>',
    'GrantWriteACP' => '<string>',
    'ObjectLockEnabledForBucket' => true || false,
    'ObjectOwnership' => 'BucketOwnerPreferred|ObjectWriter|BucketOwnerEnforced',
]);

Parameter Details

Result Syntax

[
    'Location' => '<string>',
]

Result Details

Errors

BucketAlreadyExists:

The requested bucket name is not available. The bucket namespace is shared by all users of the system. Select a different name and try again.

BucketAlreadyOwnedByYou:

The bucket you tried to create already exists, and you own it. Amazon S3 returns this error in all Amazon Web Services Regions except in the North Virginia Region. For legacy compatibility, if you re-create an existing bucket that you already own in the North Virginia Region, Amazon S3 returns 200 OK and resets the bucket access control lists (ACLs).

Examples

Example 1: To create a bucket

The following example creates a bucket.

$result = $client->createBucket([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'Location' => '/examplebucket',
]

Example 2: To create a bucket in a specific region

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

$result = $client->createBucket([
    'Bucket' => 'examplebucket',
    'CreateBucketConfiguration' => [
        'LocationConstraint' => 'eu-west-1',
    ],
]);

Result syntax:

[
    'Location' => 'http://examplebucket..s3.amazonaws.com/',
]

CreateMultipartUpload

$result = $client->createMultipartUpload([/* ... */]);
$promise = $client->createMultipartUploadAsync([/* ... */]);

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.

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 and kms:GenerateDataKey actions on the key. The requester must also have permissions for the kms:GenerateDataKey action for the CreateMultipartUpload API. Then, the requester needs permissions for the kms:Decrypt action on the UploadPart and UploadPartCopy 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 the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession 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 another CreateSession 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, see CreateSession .

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 provide x-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 and kms: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 and PUT 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 your CreateSession requests or PUT 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, and x-amz-server-side-encryption-bucket-key-enabled) that are specified in the CreateSession 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 the CreateSession 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 the CreateSession request. It's not supported to override the encryption settings values in the CreateSession 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 an UploadPartCopy operation, the request headers you provide in the CreateMultipartUpload 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:

• UploadPart

• CompleteMultipartUpload

• AbortMultipartUpload

• ListParts

• ListMultipartUploads

Parameter Syntax

$result = $client->createMultipartUpload([
    'ACL' => 'private|public-read|public-read-write|authenticated-read|aws-exec-read|bucket-owner-read|bucket-owner-full-control',
    'Bucket' => '<string>', // REQUIRED
    'BucketKeyEnabled' => true || false,
    'CacheControl' => '<string>',
    'ChecksumAlgorithm' => 'CRC32|CRC32C|SHA1|SHA256',
    'ContentDisposition' => '<string>',
    'ContentEncoding' => '<string>',
    'ContentLanguage' => '<string>',
    'ContentType' => '<string>',
    'ExpectedBucketOwner' => '<string>',
    'Expires' => <integer || string || DateTime>,
    'GrantFullControl' => '<string>',
    'GrantRead' => '<string>',
    'GrantReadACP' => '<string>',
    'GrantWriteACP' => '<string>',
    'Key' => '<string>', // REQUIRED
    'Metadata' => ['<string>', ...],
    'ObjectLockLegalHoldStatus' => 'ON|OFF',
    'ObjectLockMode' => 'GOVERNANCE|COMPLIANCE',
    'ObjectLockRetainUntilDate' => <integer || string || DateTime>,
    'RequestPayer' => 'requester',
    'SSECustomerAlgorithm' => '<string>',
    'SSECustomerKey' => '<string>',
    'SSECustomerKeyMD5' => '<string>',
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'StorageClass' => 'STANDARD|REDUCED_REDUNDANCY|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|GLACIER|DEEP_ARCHIVE|OUTPOSTS|GLACIER_IR|SNOW|EXPRESS_ONEZONE',
    'Tagging' => '<string>',
    'WebsiteRedirectLocation' => '<string>',
]);

Parameter Details

Result Syntax

[
    'AbortDate' => <DateTime>,
    'AbortRuleId' => '<string>',
    'Bucket' => '<string>',
    'BucketKeyEnabled' => true || false,
    'ChecksumAlgorithm' => 'CRC32|CRC32C|SHA1|SHA256',
    'Key' => '<string>',
    'RequestCharged' => 'requester',
    'SSECustomerAlgorithm' => '<string>',
    'SSECustomerKeyMD5' => '<string>',
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'UploadId' => '<string>',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To initiate a multipart upload

The following example initiates a multipart upload.

$result = $client->createMultipartUpload([
    'Bucket' => 'examplebucket',
    'Key' => 'largeobject',
]);

Result syntax:

[
    'Bucket' => 'examplebucket',
    'Key' => 'largeobject',
    'UploadId' => 'ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--',
]

CreateSession

$result = $client->createSession([/* ... */]);
$promise = $client->createSessionAsync([/* ... */]);

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.

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 the s3express:SessionMode condition key to control who can create a ReadWrite or ReadOnly session. For more information about ReadWrite or ReadOnly sessions, see x-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 the kms: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 your CreateSession requests or PUT 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, and x-amz-server-side-encryption-bucket-key-enabled) from the CreateSession 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 the CreateSession 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 the CreateSession request. It's not supported to override the encryption settings values in the CreateSession 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 the CreateSession request.

HTTP Host header syntax

Directory buckets - The HTTP Host header syntax is Bucket_name.s3express-az_id.region.amazonaws.com.

Parameter Syntax

$result = $client->createSession([
    'Bucket' => '<string>', // REQUIRED
    'BucketKeyEnabled' => true || false,
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
    'SessionMode' => 'ReadOnly|ReadWrite',
]);

Parameter Details

Result Syntax

[
    'BucketKeyEnabled' => true || false,
    'Credentials' => [
        'AccessKeyId' => '<string>',
        'Expiration' => <DateTime>,
        'SecretAccessKey' => '<string>',
        'SessionToken' => '<string>',
    ],
    'SSEKMSEncryptionContext' => '<string>',
    'SSEKMSKeyId' => '<string>',
    'ServerSideEncryption' => 'AES256|aws:kms|aws:kms:dsse',
]

Result Details

Errors

NoSuchBucket:

The specified bucket does not exist.

DeleteBucket

$result = $client->deleteBucket([/* ... */]);
$promise = $client->deleteBucketAsync([/* ... */]);

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.

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:

• CreateBucket

• DeleteObject

Parameter Syntax

$result = $client->deleteBucket([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete a bucket

The following example deletes the specified bucket.

$result = $client->deleteBucket([
    'Bucket' => 'forrandall2',
]);

DeleteBucketAnalyticsConfiguration

$result = $client->deleteBucketAnalyticsConfiguration([/* ... */]);
$promise = $client->deleteBucketAnalyticsConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketAnalyticsConfiguration

• ListBucketAnalyticsConfigurations

• PutBucketAnalyticsConfiguration

Parameter Syntax

$result = $client->deleteBucketAnalyticsConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketCors

$result = $client->deleteBucketCors([/* ... */]);
$promise = $client->deleteBucketCorsAsync([/* ... */]);

This operation is not supported for directory buckets.

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

• PutBucketCors

• RESTOPTIONSobject

Parameter Syntax

$result = $client->deleteBucketCors([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete cors configuration on a bucket.

The following example deletes CORS configuration on a bucket.

$result = $client->deleteBucketCors([
    'Bucket' => 'examplebucket',
]);

DeleteBucketEncryption

$result = $client->deleteBucketEncryption([/* ... */]);
$promise = $client->deleteBucketEncryptionAsync([/* ... */]);

This implementation of the DELETE action resets the default encryption for the bucket as server-side encryption with Amazon S3 managed keys (SSE-S3).

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:

• PutBucketEncryption

• GetBucketEncryption

Parameter Syntax

$result = $client->deleteBucketEncryption([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketIntelligentTieringConfiguration

$result = $client->deleteBucketIntelligentTieringConfiguration([/* ... */]);
$promise = $client->deleteBucketIntelligentTieringConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketIntelligentTieringConfiguration

• PutBucketIntelligentTieringConfiguration

• ListBucketIntelligentTieringConfigurations

Parameter Syntax

$result = $client->deleteBucketIntelligentTieringConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketInventoryConfiguration

$result = $client->deleteBucketInventoryConfiguration([/* ... */]);
$promise = $client->deleteBucketInventoryConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketInventoryConfiguration

• PutBucketInventoryConfiguration

• ListBucketInventoryConfigurations

Parameter Syntax

$result = $client->deleteBucketInventoryConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketLifecycle

$result = $client->deleteBucketLifecycle([/* ... */]);
$promise = $client->deleteBucketLifecycleAsync([/* ... */]);

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:

• PutBucketLifecycleConfiguration

• GetBucketLifecycleConfiguration

Parameter Syntax

$result = $client->deleteBucketLifecycle([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete lifecycle configuration on a bucket.

The following example deletes lifecycle configuration on a bucket.

$result = $client->deleteBucketLifecycle([
    'Bucket' => 'examplebucket',
]);

DeleteBucketMetricsConfiguration

$result = $client->deleteBucketMetricsConfiguration([/* ... */]);
$promise = $client->deleteBucketMetricsConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketMetricsConfiguration

• PutBucketMetricsConfiguration

• ListBucketMetricsConfigurations

• Monitoring Metrics with Amazon CloudWatch

Parameter Syntax

$result = $client->deleteBucketMetricsConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketOwnershipControls

$result = $client->deleteBucketOwnershipControls([/* ... */]);
$promise = $client->deleteBucketOwnershipControlsAsync([/* ... */]);

This operation is not supported for directory buckets.

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

Parameter Syntax

$result = $client->deleteBucketOwnershipControls([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

DeleteBucketPolicy

$result = $client->deleteBucketPolicy([/* ... */]);
$promise = $client->deleteBucketPolicyAsync([/* ... */]);

Deletes the policy of a specified bucket.

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 a 403 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 a 405 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, and DeleteBucketPolicy 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

• CreateBucket

• DeleteObject

Parameter Syntax

$result = $client->deleteBucketPolicy([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete bucket policy

The following example deletes bucket policy on the specified bucket.

$result = $client->deleteBucketPolicy([
    'Bucket' => 'examplebucket',
]);

DeleteBucketReplication

$result = $client->deleteBucketReplication([/* ... */]);
$promise = $client->deleteBucketReplicationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutBucketReplication

• GetBucketReplication

Parameter Syntax

$result = $client->deleteBucketReplication([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete bucket replication configuration

The following example deletes replication configuration set on bucket.

$result = $client->deleteBucketReplication([
    'Bucket' => 'example',
]);

DeleteBucketTagging

$result = $client->deleteBucketTagging([/* ... */]);
$promise = $client->deleteBucketTaggingAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketTagging

• PutBucketTagging

Parameter Syntax

$result = $client->deleteBucketTagging([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete bucket tags

The following example deletes bucket tags.

$result = $client->deleteBucketTagging([
    'Bucket' => 'examplebucket',
]);

DeleteBucketWebsite

$result = $client->deleteBucketWebsite([/* ... */]);
$promise = $client->deleteBucketWebsiteAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetBucketWebsite

• PutBucketWebsite

Parameter Syntax

$result = $client->deleteBucketWebsite([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete bucket website configuration

The following example deletes bucket website configuration.

$result = $client->deleteBucketWebsite([
    'Bucket' => 'examplebucket',
]);

DeleteObject

$result = $client->deleteObject([/* ... */]);
$promise = $client->deleteObjectAsync([/* ... */]);

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.

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 the s3: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 the s3: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, and s3: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:

• PutObject

Parameter Syntax

$result = $client->deleteObject([
    'Bucket' => '<string>', // REQUIRED
    'BypassGovernanceRetention' => true || false,
    'ExpectedBucketOwner' => '<string>',
    'IfMatch' => '<string>',
    'IfMatchLastModifiedTime' => <integer || string || DateTime>,
    'IfMatchSize' => <integer>,
    'Key' => '<string>', // REQUIRED
    'MFA' => '<string>',
    'RequestPayer' => 'requester',
    'VersionId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'DeleteMarker' => true || false,
    'RequestCharged' => 'requester',
    'VersionId' => '<string>',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete an object

The following example deletes an object from an S3 bucket.

$result = $client->deleteObject([
    'Bucket' => 'examplebucket',
    'Key' => 'objectkey.jpg',
]);

Result syntax:

[
]

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

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

$result = $client->deleteObject([
    'Bucket' => 'ExampleBucket',
    'Key' => 'HappyFace.jpg',
]);

DeleteObjectTagging

$result = $client->deleteObjectTagging([/* ... */]);
$promise = $client->deleteObjectTaggingAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutObjectTagging

• GetObjectTagging

Parameter Syntax

$result = $client->deleteObjectTagging([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Key' => '<string>', // REQUIRED
    'VersionId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'VersionId' => '<string>',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To remove tag set from an object

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

$result = $client->deleteObjectTagging([
    'Bucket' => 'examplebucket',
    'Key' => 'HappyFace.jpg',
]);

Result syntax:

[
    'VersionId' => 'null',
]

Example 2: To remove tag set from an object version

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

$result = $client->deleteObjectTagging([
    'Bucket' => 'examplebucket',
    'Key' => 'HappyFace.jpg',
    'VersionId' => 'ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI',
]);

Result syntax:

[
    'VersionId' => 'ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI',
]

DeleteObjects

$result = $client->deleteObjects([/* ... */]);
$promise = $client->deleteObjectsAsync([/* ... */]);

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.

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 the s3:DeleteObject permission.

  • s3:DeleteObjectVersion - To delete a specific version of an object from a versioning-enabled bucket, you must specify the s3: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 the s3express:CreateSession permission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make the CreateSession 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 another CreateSession 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, see CreateSession .

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, or x-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:

• CreateMultipartUpload

• UploadPart

• CompleteMultipartUpload

• ListParts

• AbortMultipartUpload

Parameter Syntax

$result = $client->deleteObjects([
    'Bucket' => '<string>', // REQUIRED
    'BypassGovernanceRetention' => true || false,
    'ChecksumAlgorithm' => 'CRC32|CRC32C|SHA1|SHA256',
    'Delete' => [ // REQUIRED
        'Objects' => [ // REQUIRED
            [
                'ETag' => '<string>',
                'Key' => '<string>', // REQUIRED
                'LastModifiedTime' => <integer || string || DateTime>,
                'Size' => <integer>,
                'VersionId' => '<string>',
            ],
            // ...
        ],
        'Quiet' => true || false,
    ],
    'ExpectedBucketOwner' => '<string>',
    'MFA' => '<string>',
    'RequestPayer' => 'requester',
]);

Parameter Details

Result Syntax

[
    'Deleted' => [
        [
            'DeleteMarker' => true || false,
            'DeleteMarkerVersionId' => '<string>',
            'Key' => '<string>',
            'VersionId' => '<string>',
        ],
        // ...
    ],
    'Errors' => [
        [
            'Code' => '<string>',
            'Key' => '<string>',
            'Message' => '<string>',
            'VersionId' => '<string>',
        ],
        // ...
    ],
    'RequestCharged' => 'requester',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To delete multiple object versions from a versioned bucket

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

$result = $client->deleteObjects([
    'Bucket' => 'examplebucket',
    'Delete' => [
        'Objects' => [
            [
                'Key' => 'HappyFace.jpg',
                'VersionId' => '2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b',
            ],
            [
                'Key' => 'HappyFace.jpg',
                'VersionId' => 'yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd',
            ],
        ],
        'Quiet' => ,
    ],
]);

Result syntax:

[
    'Deleted' => [
        [
            'Key' => 'HappyFace.jpg',
            'VersionId' => 'yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd',
        ],
        [
            'Key' => 'HappyFace.jpg',
            'VersionId' => '2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b',
        ],
    ],
]

Example 2: To delete multiple objects from a versioned bucket

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

$result = $client->deleteObjects([
    'Bucket' => 'examplebucket',
    'Delete' => [
        'Objects' => [
            [
                'Key' => 'objectkey1',
            ],
            [
                'Key' => 'objectkey2',
            ],
        ],
        'Quiet' => ,
    ],
]);

Result syntax:

[
    'Deleted' => [
        [
            'DeleteMarker' => true,
            'DeleteMarkerVersionId' => 'A._w1z6EFiCF5uhtQMDal9JDkID9tQ7F',
            'Key' => 'objectkey1',
        ],
        [
            'DeleteMarker' => true,
            'DeleteMarkerVersionId' => 'iOd_ORxhkKe_e8G8_oSGxt2PjsCZKlkt',
            'Key' => 'objectkey2',
        ],
    ],
]

DeletePublicAccessBlock

$result = $client->deletePublicAccessBlock([/* ... */]);
$promise = $client->deletePublicAccessBlockAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• Using Amazon S3 Block Public Access

• GetPublicAccessBlock

• PutPublicAccessBlock

• GetBucketPolicyStatus

Parameter Syntax

$result = $client->deletePublicAccessBlock([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

There are no errors described for this operation.

GetBucketAccelerateConfiguration

$result = $client->getBucketAccelerateConfiguration([/* ... */]);
$promise = $client->getBucketAccelerateConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutBucketAccelerateConfiguration

Parameter Syntax

$result = $client->getBucketAccelerateConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'RequestPayer' => 'requester',
]);

Parameter Details

Result Syntax

[
    'RequestCharged' => 'requester',
    'Status' => 'Enabled|Suspended',
]

Result Details

Errors

There are no errors described for this operation.

GetBucketAcl

$result = $client->getBucketAcl([/* ... */]);
$promise = $client->getBucketAclAsync([/* ... */]);

This operation is not supported for directory buckets.

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.

The following operations are related to GetBucketAcl:

• ListObjects

Parameter Syntax

$result = $client->getBucketAcl([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'Grants' => [
        [
            'Grantee' => [
                'DisplayName' => '<string>',
                'EmailAddress' => '<string>',
                'ID' => '<string>',
                'Type' => 'CanonicalUser|AmazonCustomerByEmail|Group',
                'URI' => '<string>',
            ],
            'Permission' => 'FULL_CONTROL|WRITE|WRITE_ACP|READ|READ_ACP',
        ],
        // ...
    ],
    'Owner' => [
        'DisplayName' => '<string>',
        'ID' => '<string>',
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketAnalyticsConfiguration

$result = $client->getBucketAnalyticsConfiguration([/* ... */]);
$promise = $client->getBucketAnalyticsConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• DeleteBucketAnalyticsConfiguration

• ListBucketAnalyticsConfigurations

• PutBucketAnalyticsConfiguration

Parameter Syntax

$result = $client->getBucketAnalyticsConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'AnalyticsConfiguration' => [
        'Filter' => [
            'And' => [
                'Prefix' => '<string>',
                'Tags' => [
                    [
                        'Key' => '<string>',
                        'Value' => '<string>',
                    ],
                    // ...
                ],
            ],
            'Prefix' => '<string>',
            'Tag' => [
                'Key' => '<string>',
                'Value' => '<string>',
            ],
        ],
        'Id' => '<string>',
        'StorageClassAnalysis' => [
            'DataExport' => [
                'Destination' => [
                    'S3BucketDestination' => [
                        'Bucket' => '<string>',
                        'BucketAccountId' => '<string>',
                        'Format' => 'CSV',
                        'Prefix' => '<string>',
                    ],
                ],
                'OutputSchemaVersion' => 'V_1',
            ],
        ],
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketCors

$result = $client->getBucketCors([/* ... */]);
$promise = $client->getBucketCorsAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutBucketCors

• DeleteBucketCors

Parameter Syntax

$result = $client->getBucketCors([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'CORSRules' => [
        [
            'AllowedHeaders' => ['<string>', ...],
            'AllowedMethods' => ['<string>', ...],
            'AllowedOrigins' => ['<string>', ...],
            'ExposeHeaders' => ['<string>', ...],
            'ID' => '<string>',
            'MaxAgeSeconds' => <integer>,
        ],
        // ...
    ],
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get cors configuration set on a bucket

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

$result = $client->getBucketCors([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'CORSRules' => [
        [
            'AllowedHeaders' => [
                'Authorization',
            ],
            'AllowedMethods' => [
                'GET',
            ],
            'AllowedOrigins' => [
                '*',
            ],
            'MaxAgeSeconds' => 3000,
        ],
    ],
]

GetBucketEncryption

$result = $client->getBucketEncryption([/* ... */]);
$promise = $client->getBucketEncryptionAsync([/* ... */]);

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).

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:

• PutBucketEncryption

• DeleteBucketEncryption

Parameter Syntax

$result = $client->getBucketEncryption([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'ServerSideEncryptionConfiguration' => [
        'Rules' => [
            [
                'ApplyServerSideEncryptionByDefault' => [
                    'KMSMasterKeyID' => '<string>',
                    'SSEAlgorithm' => 'AES256|aws:kms|aws:kms:dsse',
                ],
                'BucketKeyEnabled' => true || false,
            ],
            // ...
        ],
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketIntelligentTieringConfiguration

$result = $client->getBucketIntelligentTieringConfiguration([/* ... */]);
$promise = $client->getBucketIntelligentTieringConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• DeleteBucketIntelligentTieringConfiguration

• PutBucketIntelligentTieringConfiguration

• ListBucketIntelligentTieringConfigurations

Parameter Syntax

$result = $client->getBucketIntelligentTieringConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'IntelligentTieringConfiguration' => [
        'Filter' => [
            'And' => [
                'Prefix' => '<string>',
                'Tags' => [
                    [
                        'Key' => '<string>',
                        'Value' => '<string>',
                    ],
                    // ...
                ],
            ],
            'Prefix' => '<string>',
            'Tag' => [
                'Key' => '<string>',
                'Value' => '<string>',
            ],
        ],
        'Id' => '<string>',
        'Status' => 'Enabled|Disabled',
        'Tierings' => [
            [
                'AccessTier' => 'ARCHIVE_ACCESS|DEEP_ARCHIVE_ACCESS',
                'Days' => <integer>,
            ],
            // ...
        ],
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketInventoryConfiguration

$result = $client->getBucketInventoryConfiguration([/* ... */]);
$promise = $client->getBucketInventoryConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• DeleteBucketInventoryConfiguration

• ListBucketInventoryConfigurations

• PutBucketInventoryConfiguration

Parameter Syntax

$result = $client->getBucketInventoryConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'InventoryConfiguration' => [
        'Destination' => [
            'S3BucketDestination' => [
                'AccountId' => '<string>',
                'Bucket' => '<string>',
                'Encryption' => [
                    'SSEKMS' => [
                        'KeyId' => '<string>',
                    ],
                    'SSES3' => [
                    ],
                ],
                'Format' => 'CSV|ORC|Parquet',
                'Prefix' => '<string>',
            ],
        ],
        'Filter' => [
            'Prefix' => '<string>',
        ],
        'Id' => '<string>',
        'IncludedObjectVersions' => 'All|Current',
        'IsEnabled' => true || false,
        'OptionalFields' => ['<string>', ...],
        'Schedule' => [
            'Frequency' => 'Daily|Weekly',
        ],
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketLifecycle

$result = $client->getBucketLifecycle([/* ... */]);
$promise = $client->getBucketLifecycleAsync([/* ... */]);

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:

• GetBucketLifecycleConfiguration

• PutBucketLifecycle

• DeleteBucketLifecycle

Parameter Syntax

$result = $client->getBucketLifecycle([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'Rules' => [
        [
            'AbortIncompleteMultipartUpload' => [
                'DaysAfterInitiation' => <integer>,
            ],
            'Expiration' => [
                'Date' => <DateTime>,
                'Days' => <integer>,
                'ExpiredObjectDeleteMarker' => true || false,
            ],
            'ID' => '<string>',
            'NoncurrentVersionExpiration' => [
                'NewerNoncurrentVersions' => <integer>,
                'NoncurrentDays' => <integer>,
            ],
            'NoncurrentVersionTransition' => [
                'NewerNoncurrentVersions' => <integer>,
                'NoncurrentDays' => <integer>,
                'StorageClass' => 'GLACIER|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|DEEP_ARCHIVE|GLACIER_IR',
            ],
            'Prefix' => '<string>',
            'Status' => 'Enabled|Disabled',
            'Transition' => [
                'Date' => <DateTime>,
                'Days' => <integer>,
                'StorageClass' => 'GLACIER|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|DEEP_ARCHIVE|GLACIER_IR',
            ],
        ],
        // ...
    ],
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get a bucket acl

The following example gets ACL on the specified bucket.

$result = $client->getBucketLifecycle([
    'Bucket' => 'acl1',
]);

Result syntax:

[
    'Rules' => [
        [
            'Expiration' => [
                'Days' => 1,
            ],
            'ID' => 'delete logs',
            'Prefix' => '123/',
            'Status' => 'Enabled',
        ],
    ],
]

GetBucketLifecycleConfiguration

$result = $client->getBucketLifecycleConfiguration([/* ... */]);
$promise = $client->getBucketLifecycleConfigurationAsync([/* ... */]);

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:

• GetBucketLifecycle

• PutBucketLifecycle

• DeleteBucketLifecycle

Parameter Syntax

$result = $client->getBucketLifecycleConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'Rules' => [
        [
            'AbortIncompleteMultipartUpload' => [
                'DaysAfterInitiation' => <integer>,
            ],
            'Expiration' => [
                'Date' => <DateTime>,
                'Days' => <integer>,
                'ExpiredObjectDeleteMarker' => true || false,
            ],
            'Filter' => [
                'And' => [
                    'ObjectSizeGreaterThan' => <integer>,
                    'ObjectSizeLessThan' => <integer>,
                    'Prefix' => '<string>',
                    'Tags' => [
                        [
                            'Key' => '<string>',
                            'Value' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'ObjectSizeGreaterThan' => <integer>,
                'ObjectSizeLessThan' => <integer>,
                'Prefix' => '<string>',
                'Tag' => [
                    'Key' => '<string>',
                    'Value' => '<string>',
                ],
            ],
            'ID' => '<string>',
            'NoncurrentVersionExpiration' => [
                'NewerNoncurrentVersions' => <integer>,
                'NoncurrentDays' => <integer>,
            ],
            'NoncurrentVersionTransitions' => [
                [
                    'NewerNoncurrentVersions' => <integer>,
                    'NoncurrentDays' => <integer>,
                    'StorageClass' => 'GLACIER|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|DEEP_ARCHIVE|GLACIER_IR',
                ],
                // ...
            ],
            'Prefix' => '<string>',
            'Status' => 'Enabled|Disabled',
            'Transitions' => [
                [
                    'Date' => <DateTime>,
                    'Days' => <integer>,
                    'StorageClass' => 'GLACIER|STANDARD_IA|ONEZONE_IA|INTELLIGENT_TIERING|DEEP_ARCHIVE|GLACIER_IR',
                ],
                // ...
            ],
        ],
        // ...
    ],
    'TransitionDefaultMinimumObjectSize' => 'varies_by_storage_class|all_storage_classes_128K',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get lifecycle configuration on a bucket

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

$result = $client->getBucketLifecycleConfiguration([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'Rules' => [
        [
            'ID' => 'Rule for TaxDocs/',
            'Prefix' => 'TaxDocs',
            'Status' => 'Enabled',
            'Transitions' => [
                [
                    'Days' => 365,
                    'StorageClass' => 'STANDARD_IA',
                ],
            ],
        ],
    ],
]

GetBucketLocation

$result = $client->getBucketLocation([/* ... */]);
$promise = $client->getBucketLocationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• GetObject

• CreateBucket

Parameter Syntax

$result = $client->getBucketLocation([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'LocationConstraint' => 'ap-northeast-1|ap-southeast-2|ap-southeast-1|cn-north-1|eu-central-1|eu-west-1|us-east-1|us-west-1|us-west-2|sa-east-1',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get bucket location

The following example returns bucket location.

$result = $client->getBucketLocation([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'LocationConstraint' => 'us-west-2',
]

GetBucketLogging

$result = $client->getBucketLogging([/* ... */]);
$promise = $client->getBucketLoggingAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• CreateBucket

• PutBucketLogging

Parameter Syntax

$result = $client->getBucketLogging([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'LoggingEnabled' => [
        'TargetBucket' => '<string>',
        'TargetGrants' => [
            [
                'Grantee' => [
                    'DisplayName' => '<string>',
                    'EmailAddress' => '<string>',
                    'ID' => '<string>',
                    'Type' => 'CanonicalUser|AmazonCustomerByEmail|Group',
                    'URI' => '<string>',
                ],
                'Permission' => 'FULL_CONTROL|READ|WRITE',
            ],
            // ...
        ],
        'TargetObjectKeyFormat' => [
            'PartitionedPrefix' => [
                'PartitionDateSource' => 'EventTime|DeliveryTime',
            ],
            'SimplePrefix' => [
            ],
        ],
        'TargetPrefix' => '<string>',
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketMetricsConfiguration

$result = $client->getBucketMetricsConfiguration([/* ... */]);
$promise = $client->getBucketMetricsConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutBucketMetricsConfiguration

• DeleteBucketMetricsConfiguration

• ListBucketMetricsConfigurations

• Monitoring Metrics with Amazon CloudWatch

Parameter Syntax

$result = $client->getBucketMetricsConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'MetricsConfiguration' => [
        'Filter' => [
            'AccessPointArn' => '<string>',
            'And' => [
                'AccessPointArn' => '<string>',
                'Prefix' => '<string>',
                'Tags' => [
                    [
                        'Key' => '<string>',
                        'Value' => '<string>',
                    ],
                    // ...
                ],
            ],
            'Prefix' => '<string>',
            'Tag' => [
                'Key' => '<string>',
                'Value' => '<string>',
            ],
        ],
        'Id' => '<string>',
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketNotification

$result = $client->getBucketNotification([/* ... */]);
$promise = $client->getBucketNotificationAsync([/* ... */]);

This operation is not supported for directory buckets.

No longer used, see GetBucketNotificationConfiguration.

Parameter Syntax

$result = $client->getBucketNotification([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'CloudFunctionConfiguration' => [
        'CloudFunction' => '<string>',
        'Event' => 's3:ReducedRedundancyLostObject|s3:ObjectCreated:*|s3:ObjectCreated:Put|s3:ObjectCreated:Post|s3:ObjectCreated:Copy|s3:ObjectCreated:CompleteMultipartUpload|s3:ObjectRemoved:*|s3:ObjectRemoved:Delete|s3:ObjectRemoved:DeleteMarkerCreated|s3:ObjectRestore:*|s3:ObjectRestore:Post|s3:ObjectRestore:Completed|s3:Replication:*|s3:Replication:OperationFailedReplication|s3:Replication:OperationNotTracked|s3:Replication:OperationMissedThreshold|s3:Replication:OperationReplicatedAfterThreshold|s3:ObjectRestore:Delete|s3:LifecycleTransition|s3:IntelligentTiering|s3:ObjectAcl:Put|s3:LifecycleExpiration:*|s3:LifecycleExpiration:Delete|s3:LifecycleExpiration:DeleteMarkerCreated|s3:ObjectTagging:*|s3:ObjectTagging:Put|s3:ObjectTagging:Delete',
        'Events' => ['<string>', ...],
        'Id' => '<string>',
        'InvocationRole' => '<string>',
    ],
    'QueueConfiguration' => [
        'Event' => 's3:ReducedRedundancyLostObject|s3:ObjectCreated:*|s3:ObjectCreated:Put|s3:ObjectCreated:Post|s3:ObjectCreated:Copy|s3:ObjectCreated:CompleteMultipartUpload|s3:ObjectRemoved:*|s3:ObjectRemoved:Delete|s3:ObjectRemoved:DeleteMarkerCreated|s3:ObjectRestore:*|s3:ObjectRestore:Post|s3:ObjectRestore:Completed|s3:Replication:*|s3:Replication:OperationFailedReplication|s3:Replication:OperationNotTracked|s3:Replication:OperationMissedThreshold|s3:Replication:OperationReplicatedAfterThreshold|s3:ObjectRestore:Delete|s3:LifecycleTransition|s3:IntelligentTiering|s3:ObjectAcl:Put|s3:LifecycleExpiration:*|s3:LifecycleExpiration:Delete|s3:LifecycleExpiration:DeleteMarkerCreated|s3:ObjectTagging:*|s3:ObjectTagging:Put|s3:ObjectTagging:Delete',
        'Events' => ['<string>', ...],
        'Id' => '<string>',
        'Queue' => '<string>',
    ],
    'TopicConfiguration' => [
        'Event' => 's3:ReducedRedundancyLostObject|s3:ObjectCreated:*|s3:ObjectCreated:Put|s3:ObjectCreated:Post|s3:ObjectCreated:Copy|s3:ObjectCreated:CompleteMultipartUpload|s3:ObjectRemoved:*|s3:ObjectRemoved:Delete|s3:ObjectRemoved:DeleteMarkerCreated|s3:ObjectRestore:*|s3:ObjectRestore:Post|s3:ObjectRestore:Completed|s3:Replication:*|s3:Replication:OperationFailedReplication|s3:Replication:OperationNotTracked|s3:Replication:OperationMissedThreshold|s3:Replication:OperationReplicatedAfterThreshold|s3:ObjectRestore:Delete|s3:LifecycleTransition|s3:IntelligentTiering|s3:ObjectAcl:Put|s3:LifecycleExpiration:*|s3:LifecycleExpiration:Delete|s3:LifecycleExpiration:DeleteMarkerCreated|s3:ObjectTagging:*|s3:ObjectTagging:Put|s3:ObjectTagging:Delete',
        'Events' => ['<string>', ...],
        'Id' => '<string>',
        'Topic' => '<string>',
    ],
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get notification configuration set on a bucket

The following example returns notification configuration set on a bucket.

$result = $client->getBucketNotification([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'QueueConfiguration' => [
        'Event' => 's3:ObjectCreated:Put',
        'Events' => [
            's3:ObjectCreated:Put',
        ],
        'Id' => 'MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx',
        'Queue' => 'arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue',
    ],
    'TopicConfiguration' => [
        'Event' => 's3:ObjectCreated:Copy',
        'Events' => [
            's3:ObjectCreated:Copy',
        ],
        'Id' => 'YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi',
        'Topic' => 'arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic',
    ],
]

Example 2: To get notification configuration set on a bucket

The following example returns notification configuration set on a bucket.

$result = $client->getBucketNotification([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'QueueConfiguration' => [
        'Event' => 's3:ObjectCreated:Put',
        'Events' => [
            's3:ObjectCreated:Put',
        ],
        'Id' => 'MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx',
        'Queue' => 'arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue',
    ],
    'TopicConfiguration' => [
        'Event' => 's3:ObjectCreated:Copy',
        'Events' => [
            's3:ObjectCreated:Copy',
        ],
        'Id' => 'YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi',
        'Topic' => 'arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic',
    ],
]

GetBucketNotificationConfiguration

$result = $client->getBucketNotificationConfiguration([/* ... */]);
$promise = $client->getBucketNotificationConfigurationAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• PutBucketNotification

Parameter Syntax

$result = $client->getBucketNotificationConfiguration([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'EventBridgeConfiguration' => [
    ],
    'LambdaFunctionConfigurations' => [
        [
            'Events' => ['<string>', ...],
            'Filter' => [
                'Key' => [
                    'FilterRules' => [
                        [
                            'Name' => 'prefix|suffix',
                            'Value' => '<string>',
                        ],
                        // ...
                    ],
                ],
            ],
            'Id' => '<string>',
            'LambdaFunctionArn' => '<string>',
        ],
        // ...
    ],
    'QueueConfigurations' => [
        [
            'Events' => ['<string>', ...],
            'Filter' => [
                'Key' => [
                    'FilterRules' => [
                        [
                            'Name' => 'prefix|suffix',
                            'Value' => '<string>',
                        ],
                        // ...
                    ],
                ],
            ],
            'Id' => '<string>',
            'QueueArn' => '<string>',
        ],
        // ...
    ],
    'TopicConfigurations' => [
        [
            'Events' => ['<string>', ...],
            'Filter' => [
                'Key' => [
                    'FilterRules' => [
                        [
                            'Name' => 'prefix|suffix',
                            'Value' => '<string>',
                        ],
                        // ...
                    ],
                ],
            ],
            'Id' => '<string>',
            'TopicArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketOwnershipControls

$result = $client->getBucketOwnershipControls([/* ... */]);
$promise = $client->getBucketOwnershipControlsAsync([/* ... */]);

This operation is not supported for directory buckets.

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

Parameter Syntax

$result = $client->getBucketOwnershipControls([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'OwnershipControls' => [
        'Rules' => [
            [
                'ObjectOwnership' => 'BucketOwnerPreferred|ObjectWriter|BucketOwnerEnforced',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

There are no errors described for this operation.

GetBucketPolicy

$result = $client->getBucketPolicy([/* ... */]);
$promise = $client->getBucketPolicyAsync([/* ... */]);

Returns the policy of a specified bucket.

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 a 403 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 a 405 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, and DeleteBucketPolicy 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:

• GetObject

Parameter Syntax

$result = $client->getBucketPolicy([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details

Result Syntax

[
    'Policy' => '<string>',
]

Result Details

Errors

There are no errors described for this operation.

Examples

Example 1: To get bucket policy

The following example returns bucket policy associated with a bucket.

$result = $client->getBucketPolicy([
    'Bucket' => 'examplebucket',
]);

Result syntax:

[
    'Policy' => '{"Version":"2008-10-17","Id":"LogPolicy","Statement":[{"Sid":"Enables the log delivery group to publish logs to your bucket ","Effect":"Allow","Principal":{"AWS":"111122223333"},"Action":["s3:GetBucketAcl","s3:GetObjectAcl","s3:PutObject"],"Resource":["arn:aws:s3:::policytest1/*","arn:aws:s3:::policytest1"]}]}',
]

GetBucketPolicyStatus

$result = $client->getBucketPolicyStatus([/* ... */]);
$promise = $client->getBucketPolicyStatusAsync([/* ... */]);

This operation is not supported for directory buckets.

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:

• Using Amazon S3 Block Public Access

• GetPublicAccessBlock

• PutPublicAccessBlock

• DeletePublicAccessBlock

Parameter Syntax

$result = $client->getBucketPolicyStatus([
    'Bucket' => '<string>', // REQUIRED
    'ExpectedBucketOwner' => '<string>',
]);

Parameter Details