事件通知 · Cloudflare R2 docs

事件通知在 R2 存储桶中的数据发生变化时，向您的队列（Queues）发送消息。您可以使用消费者 Worker消费这些消息，或通过 HTTP pull从 Cloudflare Workers 外部拉取。

事件通知入门

前提条件

开始之前，您需要：

现有 R2 存储桶。若尚无 R2 存储桶，请参阅创建存储桶。
现有队列。若尚无队列，请参阅创建队列。
在 Queue 上启用消费者 Worker或 HTTP pull。

通过仪表板启用事件通知

在 Cloudflare 仪表板中，前往 R2 object storage（R2 对象存储） 页面。
Go to Overview ↗
选择要添加事件通知规则的存储桶。
切换到 Settings（设置） 选项卡，向下滚动至 Event notifications 卡片。
选择 Add notification（添加通知），选择接收通知的队列以及触发通知的事件类型。
选择 Add notification（添加通知）。

通过 Wrangler 启用事件通知

设置 Wrangler

首先安装 npm ↗。然后安装 Wrangler（Developer Platform CLI）。

在 R2 存储桶上启用事件通知

使用 wrangler login 命令登录 Wrangler。然后运行 r2 bucket notification create 命令为存储桶添加事件通知规则。

npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME>

要基于 prefix 或 suffix 添加过滤，请分别使用 --prefix 或 --suffix 标志。

# Filter using prefix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>"

# Filter using suffix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --suffix "<SUFFIX_VALUE>"

# Filter using prefix and suffix. Both the conditions will be used for filtering
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>" --suffix "<SUFFIX_VALUE>"

更完整的分步示例请参阅使用事件通知在 R2 中记录和存储上传事件。

事件通知规则

事件通知规则决定触发通知的事件类型，并可选择基于对象 prefix 和 suffix 启用过滤。每个 R2 存储桶最多可有 100 条事件通知规则。

事件类型

事件类型	描述	触发操作
`object-create`	创建新对象或覆盖现有对象时触发。	`PutObject` `CopyObject` `CompleteMultipartUpload`
`object-delete`	从存储桶中显式移除对象时触发。	`DeleteObject` `LifecycleDeletion`

消息格式

队列消费者以消息（Messages）形式接收通知。以下是消费者 Worker 将收到的消息体示例：

{
	"account": "3f4b7e3dcab231cbfdaa90a6a28bd548",
	"action": "CopyObject",
	"bucket": "my-bucket",
	"object": {
		"key": "my-new-object",
		"size": 65536,
		"eTag": "c846ff7a18f28c2e262116d6e8719ef0"
	},
	"eventTime": "2024-05-24T19:36:44.379Z",
	"copySource": {
		"bucket": "my-bucket",
		"object": "my-original-object"
	}
}

属性

属性	类型	描述
`account`	String	事件关联的 Cloudflare 账户 ID。
`action`	String	触发事件通知的操作类型。示例操作包括：`PutObject`、`CopyObject`、`CompleteMultipartUpload`、`DeleteObject`。
`bucket`	String	事件发生所在存储桶的名称。
`object`	Object	包含事件涉及对象详情的嵌套对象。
`object.key`	String	存储桶内对象的键（或名称）。
`object.size`	Number	对象大小（字节）。注意：object-delete 事件不包含此字段。
`object.eTag`	String	对象的实体标签 (eTag)。注意：object-delete 事件不包含此字段。
`eventTime`	String	触发事件的操作发生时间。
`copySource`	Object	包含被复制对象源详情的嵌套对象。注意：仅 `CopyObject` 触发的事件包含此字段。
`copySource.bucket`	String	包含源对象的存储桶。
`copySource.object`	String	源对象的名称。

说明

Queues 每队列消息吞吐量目前为每秒 5,000 条消息。若工作负载每秒产生超过 5,000 条通知，建议将通知规则拆分到多个队列。
无前缀/后缀的规则适用于存储桶中所有对象。
不允许重叠或冲突的规则对同一事件触发多条通知。例如，若有无前缀和后缀的 object-create（或 PutObject 操作）规则，再添加带 images/ 等前缀的 object-create（或 PutObject 操作）规则，可能对单次上传触发多条通知，这是无效的。