金山云-文档中心-PUT Bucket Notification

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

Bucket相关

事件通知（Notification）

PUT Bucket Notification

最近更新时间：2025-09-17 15:39:21



该接口用于针对指定Bucket设置事件通知规则，客户创建规则时，支持传入回调地址，触发事件通知规则后，KS3将事件通知内容将推送至客户的回调地址。调用该接口的用户必须是桶的拥有者或具有ks3:PutBucketNotification权限。

注：使用事件通知功能前需设置若干权限，详情请参见文档：事件通知。

1. 如果某个Bucket之前已经有事件通知规则，新添加的规则将全部覆盖旧规则，请注意这一点以免误删。如果想要增加而不是覆盖规则，可以通过先GET Bucket Notification获取已有规则后，在已有规则的基础上叠加规则进行设置。

2. 单个规则（Rule）不支持修改，仅支持新增和删除。

3. 事件通知功能仅支持宁夏、俄罗斯区域。

4. 事件通知为邀测功能，如有需要请联系商务或提交工单申请。

5. 仅支持公网推送至客户的回调地址，不支持内网推送。

6. 不支持匿名访问KS3触发事件通知规则，请求KS3如果需要触发事件通知，需要携带签名访问。

7. 不支持跨账号访问触发事件通知规则。

8. 创建事件通知规则成功后，预计5分钟生效。

9. 不同的规则可以设置相同的回调地址，同一个规则也可以同时设置多个不同的回调地址。

10. 两个规则（Rule）如果事件类型一致，则前缀或后缀不允许存在重叠。

11. 有关事件通知规则更多详细描述，请参见文档：事件通知。

请求语法

PUT /?notification HTTP/1.1 
Host: {BucketName}.{endpoint} 
Date: {date} 
Authorization: {SignatureValue} 
Content-length: {length} 
Content-MD5: {md5}   

Bucket notification written in JSON

请求头

该接口仅使用公共请求头。

请求体

一段描述事件通知规则的JSON：

{
  "Notifications": [
    {
      "RuleId": "testNotification1",
      "Method": "PUT",
      "Events": [
        "ks3:ObjectCreated:PutObject",
        "ks3:ObjectCreated:PostObject"
      ],
      "Resources": [
        {
          "Prefix": "",
          "Suffix": ""
        }
      ],
      "Destinations": [
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        },
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        }
      ],
      "Report": {
        "ReportType": "failed",
        "Enabled": "true",
        "Bucket": "bucketname",
        "Prefix": "prefixname"
      }
    },
    {
      "RuleId": "testNotification2",
      "Method": "POST",
      "Events": [
        "ks3:ObjectCreated:SyncMirror",
        "ks3:ObjectCreated:AsyncMirror"
      ],
      "Resources": [
        {
          "Prefix": "prefix1",
          "Suffix": "suffix1"
        },
        {
          "Prefix": "prefix2",
          "Suffix": "suffix2"
        }
      ],
      "Destinations": [
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        },
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        }
      ],
      "Report": {
        "ReportType": "failed",
        "Enabled": "true",
        "Bucket": "bucketname",
        "Prefix": "prefixname"
      }
    }
  ]
}

请求体内相关元素的具体描述如下：

