跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

消费记录

最后更新 查看 MarkdownAgent 设置

消费者通过订阅从 K2 流读取记录,订阅 跟踪哪些记录已被处理。流上的每个订阅都 独立读取,这意味着多个应用可以读取相同的记录。

要消费记录:

  1. 在流上创建订阅。
  2. 请求一批记录。K2 会将该批次租给您的消费者。
  3. 处理记录,然后确认该批次。如果处理时间超过租约,请延长租约。
  4. 从第 2 步重复。

K2 至少投递一次记录。您的消费者可能会多次收到同一条记录。有关详情,请参阅投递保证。

开始之前

所有消费者请求都使用流端点 https://<STREAM_ID>.k2.cloudflarestorage.com,并需要在拥有该流的账户中具有 K2 Consume 权限的 API token。

本页示例使用以下 shell 变量:

export K2_ENDPOINT=https://<STREAM_ID>.k2.cloudflarestorage.com
export CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN>

创建订阅后,导出其 ID。请求一批后,从响应中导出 batch_id:

export SUBSCRIPTION_ID=<SUBSCRIPTION_ID>
export BATCH_ID=<BATCH_ID>

创建订阅

curl "$K2_ENDPOINT/subscriptions" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "orders-ingestion",
    "start_at": { "type": "earliest" }
  }'
{
	"result": { "id": "e2f747f8bccf453eb2767496779cd135" },
	"success": true,
	"errors": [],
	"messages": []
}
字段 类型 必填 说明
name string 是 1 到 128 个字母、数字、下划线或连字符。在流内必须唯一。不区分大小写。
start_at.type string 是 订阅开始读取的位置。earliest 从最旧的仍保留记录开始。latest 从流中最新记录之后开始。

订阅一旦创建便不可变。

如果您使用与现有订阅相同的名称和设置创建订阅,K2 会返回现有订阅 ID。如果名称匹配但设置不同,K2 会返回 422 错误。

管理订阅

操作 请求
列出订阅 GET /subscriptions
按名称查找订阅 GET /subscriptions?name=<SUBSCRIPTION_NAME>
获取订阅 GET /subscriptions/<SUBSCRIPTION_ID>
删除订阅 DELETE /subscriptions/<SUBSCRIPTION_ID>

列表请求返回订阅数组,最旧的在前。带 name 的请求最多返回包含一个订阅的数组。

获取请求返回单个订阅:

