PUT Bucket Notification

You can perform this operation to notify users of their operations on buckets, letting users know events on buckets in a timely manner. For details about how to configure Simple Message Notification (SMN) and interconnect systems, see Managing Event Notification in the Object Storage Service Developer Guide.

By default, the notification function of your bucket is not enabled. Namely, the NotificationConfiguration element is null. If you want to disable the function, set the NotificationConfiguration element to null.

<NotificationConfiguration>
</NotificationConfiguration>

OBS supports SMN, FunctionStage, and FunctionGraph for bucket notification. For example, with SMN, after receiving a notification request, OBS verifies whether the specified SMN Topic exists and whether the topic is authorized to OBS. If the topic exists and is authorized to OBS, OBS sends a test notification to the topic subscriber.

The s3:PutBucketNotification permission is required to configure the notification function. By default, the permission is granted to the bucket owner only. However, it can be granted to other users by configuring the bucket policy.

NOTE:
  1. For details about how to authorize a topic policy to OBS, see Topic Policy Modification.
  2. For details about how to authorize FunctionStage to OBS, see the FunctionStage user guide.
  3. For details about how to authorize FunctionGraph to OBS, see the FunctionGraph user guide.

Request Syntax

PUT /?notification HTTP/1.1
Host: bucketname.obs.cn-north-1.myhwclouds.com
Date: date
Authorization: authorization string

<NotificationConfiguration> 
    <TopicConfiguration> 
        <Id>ConfigurationId</Id> 
        <Filter> 
            <S3Key> 
                <FilterRule> 
                    <Name>prefix</Name> 
                    <Value>prefix-value</Value> 
                </FilterRule> 
                <FilterRule> 
                    <Name>suffix</Name> 
                    <Value>suffix-value</Value> 
                </FilterRule> 
           </S3Key> 
        </Filter> 
        <Topic>TopicARN</Topic> 
        <Event>event-type</Event> 
        <Event>event-type</Event> 
        ... 
    </TopicConfiguration>
    <CloudFunctionConfiguration>
        <Id>ConfigurationId</Id>
        <Filter>
        ...
        </Filter>
        <CloudFunction>cloud-function-arn</CloudFunction>
        <Event>event-type</Event>
        ...
        </CloudFunctionConfiguration>
        ...
    <FunctionGraphConfiguration>
        <Id>ConfigurationId</Id>
        <Filter>
        ...
        </Filter>
        <FunctionGraph>function-graph-arn</FunctionGraph>
        <Event>event-type</Event>
        ...
    </FunctionGraphConfiguration>
    ...
</NotificationConfiguration>

Request Parameters

This request contains no parameter.

Request Headers

This request uses common headers. For details, see Common Message Headers.

Request Elements

This request contains elements to specify the notification configuration for the bucket in XML format. Table 1 lists the request elements.

Table 1 Request elements of notification function configuration

Element

Description

Required or Optional

NotificationConfiguration

Root element for configuring the event notification function of a bucket. If the sub element is null, the function is disabled.

Type: element

Ancestor: none

Children: no or multiple TopicConfigurations

Required

TopicConfiguration

Element for configuring the event notification topic.

Type: element

Ancestor: NotificationConfiguration

Children: Id, Filter, Topic, Event, or Events

Optional

Topic

URN of the event notification topic. When OBS detects a specific event in the bucket, it publishes a notification message to the topic. The topic value can be found in SMN Topic.

Type: string

Ancestor: TopicConfiguration

Required if TopicConfiguration is added

CloudFunctionConfiguration

Element of configuring FunctionStage.

Type: element

Ancestor: NotificationConfiguration

Children: Id, Filter, Topic, Event, or Events

Optional

CloudFunction

URN of FunctionStage. When OBS detects a specific event in the bucket, it sends a message to FunctionStage and calls FunctionStage.

Type: string

Ancestor: CloudFunctionConfiguration

Required if CloudFunctionConfiguration is added

FunctionGraphConfiguration

Element of configuring FunctionGraph.

Type: element

Ancestor: NotificationConfiguration

Children: Id, Filter, Topic, Event, or Events

Optional

FunctionGraph

URN of FunctionGraph. When OBS detects a specific event in the bucket, it sends a message to FunctionGraph and calls FunctionGraph.

Type: string

Ancestor: FunctionGraphConfiguration

Required if FunctionGraphConfiguration is added

Id

Unique ID of each event notification. If the user does not specify an ID, the system assigns an ID automatically.

Type: string

Ancestor: TopicConfiguration, CloudFunctionConfiguration, or FunctionGraphConfiguration

Optional

Filter

Element of S3Key used to store rules of filtering object names

Type: element

Ancestor: TopicConfiguration, CloudFunctionConfiguration, or FunctionGraphConfiguration

Children: S3Key

Optional

S3Key

Element that defines the filtering rule. The rule filters objects based on the prefixes and suffixes of object names.

Type: element

Ancestor: Filter

Children: one or more FilterRules

Optional

FilterRule

Element that defines key-value pairs of the filtering rule.

Type: element

Ancestor: S3Key

Children: Name, Value

Optional

Name

Prefix or suffix of object names for filtering.

Type: string

Ancestor: FilterRule

Valid value: prefix or suffix

Optional

Value

Key word of object names. Based on the prefix or suffix defined by Name, enter the key word for filtering objects. A longer string of characters delivers a more accurate filtering result. A maximum of 1024 characters are supported.

Type: string

Ancestor: FilterRule

Optional

Event

Type of events that need to be notified.

NOTE:

Multiple event types can be added in one TopicConfiguration, CloudFunctionConfiguration, or FunctionGraphConfiguration configuration item.

Type: string

Valid value: See the content about event types in the Object Storage Service Developer Guide.

Ancestor: TopicConfiguration, CloudFunctionConfiguration, or FunctionGraphConfiguration

Required if TopicConfiguration, CloudFunctionConfiguration, or FunctionGraphConfiguration is added

Response Syntax

HTTP/1.1 status_code
Date: date
Content-Length: length
Content-Type: type

Response Headers

This response uses common headers. For details, see Common Response Headers.

Response Elements

This response contains no element.

Error Responses

When a user invokes this interface, the system checks whether the NotificationConfiguration element and the configuration are valid. The following table lists common errors and possible causes.

Table 2 Error codes and possible causes

Error Code

Possible Cause

HTTP Status Code

InvalidArgument

Possible causes of this error are:

  • Unsupported events were specified.
  • The specified URN does not exist or is incorrect.
  • The specified region in the URN is different from the region where the bucket resides.
  • The specified filtering rules overlap.

400 Bad Request

AccessDenied

The operator is not the bucket owner and not granted the s3:PutBucketNotification permission.

403 Forbidden

Registration