金山云-文档中心-事件通知

KS3事件通知功能支持为指定Bucket设置事件通知规则，客户创建规则时，支持传入回调地址，触发事件通知规则后，KS3将事件通知内容将推送至客户的回调地址。

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

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

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

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

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

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

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

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

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

10. 使用该功能的用户，必须已经在KS3控制台开通批量处理角色授权（KsyunKS3BucketLoggingProcessingRole）。

支持的事件类型

事件类别	事件名称	KS3对应接口	描述
ks3:ObjectCreated:*	ks3:ObjectCreated:PutObject	PUT Object	调用PUT Object接口上传文件成功后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:CompleteMultipartUpload	Complete Multipart Upload	调用Complete Multipart Upload接口上传文件完成后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:SyncMirror	——	创建同步回源规则，同步回源成功上传到KS3后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:AsyncMirror	——	创建异步回源规则，异步回源成功上传到KS3后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:PostObject	POST Object	调用POST Object接口表单上传对象后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:CopyObject	PUT Object Copy	调用PUT Object Copy接口上传文件完成后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:AppendObject	Append Object	调用Append Object接口新增或追加文件，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:PutFetch	PUT Fetch	拉取对象上传至KS3成功后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:Replication	——	通过跨区域复制/同区域复制上传文件完成后触发，不区分新增上传或覆盖上传。
	ks3:ObjectCreated:Recover	Recover Object	调用Recover Object接口将回收站内文件恢复到桶内操作，不区分新增上传或覆盖上传。
ks3:ObjectRemoved:*	ks3:ObjectRemoved:DeleteObject	DELETE Object	调用DELETE Object接口删除文件后触发。
	ks3:ObjectRemoved:Lifecycle	——	通过生命周期规则删除文件后触发。
	ks3:ObjectRemoved:Retention	CLEAR Object	调用CLEAR Object接口删除回收站内文件成功后触发，不区分调用接口删除或通过回收站规则定时删除。

事件通知推送内容

当客户在KS3上进行新增或删除文件等相关操作触发事件通知后，KS3会将事件通知内容以JSON格式推送至客户的回调地址。

推送示例如下所示：

{
  "id": "fr4i8td4kb68al7sthmnrmpfllosbs3h",
  "source": "kcs:ks3",
  "ruleId": "jy_test_nx00001",
  "type": "ks3:ObjectCreated:PutObject",
  "specversion": "1.0",
  "time": "2025-06-24T12:54:09.932 08:00",
  "datacontenttype": "application/json",
  "subject": "jy-test-nx/21",
  "extensions": {
    "accountid": "73403574",
    "userid": "30542",
    "roleid": "",
    "region": "NINGXIA",
    "eventversion": "1.0"
  },
  "data": {
    "request": {
      "sourceIPAddress": "10.232.61.249"
    },
    "response": {
      "requestId": "fr4i8td4kb68al7sthmnrmpfllosbs3h"
    },
    "ks3": {
      "bucket": {
        "name": "jy-test-nx",
        "ownerid": "73403574"
      },
      "object": {
        "key": "21",
        "objectsize": "21",
        "etag": "xZHJRA3az9V0Y0jqGv7zjw==",
        "position": 21,
        "userMetaData": {
          "x-kss-meta-a": "1",
          "x-kss-meta-b": "2"
        }
      }
    }
  }
}

推送字段详细说明如下：

参数名称	说明
id	事件ID，标识事件的唯一性，与KS3接口请求ID一致。
source	提供事件的服务，固定值：`kcs:ks3`。
ruleId	客户创建事件通知规则时设置，单个UID内ruleId不能重复。
type	触发事件通知的事件类型。
specversion	CloudEvents协议版本，当前版本为`1.0`。
time	事件产生的时间，使用ISO-8601标准时间格式。示例：`2025-06-24T12:54:09.932 08:00`
datacontenttype	推送事件通知内容的格式，固定取值：`application/json`。
subject	指定触发事件通知的对象名称。示例：`bucketname/prefix1/prefix2/aaa.txt`
extensions	扩展属性，用于存放账号、地域等公共属性。
accountid	Bucket拥有者的账号ID（UID）。
userid	发起请求的子账号名称，如果是主账号访问，将不推送该字段。
roleid	请求发起者的角色ID。
region	Bucket所在的区域。
eventversion	KS3事件data schema版本，固定取值：`1.0`。
data	KS3操作及资源相关信息。
request	请求相关信息。
sourceIPAddress	请求者的源IP地址。
response	响应相关信息。
requestId	请求ID。
ks3	KS3资源相关信息。
bucket	Bucket相关信息。
name	Bucket的名称。
ownerid	Bucket的创建者对应的账号ID（UID）。
object	对象相关信息。
key	对象的Key。示例：`prefix1/prefix2/aa.png`
objectsize	对象的大小。
etag	对象的ETag值。
position	追加上传的起始位置。仅适用于`ks3:ObjectCreated:AppendObject`事件，表示此次请求开始追加的位置。首次AppendObject请求的位置从0字节开始。
userMetaData	自定义元数据信息。

操作流程

控制台操作流程

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

登录KS3控制台。
点击左侧的【存储空间】页签，进入存储空间列表。
点击目标存储空间名称，进入存储空间内，点击【空间设置】。
在空间设置界面找到对应的页签【事件通知】。
点击【立即授权】，根据操作指引完成角色授权。

点击【创建规则】，填写规则信息。

规则相关信息描述：

规则相关信息	描述
规则名称	设置事件通知规则名称，单个UID内唯一。
资源描述	设置符合规则的对象前缀和后缀，前后缀均为空表示该Bucket下的全部文件均符合规则。
事件类型	填写期望触发通知的事件名称，参见：支持的事件类型。
接收终端	回调地址。当触发事件通知时，KS3会以回调方式将事件通知消息体以JSON格式推送至该地址。
推送方式	事件通知内容推送至客户端地址的方式。
推送失败列表导出地址	推送失败列表报告投递的桶和前缀。

点击【确定】。

其他方式操作流程

操作方式	文档链接
API	PUT Bucket Notification GET Bucket Notification DELETE Bucket Notification
SDK	Java SDK