{
	"result": {
		"id": "e2f747f8bccf453eb2767496779cd135",
		"name": "orders-processor",
		"start_at": { "type": "earliest" },
		"created_at": "2026-09-23T12:00:00.000Z",
		"modified_at": "2026-09-23T12:00:00.000Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

一个流最多可以有 100 个订阅。如果您在已有 100 个订阅的流上创建订阅,K2 会返回代码为 10219 的 422 错误。删除现有订阅后再创建新订阅。

请求批次

向 /subscriptions/<SUBSCRIPTION_ID>/consume 发送 POST 请求:

curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/consume" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "worker_id": "worker-1",
    "max_records": 100
  }'
字段 类型 必填 说明
worker_id string 是 消费者标识符,1 到 256 个字符。每个并发消费者使用不同的值。
max_records integer 是 返回的最大记录数,从 1 到 10000。
{
	"result": {
		"batch_id": "4f1c2a9e8b7d4c6f9a0e1d2c3b4a5968",
		"leased_until_ms": 1790165100000,
		"records": [
			{
				"timestamp_ms": 1790164800000,
				"content": "eyJvcmRlcl9pZCI6MTAwMSwic3RhdHVzIjoiY3JlYXRlZCJ9",
				"headers": { "event-type": "order.created" }
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}
字段 说明
batch_id 已租出批次的 ID。用于确认该批次。
leased_until_ms 租约到期时间,为自 Unix 纪元以来的毫秒数。
records[].timestamp_ms K2 收到记录的时间,为自 Unix 纪元以来的毫秒数。
records[].content 记录负载,为标准 base64。
records[].headers 记录标头。如果生产时没有标头则省略。

max_records 是返回记录数的上限,但批次可能包含 更少的记录。这并不一定意味着没有更多可用记录。

没有可用记录

如果没有新记录,响应会包含空批次:

{
	"result": { "batch_id": null, "leased_until_ms": null, "records": [] },
	"success": true,
	"errors": [],
	"messages": []
}

请等待后再发送另一个请求。使用退避间隔,避免持续轮询。

租约

K2 返回批次时,会将该批次租给请求它的 worker_id。租约持续五分钟。

  • 每个 worker_id 一次只能持有一个租约。
  • K2 从不会将相同记录同时租给两个 worker。
  • 一个订阅最多可以有 128 个活动租约。如果所有租约都在使用中,K2 会返回代码为 10216 的 429 错误。
  • K2 不保证共享同一订阅的 worker 处理记录的顺序。

如果 worker 在已持有租约时请求批次,K2 会再次返回 同一批次和记录,并刷新租约。返回同一批次时,K2 会忽略 max_records。 如果消费者丢失响应(例如网络错误后),可使用此方式恢复批次。

如果租约在批次被确认前到期,K2 会将记录再次投递给下一个请求批次的 worker。

确认批次

处理完批次后,确认它。这会将这些记录标记为已处理并释放租约,以便 worker 可以请求下一批次。

curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/batches/$BATCH_ID/ack" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "worker_id": "worker-1" }'
{ "result": {}, "success": true, "errors": [], "messages": [] }

在 leased_until_ms 之前确认批次。如果租约已过期且 K2 已在新批次中投递这些记录,则该确认不会生效。

多次确认同一批次是安全的。对于未知或已确认的批次,K2 会返回成功响应。

延长租约

如果消费者处理批次需要超过五分钟,请在租约到期前延长它:

curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/batches/$BATCH_ID/extend" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "worker_id": "worker-1" }'
{
	"result": { "leased_until_ms": 1790165400000 },
	"success": true,
	"errors": [],
	"messages": []
}

成功延长会将租约设置为请求后五分钟到期。它绝不会缩短租约。

与 ack 和 nack 不同,worker_id 必须匹配持有该租约的 worker。如果租约已 过期、已释放,或批次已被确认或投递给另一个 worker,K2 会返回代码为 10218 的 409 错误。重试同一请求不会成功。停止处理该 批次并请求新批次。K2 会以新的 batch_id 再次投递这些记录。

释放批次

如果消费者无法处理某个批次,请发送否定确认(nack) 立即释放它,而不是等待租约到期:

curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/batches/$BATCH_ID/nack" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "worker_id": "worker-1" }'
{ "result": {}, "success": true, "errors": [], "messages": [] }

K2 会在任意 worker 请求的下一批次中再次投递已释放的记录, 并使用新的 batch_id。在该新批次被确认之前,订阅不会越过这些记录。

处理错误

订阅和消费错误使用 Cloudflare API 格式,包含 errors 数组:

{
	"result": null,
	"success": false,
	"errors": [
		{
			"code": 10216,
			"message": "All parallel read slots for this subscription are in use, please retry"
		}
	],
	"messages": []
}

这与生产错误的格式不同。

对于代码为 10211、10214、10216 或 10217 的失败请求,请在退避间隔后重试。不要在未更改请求的情况下重试其他错误。

订阅和消费错误代码

代码 HTTP 状态 说明
10200 404 流不存在。
10201 422 已存在同名但设置不同的订阅。
10204 400 请求无效。例如 JSON 格式错误或字段超出范围。
10205 415 Content-Type 标头不是 application/json。
10208 401 请求没有 Authorization 标头。
10209 401 Authorization 标头格式错误或 API token 无效。
10210 403 API token 没有从此流消费的权限。
10211 503 K2 暂时不可用。请重试该请求。
10213 500 发生内部错误。
10214 503 K2 无法从存储读取记录。请重试该请求。
10215 404 订阅不存在。
10216 429 此订阅的并发消费者数量已达上限。请在租约被确认、释放或到期后重试。
10217 409 K2 仍在为此 worker_id 读取更早请求的批次。请重试该请求以接收批次。
10218 409 此 worker 不再持有该租约。请勿重试。改为请求新批次。
10219 422 流已达到最多 100 个订阅的上限。

后续步骤

  • 在限制中查看消费者限制。

这篇文档对您有帮助吗?