消费者通过订阅从 K2 流读取记录,订阅 跟踪哪些记录已被处理。流上的每个订阅都 独立读取,这意味着多个应用可以读取相同的记录。
要消费记录:
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 个订阅的上限。 |
- 在限制中查看消费者限制。