功能描述

此接口用于为存储桶（Bucket）设置事件通知规则，支持将事件推送至多个目标，详细说明，请参见对象存储事件通知功能接口变更说明。通过事件通知功能，您可以在存储桶内的资源发生变更时，获得事件通知。

注意事项

调用此接口您必须为桶所有者，或被授权当前桶的 PutBucketNotification 权限。

分层桶暂不支持 PutBucketNotificationV2 接口。

请求消息样式

PUT /?notification_v2 HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: GMT Date​
Authorization: authorization string​
{​
    "Rules":[​
        {​
            "Events":[​
                "tos:ObjectCreated:*",​
                "tos:ObjectRemoved:*"​
            ],​
            "Filter":{​
                "TOSKey":{​
                    "FilterRules":[​
                        {​
                            "Name":"prefix",​
                            "Value":"test_"​
                        },​
                        {​
                            "Name":"suffix",​
                            "Value":".jpg"​
                        }​
                    ]​
                }​
            },​
            "RuleId":"string",​
            "Destination":{​
                "VeFaaS":[​
                    {​
                        "FunctionId":"function_id"​
                    }​
                ]​
            }​
        }​
    ]​
}​

请求参数与消息头

该请求返回的公共响应消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
notification_v2	Query	String	是	-	代表 PutBucketNotificationV2 请求的特殊标识。

请求元素

名称	参数类型	是否必选	示例值	说明
Rules	Array	否	-	事件通知规则信息。
Events	Array	是	["tos:ObjectCreated:", "tos:ObjectRemoved:"]	设置需要通知的事件类型。TOS 支持的事件列表，请参见事件列表。父节点：Rules
Filter	Container	否	-	设置过滤规则。父节点：Rules
TOSKey	Container	否	-	当前支持设置 FilterRule，即对象的过滤信息。父节点：Filter
FilterRules	Array	否	[ {"Name": "prefix", "Value": "test_" }, { "Name": "suffix", "Value": ".jpg" } ]	设置对象需要匹配的过滤规则。支持设置 prefix 和 suffix，即分别根据前缀和后缀规则对事件对象过滤。如果同时设置了前缀与后缀规则，则事件需要同时满足二者，才会被通知。如果前后缀均未设置，则会匹配存储桶内所有对象。父节点：TOSKey
Name	String	否	prefix	设置需要匹配的条件。取值说明如下: prefix：前缀。 suffix：后缀。父节点：FilterRules
Value	String	否	test_	设置需要匹配的前后缀信息。父节点：FilterRules
RuleId	String	否	TestNotification	设置事件通知规则名称，命名规范如下：同一存储桶下创建的事件名称不能重复。长度不超过 255 个字符。如果未设置，则 TOS 将自动生成规则名称。父节点：Rules
Destination	Container	是	-	设置事件通知推送目标，至少包含一个目标，最多支持5个不同目标。父节点：Rules
VeFaaS	Array	否	[ {"FunctionId": "l2u0****"} ]	设置事件投递的目标为函数服务，可以设置多个不同的函数服务。父节点：Destination
FunctionId	String	是说明当事件投递的目标是函数服务时，FunctionId 才为必选参数。	l2u0****	事件投递的函数 ID。您可以登录函数服务控制台，在函数配置页面查看函数 ID。父节点：VeFaaS
Kafka	Array	是说明当事件投递的目标是消息队列 Kafka时，Kafka才为必选参数。	"Kafka":[ { "Role":"trn:iam::214748**:role/aaa", "InstanceId":"kafka-cnoeb1pq83rs**", "Topic":"test-aaa", "User":"bbbbb" } ]	设置事件投递的目标为消息队列 Kafka 版，可以设置多个不同的 Kafka 实例。父节点：Destination
Role	String	是	trn:iam::214748****:role/aaa	角色 TRN，该角色必须绑定系统预设策略 KafkaAccessForTOS ，用于授权 TOS 访问 Kafka 服务。父节点：Kafka 说明您需要先创建角色，并为角色绑定系统预设策略 KafkaAccessForTOS，然后获取角色 TRN，具体操作，请参见 CreateRole 和 AttachRolePolicy。
InstanceId	String	是	kafka-cnoeb1pq83rs****	Kafka 实例 ID。父节点：Kafka
Topic	String	是	test-aaa	Kafka Topic 的名称。父节点：Kafka
User	String	是	bbb	Kafka 用户名称。父节点：Kafka
Version	String	否	1698031811529301000	事件通知规则的版本号，请求 GetBucketNotificationV2 接口可获取该值。配置 Version 参数可保证事件通知规则设置的原子性，建议通过 PutBucketNotificationV2 接口修改事件通知规则时，配置 Version 参数。与 Rules 同级

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

对于正确请求，响应中无消息元素。

请求示例

设置事件通知投递至函数服务

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****"
}
]
}
}
]
}

设置事件通知投递至消息队列 Kafka 版

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"
}
]
}
}
]
}

响应示例

HTTP/1.1 200 OK​
Content-Length: 0​
Date: Wed, 17 May 2023 12:18:08 GMT​
Server: TosServer​
X-Tos-Id-2: c25e0164c600b8df6464c600-ac1bb4fd-1pzG6a-PBN-cgb-tos-front-2​
X-Tos-Request-Id: c25e0164c600b8df6464c600-ac1bb4fd-1pzG6a-PBN-cgb-tos-front-2​
X-Tos-Server-Time: 165​