文档中心

对象存储

请输入

事件通知

事件通知概述

如果您希望实时掌握在 TOS 中的资源变动，可以设置事件通知规则。本文介绍事件通知的背景信息、前提条件及 TOS 支持的事件类型。

背景信息

TOS 支持将部分事件的变动投递到函数服务和消息队列 Kafka。函数服务和消息队列 Kafka 的介绍请参见什么是函数服务和什么是消息队列 Kafka版。

注意事项

当前仅华北2（北京）、华南1（广州）、华东2（上海）和亚太东南（柔佛）地域支持事件通知功能。

创建、修改事件通知规则后，规则将在数分钟内逐步生效，期间也可能收到部分历史操作的事件通知。如需仅处理规则生效后的新增事件，建议依据事件发生时间字段 eventTime 做数据过滤。

TOS 事件通知采用服务端主动推送机制，消息推送的可靠性依赖接收端目标服务（函数服务/消息队列 Kafka 版）的写入能力。若目标服务的写入速率持续低于事件生成速率，通知消息将在服务端持续积压。当积压量达到上限后，新增的事件通知消息将被丢弃，且无法恢复。

为降低消息积压和丢失风险，建议采取以下措施：

提前规划容量：预先评估业务峰值事件量。

使用函数服务时，应配置充足的计算资源和并发配额。

使用消息队列 Kafka 版时，应选择满足业务峰值写入吞吐要求的实例规格。

完善监控告警：为推送目标配置性能水位监控告警，并在消费侧增加基于事件 eventTime 的接收延迟告警。一旦监测到积压持续上涨，及时扩容推送目标性能，防止消息丢失。

支持的事件类型

事件类别	事件名称	TOS 对应接口	描述
tos:ObjectCreated:*	tos:ObjectCreated:Put	PutObject	通过简单上传对象后触发。
		tos:ObjectCreated:Post	PostObject	通过表单上传对象后触发。
		tos:ObjectCreated:Origin	GetObject	创建回源规则，回源成功上传到 TOS 后触发。
		tos:ObjectCreated:Fetch	FetchObject	拉取对象后触发。
		tos:ObjectCreated:Copy	CopyObject	对象复制成功后触发。
		tos:ObjectCreated:CompleteUpload	CompleteUpload	分片上传提交成功后触发。
		tos:ObjectCreated:Append	AppendObject	追加上传成功后触发。
		tos:ObjectCreated:Modify	ModifyObject	修改对象后触发。说明仅 HNS 桶支持配置 tos:ObjectCreated:Modify事件。
tos:ObjectRemoved:*	tos:ObjectRemoved:Delete	DeleteObject	删除对象后触发（包括批量删除）。
		tos:ObjectRemoved:DeleteMarkerCreated	DeleteObject	删除对象生成删除标记后触发。
		tos:ObjectRemoved:TrashMoved	DeleteObject	删除对象，并将对象移入回收站后触发。说明仅 HNS 桶支持配置 tos:ObjectRemoved:TrashMoved 事件。
tos:LifecycleExpiration:*	tos:LifecycleExpiration:Delete	DeleteObject	通过生命周期规则永久删除对象后触发。
		tos:LifecycleExpiration:DeleteMarkerCreated	DeleteObject	通过生命周期规则创建删除标记后触发。
		tos:LifecycleExpiration:TrashMoved	DeleteObject	通过生命周期规则删除对象，并将对象移入回收站后触发。说明仅 HNS 桶支持配置 tos:LifecycleExpiration:TrashMoved 事件。
tos:ObjectReplication:*	tos:ObjectReplication:ObjectCreated	-	通过跨区域复制规则或同区域复制规则生成对象后触发。
tos:ObjectReplication:*		tos:ObjectReplication:ObjectModified	-	通过跨区域复制规则或同区域复制规则覆盖对象后触发。
tos:ObjectRestore:*	tos:ObjectRestore:Post	RestoreObject	创建归档存储、冷归档和深度冷归档恢复任务后触发。
tos:ObjectRestore:*		tos:ObjectRestore:Completed	RestoreObject	完成归档存储、冷归档和深度冷归档恢复任务后触发。
tos:LifecycleTransition	tos:LifecycleTransition	-	使用生命周期管理功能完成对象的存储类型转换后触发。
tos:ObjectRename	tos:ObjectRename	RenameObject	使用 RenameObject 完成对象重命名后触发。

事件通知格式

对象存储事件触发的事件通知格式如下所示。

注意

events 为数组类型，单次通知可能包含多个事件。

