PUT Bucket Notification Configuration

Enables notification on specified events for a bucket. For more information about event notifications, refer to 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. NotificationConfiguration is empty.

<NotificationConfiguration>

</NotificationConfiguration>

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

You can disable notifications by adding an empty NotificationConfiguration element.

Note

ARTESCA supports QueueConfiguration notification types only. There is no support for CloudFunctionConfiguration and TopicConfiguration notification types.

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.

GET Bucket Notification Configuration is related to PutBucketNotificationConfiguration.

Note

Bucket notification can be enabled for versioned, non-versioned, and versioning suspended buckets.

Supported Notification Event Types

Object Creation

  • s3:ObjectCreated:* (all object creation events)

  • s3:ObjectCreated:Put

  • s3:ObjectCreated:Copy

  • s3:ObjectCreated:CompleteMultipartUpload

Object Removal

  • s3:ObjectRemoved:* (all object removal events)

  • s3:ObjectRemoved:Delete

  • s3:ObjectRemoved:DeleteMarkerCreated

Object Tagging

  • s3:ObjectTagging:* (all object tagging events)

  • s3:ObjectTagging:Put

  • s3:ObjectTagging:Delete

Object ACL

  • s3:ObjectAcl:Put

Object Replication

  • s3:Replication:OperationFailedReplication

Object Restore

  • s3:ObjectRestore:* (all object restore events)

  • s3:ObjectRestore:Post

  • s3:ObjectRestore:Completed

  • s3:ObjectRestore:Delete

The s3:ObjectRestore:Post event type notifies you of object restoration initiation. The s3:ObjectRestore:Completed event type notifies you of restoration completion. The s3:ObjectRestore:Delete event type notifies you when the temporary copy of a restored object expires.

Command

Syntax

put-bucket-notification-configuration
 --bucket <value>
 --notification-configuration <value>

Options

The request uses the following URI parameters.

bucket

The name of the bucket.

Required

notification-configuration

Bucket notification configuration for the bucket.

Required

JSON Syntax:

{
  "QueueConfigurations": [
      {
        "QueueArn": "arn:partition:service:::resource",
        "Events": [
            "s3:ObjectCreated:*",
            "s3:ObjectCreated:Put",
            "s3:ObjectCreated:Copy",
            ...
        ],
        "Filter": {
            "Key": {
                "FilterRules": [
                    {
                      "Name": "prefix",
                      "Value": "string"
                    },
                    {
                      "Name": "suffix",
                      "Value": "string"
                    }
                    ...
                ]
            }
        }
      }
    ...
  ],
}

Construct QueueARN as arn:partition:service:region:account-id:resource where:

  • partition is hardcoded as scality.

  • service is harcoded as bucketnotif.

  • region is ignored.

  • account-id is ignored.

  • resource is the name of the destination created following the steps in Add Bucket Notification Destination.

For example: arn:scality:bucketnotif:::destinationResourceName

The Filter key is optional and permits specifying object key name filtering rules.

FilterRules is a list of containers for the key-value pair that defines the criteria for the filter rule. The name of each rule specifies whether to filter on the suffix or prefix of the key name.

Notification Format

The following is an example of a notification you get when putting a new object into a versioned bucket.

{
  "Records": [{
      "eventVersion": "1.0",
      "eventSource": "scality:s3",
      "awsRegion": "us-east-1",
      "eventTime": "2023-01-02T15:25:09.629Z",
      "eventName": "s3:ObjectCreated:Put",
      "userIdentity": {
          "principalId": null
      },
      "requestParameters": {
          "sourceIPAddress": null
      },
      "responseElements": {
          "x-amz-request-id": null,
          "x-amz-id-2": null
      },
      "s3": {
          "s3SchemaVersion": "1.0",
          "configurationId": "ZTExY2FmMGEtOWUyMy00ODY1LTlhOWE",
          "bucket": {
              "name": "notification-bucket",
              "ownerIdentity": {
                  "principalId": null
              },
              "arn": null
          },
          "object": {
              "key": "LICENSE",
              "size": "10753",
              "eTag": null,
              "versionId": "aJr8WJ0p2tTV00000000001I4j3QKsvf",
              "sequencer": null
          }
      }
  }]
}

Note

The following fields are required for AWS conformity, but are not supported by the S3 Connector backend. These fields are returned with a null value.

  • userIdentity.principalId

  • requestParameters.sourceIPAddress

  • responseElement.x-amz-request-id

  • responseElement.x-amz-id-2

  • s3.bucket.ownerIdentity.principalId

  • s3.bucket.arn

  • s3.object.eTag

  • s3.object.sequencer

Example

The following applies a notification configuration to a bucket named my-bucket.

aws s3api put-bucket-notification-configuration
  --bucket my-bucket
  --notification-configuration file://notification.json

The file notification.json is a JSON document in the current folder that specifies a queue and event type.

The following notification configuration contains a queue configuration identifying an s3:ObjectCreated:Put event type and a queue. The events are published whenever an object with an images/ prefix and a .jpg suffix is PUT into a bucket.

{
  "QueueConfigurations": [
    {
        "QueueArn": "arn:scality:bucketnotif:::destinationResourceName",
        "Events": [
            "s3:ObjectCreated:Put"
        ],
        "Filter": {
            "Key": {
                "FilterRules": [
                    {
                        "Name": "Prefix",
                        "Value": "images/",
                    },
                    {
                        "Name": "Suffix",
                        "Value": ".jpg",
                    }
                ]
            }
        }
    }
  ]
}