Help Center> Object Storage Service> API Reference> APIs> Advanced Bucket Settings> Configuring Event Notification for a Bucket
View PDF

Configuring Event Notification for a Bucket

Functions

This operation notifies users of their operations on buckets, allowing users know events happened on buckets in a timely manner.

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

1
2
 
<NotificationConfiguration>
</NotificationConfiguration>

OBS supports event notifications through Simple notification service (SMN) and the workflow of FunctionGraph. Taking SMN for example, after receiving a request for configuring event notification, 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.

To perform this operation, you must have the PutBucketNotification permission. By default, the permission is granted to the bucket owner only. However, it can be granted to other users by configuring the bucket policy.

  1. For details about how to grant topics to OBS, see Configuring Topic Policies.
  2. For details about the operations on FunctionGraph, see Using an OBS Trigger.
  3. An SMN request body cannot exceed 100 KB in size.
  4. A request body can contain a maximum of 100 TopicConfig elements.
  5. FunctionStage is a function in FunctionGraph.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
PUT /?notification HTTP/1.1 
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Date: date
Authorization: authorization string

<NotificationConfiguration>  
    <TopicConfiguration>  
        <Id>ConfigurationId</Id>  
        <Filter>  
            <Object>  
                <FilterRule>  
                    <Name>prefix</Name>  
                    <Value>prefix-value</Value>  
                </FilterRule>  
                <FilterRule>  
                    <Name>suffix</Name>  
                    <Value>suffix-value</Value>  
                </FilterRule>  
           </Object>  
        </Filter>  
        <Topic>TopicARN</Topic>  
        <Event>event-type</Event>  
        <Event>event-type</Event>  
        ...  
    </TopicConfiguration> 
    ... 
    <FunctionStageConfiguration> 
        <Id>ConfigurationId</Id> 
        <Filter> 
        ... 
        </Filter> 
        <FunctionStage>function-stage-arn</FunctionStage> 
        <Event>event-type</Event> 
        ... 
    </FunctionStageConfiguration> 
</NotificationConfiguration>

Request Parameters

This request contains no parameter.

Request Headers

This request uses common headers. For details, see Table 3.

Request Elements

This request contains elements to specify the notification configuration for the bucket in XML format. For details about the configuration elements, see Table 1.

Table 1 Request elements for notification function configuration

Element

Description

Mandatory

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

Yes

TopicConfiguration

Element for configuring the event notification topic.

Type: element

Ancestor: NotificationConfiguration

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

No

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

FunctionStageConfiguration

Element for configuring FunctionStage.

Type: element

Ancestor: NotificationConfiguration

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

No

FunctionStage

URN of a function in FunctionStage. When OBS detects a specific event in the bucket, OBS sends a message to FunctionStage to call this function.

Type: string

Ancestor: FunctionStageConfiguration

Required if FunctionStageConfiguration 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 or FunctionStageConfiguration

No

Filter

Element used to store rules of filtering object names.

Type: element

Ancestor:

TopicConfiguration or FunctionStageConfiguration

Children: Object

No

Object

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

No

FilterRule

Element that defines key-value pairs of the filtering rule

Type: element

Ancestor: Object

Children: Name, Value

No

Name

Prefix or suffix of object names for filtering

Type: string

Ancestor: FilterRule

Value options: prefix, suffix

No

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

No

Event

Type of events that need to be notified

NOTE:

Multiple event types can be added in one TopicConfiguration or FunctionStageConfiguration item.

Type: string

Value options:

The following values can be used to upload an object:

  • ObjectCreated:Put
  • ObjectCreated:Post
  • ObjectCreated:Copy
  • ObjectCreated:CompleteMultipartUpload

Or use wildcard characters to support all upload operations:

  • ObjectCreated:*

The following values can be used to delete an object:

  • ObjectRemoved:Delete
  • ObjectRemoved:DeleteMarkerCreated

Or use wildcard characters to support all delete operations:

  • ObjectRemoved:*

Ancestor:

TopicConfiguration or FunctionStageConfiguration

Required if TopicConfiguration or FunctionStageConfiguration is added

Response Syntax

1
2
3
4
 
HTTP/1.1 status_code
Date: date
Content-Length: length
Content-Type: type

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response involves no elements.

Error Responses

When this operation is being called, the system checks whether the NotificationConfiguration element is valid and whether the configuration is valid. The following table lists the common errors and possible causes of this operation.

Table 2 Error codes and possible causes

Error Code

Description

HTTP Status Code

InvalidArgument

Possible causes of this error are:

  • The specified event is not supported.
  • The specified URN does not exist or is incorrect.
  • The specified region in the URN is different as 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 with the PutBucketNotification permission.

403 Forbidden

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
PUT /?notification HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 03:15:45 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:uRTt8YTkAqJCUfWfYkveEcIGAC0=
Content-Length: 538

<NotificationConfiguration> 
  <TopicConfiguration> 
    <Id>ConfigurationId</Id>  
    <Filter>
      <Object>
        <FilterRule>
          <Name>prefix</Name>
          <Value>object</Value>
        </FilterRule>
        <FilterRule>
          <Name>suffix</Name>
          <Value>txt</Value>
        </FilterRule>
      </Object> 
    </Filter>  
    <Topic>urn:smn:cn-east-3:4b29a3cb5bd64581bda5714566814bb7:tet555</Topic>  
    <Event>ObjectCreated:Put</Event> 
  </TopicConfiguration>
</NotificationConfiguration>

Sample Response

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 9046000001643C8E80C19FAC4D8068E3
x-obs-id-2: 32AAAQAAEAABSAAkgAIAABAAAQAAEAABCTFAxJPTib3GkcQ7nVVs4C8Z6NNcfVDu
Date: WED, 01 Jul 2015 03:15:46 GMT
Content-Length: 0
Parent topic: Advanced Bucket Settings