Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

PUT Bucket notification

Description

This implementation of the PUT operation uses the notification subresource to enable notifications of specified events for a bucket. Currently, the s3:ReducedRedundancyLostObject event is the only event supported for notifications. The s3:ReducedRedundancyLostObject event is triggered when Amazon S3 detects that it has lost all replicas of an object and can no longer service requests for that object.

If the bucket owner and Amazon SNS topic owner are the same, the bucket owner has permission to publish notifications to the topic by default. Otherwise, the owner of the topic must create a policy to enable the bucket owner to publish to the topic. For more information about creating this policy, go to Example Cases for Amazon SNS Access Control.

By default, only the bucket owner can configure notifications on a bucket. However, bucket owners can use a bucket policy to grant permission to other users to set this configuration with s3:PutBucketNotification permission.

After you call the PUT operation to configure notifications on a bucket, Amazon S3 publishes a test notification to ensure that the topic exists and that the bucket owner has permission to publish to the specified topic. If the notification is successfully published to the SNS topic, the PUT operation updates the bucket configuration and returns the 200 OK response with a x-amz-sns-test-message-id header containing the message ID of the test notification sent to topic.

To turn off notifications on a bucket, you specify an empty NotificationConfiguration element in your request: <NotificationConfiguration />

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.

Requests

Syntax

PUT /?notification HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4))
<NotificationConfiguration>
   <TopicConfiguration>
       <Topic>TopicARN</Topic>
       <Event>Event</Event>
   </TopicConfiguration>
</NotificationConfiguration>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.

Request Elements

Name Description Required
NotificationConfiguration

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

Type: Container

Children: TopicConfiguration

Ancestry: None

Yes
TopicConfiguration

Container for specifying the topic configuration for the notification. Currently, only one topic can be configured for notifications.

Type: Container

Children: Topic, Event

Ancestry: NotificationConfiguration

No
Topic

Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the bucket.

Type: String

Ancestry: TopicConfiguration

No
Event

Bucket event for which to send notifications. Currently, s3:ReducedRedundancyLostObject is the only event supported for notifications.

Type: String

Valid Values: s3:ReducedRedundancyLostObject

Ancestry: TopicConfiguration

No

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed NotificationConfiguration element and verifies whether the proposed configuration is valid when you call the PUT operation. The following table lists the errors and possible causes.

HTTP Error Code Cause
HTTP 400 Bad RequestInvalidArgument

The following conditions can cause this error:

  • The specified event is not supported for notifications.

  • The specified topic ARN does not exist or is not well-formed. Verify the topic ARN.

  • The specified topic is in a different region than the bucket. You must use a topic that resides in the same Region as the bucket.

  • The bucket owner does not have Publish permission on the specified topic.

HTTP 403 ForbiddenAccessDenied

You are not the owner of the specified bucket or you do not have the s3:PutBucketNotification bucket permission to set the notification configuration on the bucket.

For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Requests

This request enables notification on bucket quotes.s3.amazonaws.com for the event s3:ReducedRedundancyLostObject with notifications published to the topic arn:aws:sns:us-east-1:123456789012:myTopic.

PUT ?notification HTTP/1.1 
Host: quotes.s3.amazonaws.com
Date: Wed, 02 June 2010 12:00:00 GMT
Authorization: authorization string
<NotificationConfiguration> 
   <TopicConfiguration>
       <Topic>arn:aws:sns:us-east-1:123456789012:myTopic</Topic>
       <Event>s3:ReducedRedundancyLostObject</Event>
   </TopicConfiguration>
</NotificationConfiguration>

This request turns off notification on the quotes.s3.amazonaws.com bucket.

PUT ?notification HTTP/1.1 
Host: quotes.s3.amazonaws.com
Date: Wed, 02 June 2010 12:01:00 GMT
Authorization: authorization string
<NotificationConfiguration /> 
			

Sample Responses

In this response, you are notified that the notification configuration was successful. It also returns the ID of the test message Amazon S3 sent to the topic.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
x-amz-sns-test-message-id: feeb1dff-cc96-449d-964c-f8a1890fd007
Date: Wed, 02 June 2010 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

This response returns that the notification was turned off successfully. Note that Amazon S3 doesn't send a test notification when notifications are turned off.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A890524860101
Date: Wed, 02 June 2010 12:01:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3