Skip to content

S3  >  Operations  >  put_bucket_notification_configuration

put_bucket_notification_configuration

Operation

put_bucket_notification_configuration async

put_bucket_notification_configuration(request: PutBucketNotificationConfigurationInput | PutBucketNotificationConfigurationInputDict, /, *, plugins: list[Plugin] | None = None) -> PutBucketNotificationConfigurationOutput
put_bucket_notification_configuration(*, plugins: list[Plugin] | None = None, **kwargs: Unpack[PutBucketNotificationConfigurationInputDict]) -> PutBucketNotificationConfigurationOutput
Note

This operation is not supported for directory buckets.

Enables notifications of specified events for a bucket. For more information about event notifications, see Configuring Event Notifications.

Using this API, you can replace an existing notification configuration. The configuration is an XML file that defines the event types that you want Amazon S3 to publish and the destination where you want Amazon S3 to publish an event notification when it detects an event of the specified type.

By default, your bucket has no event notifications configured. That is, the notification configuration will be an empty NotificationConfiguration.

<notificationconfiguration>

</notificationconfiguration>

This action replaces the existing notification configuration with the configuration you include in the request body.

After Amazon S3 receives this request, it first verifies that any Amazon Simple Notification Service (Amazon SNS) or Amazon Simple Queue Service (Amazon SQS) destination exists, and that the bucket owner has permission to publish to it by sending a test notification. In the case of Lambda destinations, Amazon S3 verifies that the Lambda function permissions grant Amazon S3 permission to invoke the function from the Amazon S3 bucket. For more information, see Configuring Notifications for Amazon S3 Events.

You can disable notifications by adding the empty NotificationConfiguration element.

For more information about the number of event notification configurations that you can create per bucket, see Amazon S3 service quotas in Amazon Web Services General Reference.

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

Note

The PUT notification is an atomic operation. For example, suppose your notification configuration includes SNS topic, SQS queue, and Lambda function configurations. When you send a PUT request with this configuration, Amazon S3 sends test messages to your SNS topic. If the message fails, the entire PUT action will fail, and Amazon S3 will not add the configuration to your bucket.

If the configuration in the request body includes only one TopicConfiguration specifying only the s3:ReducedRedundancyLostObject event type, the response will also include the x-amz-sns-test-message-id header containing the message ID of the test notification sent to the topic.

The following action is related to PutBucketNotificationConfiguration:

Warning

You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.

Parameters:

Name Type Description Default
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None

Returns:

Type Description
PutBucketNotificationConfigurationOutput

An instance of PutBucketNotificationConfigurationOutput.

Input

Pass the input fields as keyword arguments, or pass a model or dictionary as the first positional argument. Pass plugins separately as a keyword argument.

Model

PutBucketNotificationConfigurationInput dataclass

Bases: _SerdeShape

Dataclass for PutBucketNotificationConfigurationInput structure.

Attributes
bucket class-attribute instance-attribute
bucket: str | None = ...

The name of the bucket.

expected_bucket_owner class-attribute instance-attribute
expected_bucket_owner: str | None = ...

The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code 403 Forbidden (access denied).

notification_configuration class-attribute instance-attribute
notification_configuration: NotificationConfiguration | None = ...

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

skip_destination_validation class-attribute instance-attribute
skip_destination_validation: bool | None = ...

Skips validation of Amazon SQS, Amazon SNS, and Lambda destinations. True or false value.

Dictionaries

PutBucketNotificationConfigurationInputDict

Bases: TypedDict

Dictionary form of PutBucketNotificationConfigurationInput.

Attributes
bucket instance-attribute
bucket: Required[str]

The name of the bucket.

expected_bucket_owner instance-attribute
expected_bucket_owner: str | None

The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code 403 Forbidden (access denied).

notification_configuration instance-attribute

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

skip_destination_validation instance-attribute
skip_destination_validation: bool | None

Skips validation of Amazon SQS, Amazon SNS, and Lambda destinations. True or false value.

Output

PutBucketNotificationConfigurationOutput dataclass

Bases: _SerdeShape

Dataclass for PutBucketNotificationConfigurationOutput structure.

Attributes

response_metadata class-attribute instance-attribute
response_metadata: ResponseMetadata = ...

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.