{"events": [​
      {​
       "eventName":"tos:ObjectCreated:Put",​
        "eventSource":"tos",​
        "eventTime":"2022-08-29T08:50:54Z",​
        "eventVersion":"1.0",​
        "tos":{​
            "bucket":{​
                "trn":"trn:tos:::test",​
                "name":"test",​
                "ownerIdentity":"2100000000"​
             },​
             "object":{​
                 "eTag":"\"cbd8273ce352dfac24d5d65fa3f8****\"",​
                 "key":"aa.png",​
                 "size":29098,​
                 "versionId":"57CE0809CDADB97E****"​
             },​
             "tosSchemaVersion":"1.0",​
             "ruleId":"testput",​
             "region":"cn-beijing",​
             "requestParameters":{​
                 "sourceIPAddress":"192.160.**.***:*****",​
                 "customParameters": "image"​
             },​
             "responseElements":{​
                 "requestId":"99cb480c7dee50d6630c7dee-ac14****"​
             },​
             "userIdentity":{​
                 "principalId":"trn:iam::2100000000:user/test"​
            }       ​
        }        ​
     }​
  ]​
}​

参数说明如下。

参数							类型	示例值	描述
eventName							String	tos:ObjectCreated:Put	事件通知类型，TOS 支持的事件类型，请参见事件类型。
eventSource							String	tos	设置事件通知的消息源，固定为 tos。
eventTime							String	2022-08-29T08:50:54Z	事件产生的时间。使用 ISO-8601 时间表示法。
eventVersion							String	1.0	事件通知版本号，目前为 1.0。
tos	bucket	trn			String	trn:tos:::test	Bucket 的唯一标识符，格式为trn:tos:::<bucketname>。
				name			String	test	存储桶名称。
				ownerIdentity			String	2100100000	创建 Bucket 的火山引擎账号ID。
		object	eTag			String	"cbd8273ce352dfac24d5d65fa3f8****"	对象的 ETag，deleteMarkerCreate 事件时该参数为空。
				key			String	aa.png	对象名称。
				size			Integer	29098	对象大小， deleteMarkerCreate 事件时该参数为0。
				versionId			String	57CE0809CDADB97E****	对象版本 ID，deleteMarkerCreate 事件时，该参数为 deleteMarker 的 ID。
				originKey			String	abc.txt	使用 RenameObject 重命名对象，或删除对象，并将对象移入回收站的场景中，源对象的名称。
		tosSchemaVersion					String	1.0	此字段域的版本号，目前为 1.0。
		ruleId					String	testput	设置的事件通知名称。
		region					String	cn-beijing	存储桶所在的地域。
		requestParameters	sourceIPAddress			String	192.160..:****	请求的源 IP 地址。
		responseElements	requestId			String	99cb480c7dee50d6630c7dee-ac14****	请求对应的 Request ID。
		userIdentity	principalId			String	trn:iam::2100000000:user/test	请求发起者对应的火山引擎账号信息，说明如下：使用主账号：为主账号 ID。使用子账号：格式为 trn:iam::<AccountID>:user/<username>。
		archiveEventData	restoreEventData	restorationExpiryTime	String	2024-02-02T00:00:00Z	恢复文件后生成的临时副本文件的有效期，采用 ISO-8601 格式。说明仅设置事件为 tos:ObjectRestore:Completed，且完成归档存储、冷归档和深度冷归档恢复任务后才会展示 restorationExpiryTime 参数。
		archiveEventData	restoreEventData			restoreStorageClass	String	ARCHIVE	恢复的源文件存储类型，取值说明如下： ARCHIVE：归档存储。 COLD_ARCHIVE：冷归档。 DEEP_COLD_ARCHIVE：深度冷归档。说明仅设置事件为 tos:ObjectRestore:Completed，且完成归档存储、冷归档和深度冷归档恢复任务后才会展示 restoreStorageClass 参数。
		lifecycleEventData	transitionEventData	destinationStorageClass	String	INTELLIGENT_TIERING	使用生命周期管理功能转换存储类型时，对象的目标存储类型，取值说明如下： IA：低频存储 INTELLIGENT_TIERING：智能分层存储 ARCHIVE_FR：归档闪回存储 ARCHIVE：归档存储 COLD_ARCHIVE：冷归档存储 DEEP_COLD_ARCHIVE：深度冷归档存储说明仅设置事件为 tos:LifecycleTransition ，且使用生命周期管理功能完成对象的存储类型转换后才会展示 destinationStorageClass 参数。

规则托管

云服务在创建事件通知规则时，可通过特定参数将其标记为“托管规则”。用户对这些被托管的规则仅保留只读权限。

前提条件

已开通对象存储 TOS 服务，并创建存储桶。

已接入需要托管事件通知的其他服务（如 vePFS、EFS 等）。

注意事项

项目	说明
能力提供方	托管动作本身在对应的托管服务处产生。
权限说明	被托管的规则，用户仅保留对该规则的只读权限，不支持通过 TOS 控制台或 TOS API 删除、修改该规则。创建托管规则的云服务拥有对该规则的完整生命周期管理权限，包括读取、修改和删除。
托管服务标识	在 TOS 控制台中，被托管规则会显示对应的托管服务名称（如 vePFS）。
取消托管	托管动作由托管服务方发起，能否取消托管需咨询对应的托管服务方，无法在 TOS 侧直接解除。

最近更新时间：2026.09.29 16:38:02

这个页面对您有帮助吗？

有用

无用