名称	是否必选	说明
Notifications	是	事件通知规则信息。每个Bucket最多可同时配置10个事件通知规则。
RuleId	是	设置事件通知规则名称（单个UID内唯一），命名规范如下：父节点：Notifications RuleId的命名规范如下： 1. 单个UID下创建的规则名称不能重复，重复设置就会覆盖。 2. 长度不能超过32个字符。 3. 必须以小写字母开头 ([a-z])，后面可以跟字母、数字或下划线 ([a-zA-Z0-9_]{0,31})。
Method	否	事件通知内容推送至客户端地址的方式，取值如下： POST（默认） PUT
Events	是	设置需要触发消息通知的事件类型。父节点：Notifications 1. 单个规则支持选择多个事件类型。 2. KS3支持的事件通知类型请参见文档：事件通知。
Resources	否	设置需要触发事件通知的对象过滤规则。支持设置前缀（Prefix）、后缀（Suffix），即符合前后缀要求的文件才会触发事件通知规则。父节点：Notifications 1. 如果同时设置了前缀与后缀规则，则事件需要同时满足二者，才会触发事件通知。 2. 如果前后缀均未设置，则会匹配存储桶内所有对象。 3. 单个规则（Rule）的路径不允许有重叠。 4. 单条规则（Rule）支持最多同时设置5个触发路径。 5. 两个规则（Rule）如果事件类型一致，则前缀或后缀不允许存在重叠。
Prefix	否	设置符合规则的对象前缀。父节点：Resources 取值：0-1024字节 1. 当不填写Prefix和Suffix时，表示对整个桶内的文件均设置事件通知规则。 2. 如果要匹配Bucket内下名称为`examplefolder`目录中的全部对象，则前缀填写为`examplefolder/`，后缀（Suffix）置空即可。 3. 两个规则（Rule）如果事件类型一致，则前缀或后缀不允许存在重叠。
Suffix	否	设置符合规则的对象后缀。父节点：Resources 取值：0-1024字节 1. 如果要匹配Bucket内所有名称以`.jpg`结尾的对象，则前缀（Prefix）置空，后缀（Suffix）填写为`.jpg`即可。 2. 两个规则（Rule）如果事件类型一致，则前缀或后缀不允许存在重叠。
Destinations	是	包含回调地址信息的容器。父节点：Notifications 子节点：DestType、CallbackUrl 单个规则（Rule）内，最多支持填写5个回调地址。
DestType	是	回调地址信息的类型，固定取值：EndPoint。父节点：Destinations
CallbackUrl	否	回调地址。当触发事件通知时，KS3会以回调方式将事件通知消息体以JSON格式推送至该地址。父节点：Destinations 1. 支持HTTP或HTTPS。 2. 支持填写IP+端口号。示例：`http://198.51.100.1:8080` 3. 支持填写域名地址。示例：`http://test.com` 4. 支持填写带参数地址。示例：`https://ip:port/oss/sync/{id}?ak=xxxx` 5. 仅支持公网推送，不支持内网推送。
Report	是	导出推送失败列表报告。父节点：Notifications 1. 当触发事件通知规则时，KS3会将事件通知内容推送至客户回调地址内，推送成功后KS3接口会返回响应头`x-kss-eventBridge-status` ，该响应头的Value值为Base64编码，解码后的内容为`Code: Success`。 2. 当触发事件通知规则时，由于网络抖动或其他异常场景导致事件通知内容推送至客户回调地址失败，KS3接口会返回响应头`x-kss-eventBridge-status` ，该响应头的Value值为Base64编码，解码后的内容为`Code: Fail`。 3. 针对异常场景导致事件通知内容推送至客户回调地址失败，KS3会将该通知内容以失败列表的方式导出并每天定时投递至客户的指定桶内内。
ReportType	是	推送的报告类型，仅支持导出推送失败的列表报告，固定值failed。父节点：Report
Enabled	是	是否导出并投递失败列表报告，固定取值：true。父节点：Report
Bucket	是	推送失败列表报告投递的桶名称。父节点：Report
Prefix	否	推送失败列表报告投递的目录名称。取值范围：0-1024字节父节点：Report 如果Prefix不存在，KS3将自动创建该名称的Prefix。

响应头

该接口仅返回公共响应头。

响应体

该接口不返回响应体。

示例

请求示例

PUT /?notification HTTP/1.1 
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: xxx 
Authorization: authorization string
Content-Length: yyy
Content-type: application/xml 

{
  "Notifications": [
    {
      "RuleId": "testNotification1",
      "Method": "PUT",
      "Events": [
        "ks3:ObjectCreated:PutObject",
        "ks3:ObjectCreated:PostObject"
      ],
      "Resources": [
        {
          "Prefix": "",
          "Suffix": ""
        }
      ],
      "Destinations": [
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        },
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        }
      ],
      "Report": {
        "ReportType": "failed",
        "Enabled": "true",
        "Bucket": "bucketname",
        "Prefix": "prefixname"
      }
    },
    {
      "RuleId": "testNotification2",
      "Method": "POST",
      "Events": [
        "ks3:ObjectCreated:SyncMirror",
        "ks3:ObjectCreated:AsyncMirror"
      ],
      "Resources": [
        {
          "Prefix": "prefix1",
          "Suffix": "suffix1"
        },
        {
          "Prefix": "prefix2",
          "Suffix": "suffix2"
        }
      ],
      "Destinations": [
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        },
        {
          "DestType": "Endpoint",
          "CallbackUrl": "http://****"
        }
      ],
      "Report": {
        "ReportType": "failed",
        "Enabled": "true",
        "Bucket": "bucketname",
        "Prefix": "prefixname"
      }
    }
  ]
}

响应示例

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Tue, 19 Jul 2017 09:14:23 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***

报错

状态码（Status）	错误码（Code）	描述
403 Forbidden	AccessDenied	缺少权限
400 Bad Request	InvalidArgument	存在以下情况： RuleId参数为空或参数填写不合法。 Events存在不支持的事件。单桶规则数量超过10个。单条规则（Rule）填写的回调地址数量超过5个。 RuleId重复。单个规则（Rule）内的前后缀存在重叠。
404 Not Found	NoSuchBucket	桶不存在

文档导读

上一篇：事件通知（Notification）

下一篇：GET Bucket Notification

纯净模式常规模式

纯净模式

点击可全屏预览文档内容