Feature description

This API sets event notification rules for a storage bucket (Bucket). Through event notifications, you can receive alerts when resources within the bucket change.

Notes

This API can only be used after the event notification feature is optimized and launched. For details, see the Object Storage Event Notification Feature Interface Change Description.

To call this API, you must be the bucket owner or have the PutBucketNotification permission authorized for the current bucket.

HNS buckets do not support the PutBucketNotificationV2 interface.

Request syntax

Request parameters and headers

The public response headers returned by this request. See public parameters.

Name	Location	Parameter Type	Required	Sample value	Note
notification_v2	Query	String	Yes	-	Represents a special identifier for the PutBucketNotificationV2 request.

Request elements

Name	Type	Required	Sample value	Note
Rules	Array	No	-	Event notification rule information.
Events	Array	Yes	["tos:ObjectCreated:", "tos:ObjectRemoved:"]	Set the event types to notify. For a list of types supported by TOS, see Supported event types. Parent node: Rules
Filter	Container	No	-	Set filter rules. Parent node: Rules
TOSKey	Container	No	-	Currently supports setting FilterRule, which is the object's filter information. Parent node: Filter
FilterRules	Array	No	[ {"Name": "prefix", "Value": "test_" }, { "Name": "suffix", "Value": ".jpg" } ]	Set the filtering rules that the target object must match. Supports setting prefix and suffix for filtering event objects by prefix and suffix rules respectively. If both prefix and suffix rules are set, events must meet both to trigger a notification. If neither a prefix nor a suffix is set, all objects in the bucket will be matched. Parent node: TOSKey
Name	String	No	prefix	Set the conditions to match. The options are as follows: prefix: prefix. suffix: suffix. Parent node: FilterRules
Value	String	Not supported	test_	Set the prefix and suffix information to match. Parent node: FilterRules
RuleId	String	No	TestNotification	Specify the event notification rule name, naming rules are as follows: Event names must be unique within the bucket. Length must not exceed 255 characters. If not set, TOS will automatically generate the rule name. Parent node: Rules
Destination	Container	Yes	-	Set event notification push targets, including at least one target and support up to 5 different targets. Parent node: Rules
VeFaaS	Array	No	[ {"FunctionId": "l2u0****"} ]	Set the event delivery target to a function service, allowing multiple different function services to be set. Parent node: Destination
FunctionId	String	Yes tip When the event delivery target is a function service, FunctionId is a required parameter.	l2u0****	Function ID for event delivery. You can log in to the Function Service Console and view the Function ID on the function Configuration page. Parent node: VeFaaS
Kafka	Array	Yes tip The parameter Kafka is required only when the event delivery target is a Kafka message queue.	"Kafka":[ { "Role":"trn:iam::214748**:role/aaa", "InstanceId":"kafka-cnoeb1pq83rs**", "Topic":"test-aaa", "User":"bbbbb" } ]	Set the event delivery target to Kafka message queue. Multiple different Kafka instances can be configured. Parent node: Destination
Role	String	Yes	trn:iam::214748****:role/aaa	Role TRN. This role must be bound to the system preset policy KafkaAccessForTOS to authorize TOS to access the Kafka service. Parent node: Kafka tip You need to create a role first, bind the system preset policy KafkaAccessForTOS to the role, and then obtain the role TRN. For detailed operations, see CreateRole and AttachRolePolicy.
InstanceId	String	Yes	kafka-cnoeb1pq83rs****	Kafka instance ID. Parent node: Kafka
Topic	String	Yes	test-aaa	Name of the Kafka topic. Parent node: Kafka
User	String	Yes	bbb	Kafka user name. Parent node: Kafka
Version	String	No	1698031811529301000	The version number of the event notification rule. Use the GetBucketNotificationV2 API to obtain this value. Configuring the Version parameter ensures the atomicity of event notification rule settings. It is recommended to configure the Version parameter when modifying event notification rules through the PutBucketNotificationV2 API. At the same level as Rules

Response headers

The public response headers returned by this request. See public parameters.

Response body elements

There are no message elements in the response for a successful request.

Sample request

Set event notifications to deliver to the function service

PUT /?notification_v2= HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 13:53:55 +0000
Authorization: authorization string
{
"Rules":[
{
"Events":[
"tos:ObjectCreated:*",
"tos:ObjectRemoved:*"
],
"Filter":{
"TOSKey":{
"FilterRules":[
{
"Name":"prefix",
"Value":"test_"
},
{
"Name":"suffix",
"Value":".jpg"
}
]
}
},
"RuleId":"TestNotification",
"Destination":{
"VeFaaS":[
{
"FunctionId":"l2u0****"
}
]
}
}
]
}

Set event notifications to deliver to the Kafka version of the message queue

PUT /?notification_v2= HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Wed, 13 Aug 2025 03:36:58 +0000
Authorization: authorization string
{
"Rules":[
{
"Events":[
"tos:ObjectCreated:*",
"tos:ObjectRemoved:*"
],
"Filter":{
"TOSKey":{
"FilterRules":[
{
"Name":"prefix",
"Value":"test_"
},
{
"Name":"suffix",
"Value":".jpg"
}
]
}
},
"RuleId":"event",
"Destination":{
"Kafka":[
{
"Role":"trn:iam::214748****:role/aaa",
"InstanceId":"kafka-cnoeb1pq83rs****",
"Topic":"test-aaa",
"User":"bbbbb"
}
]
}
}
]
}

Sample response

Torch Object Storage