## 功能描述此接口用于为存储桶（Bucket）设置事件通知规则，支持将事件推送至多个目标，详细说明，请参见[对象存储事件通知功能接口变更说明](https://arcosite.bytedance.net/sites/1699502194068/654cc15af4ae8802eada576c/editor/6576fa36ccd5a102f5c32524/?docLang=zh)。通过事件通知功能，您可以在存储桶内的资源发生变更时，获得事件通知。 ## 注意事项 * 调用此接口您必须为桶所有者，或被授权当前桶的 PutBucketNotification 权限。 * [分层桶](/docs/6349/1282866)暂不支持 PutBucketNotificationV2 接口。 ## 请求消息样式 ```JSON 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" } ] } } ] } ``` ## 请求参数与消息头该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 |**名称** |**位置** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---|---| |notification_v2 |Query |String |是 |\- |代表 PutBucketNotificationV2 请求的特殊标识。 | ## 请求**元素** |**名称** |**参数类型** |**是否必选** |**示例值** |说明 | |---|---|---|---|---| |Rules |Array |否 |\- |事件通知规则信息。 | |Events |Array |是 |["tos:ObjectCreated: *", "tos:ObjectRemoved:* "] |设置需要通知的事件类型。TOS 支持的事件列表，请参见[事件列表](/docs/6349/128981#.5pSv5oyB55qE5LqL5Lu257G75Z6L)。|\ | | | | |父节点：Rules | |Filter |Container |否 |\- |设置过滤规则。|\ | | | | |父节点：Rules | |TOSKey |Container |否 |\- |当前支持设置 FilterRule，即对象的过滤信息。|\ | | | | |父节点：Filter | |FilterRules |Array |否 |[|设置对象需要匹配的过滤规则。支持设置 `prefix` 和 `suffix`，即分别根据前缀和后缀规则对事件对象过滤。|\ | | | |{"Name": "prefix",||\ | | | |"Value": "test_"|* 如果同时设置了前缀与后缀规则，则事件需要同时满足二者，才会被通知。|\ | | | |},|* 如果前后缀均未设置，则会匹配存储桶内所有对象。|\ | | | |{||\ | | | |"Name": "suffix",|父节点：TOSKey |\ | | | |"Value": ".jpg" }| |\ | | | |] | | |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 |是|l2u0\*\*\*\* |事件投递的函数 ID。您可以登录[函数服务控制台](https://console.volcengine.com/vefaas)，在函数**配置**页面查看**函数 ID**。|\ | | |:::tip| |父节点：VeFaaS |\ | | |当事件投递的目标是函数服务时，`FunctionId` 才为必选参数。| | |\ | | || | |\ | | |:::| | | |Kafka |Array |是|"Kafka":[|设置事件投递的目标为消息队列 Kafka 版，可以设置多个不同的 Kafka 实例。|\ | | |:::tip|{|父节点：Destination |\ | | |当事件投递的目标是消息队列 Kafka时，`Kafka`才为必选参数。|"Role":"trn:iam::214748\*\*\*\*:role/aaa",| |\ | | ||"InstanceId":"kafka\-cnoeb1pq83rs\*\*\*\*",| |\ | | |:::|"Topic":"test\-aaa",| |\ | | | |"User":"bbbbb"| |\ | | | |}| |\ | | | |] | | |Role |String |是 |trn:iam::214748\*\*\*\*:role/aaa |角色 TRN，该角色必须绑定系统预设策略 KafkaAccessForTOS ，用于授权 TOS 访问 Kafka 服务。|\ | | | | |父节点：Kafka|\ | | | | |:::tip|\ | | | | |您需要先创建角色，并为角色绑定系统预设策略 KafkaAccessForTOS，然后获取角色 TRN，具体操作，请参见 [CreateRole](https://www.volcengine.com/docs/6257/65016) 和 [AttachRolePolicy](https://www.volcengine.com/docs/6257/65033)。|\ | | | | ||\ | | | | |:::| |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 同级 | ## **响应消息头** 该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 ## **响应元素** 对于正确请求，响应中无消息元素。 ## 请求示例 * 设置事件通知投递至函数服务 ```JSON 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 版 ```Bash 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" } ] } } ] } ``` ## 响应示例 ```JSON 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 ```