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

快速入门

最后更新 查看 MarkdownAgent 设置

本指南将带您完成创建 K2 流、向其写入记录,以及通过订阅消费的过程。

完成本指南后,您将:

  • 使用 Cloudflare API 创建了流。
  • 通过 HTTP 向流生产了一批记录。
  • 创建了跟踪读取位置的订阅。
  • 消费了一批记录并确认了该批次。

前提条件

  1. 注册 Cloudflare 账户 ↗ 并订阅 Workers Paid 计划。K2 在 Workers Free 计划上不可用。
  2. 查找您的 账户 ID。
  3. 安装 curl ↗ 和 jq ↗。

K2 的工作原理

K2 stream(流)是持久、仅追加的记录日志。每条 record(记录) 包含二进制 content 负载和可选的字符串 headers。

生产者按批次向流追加记录。每个批次原子写入: 批次中的每条记录都会被存储,或者一条也不存储。

消费者通过 subscription(订阅)从流读取。订阅跟踪 流中的位置。同一流上的多个订阅彼此独立读取。

当消费者从订阅读取时,K2 会向该消费者租出一批记录。 消费者处理完记录后确认该批次。 如果消费者未在租约到期前确认批次,K2 会再次投递这些记录。这为您提供至少一次投递。

1. 创建 API token

您需要 API token 来创建流并从中读取。

  1. 在 Cloudflare 仪表板中,转到 Account API tokens(账户 API 令牌) 页面。

    前往 Account API tokens(账户 API 令牌) ↗
  2. 选择 Create Token(创建令牌) > Create Custom Token(创建自定义令牌)。

  3. 为令牌输入名称,例如 k2-get-started。

  4. 在 Permissions(权限) 下,为您的账户添加 K2 Config Write、K2 Produce 和 K2 Consume 权限。K2 Config Write 允许您创建和删除流。

  5. 选择 Continue to summary(继续查看摘要) > Create Token(创建令牌)。

  6. 复制令牌值。离开该页面后将无法再次查看。

将账户 ID 和 API token 导出为 shell 变量。本指南中的命令使用这些变量。

export ACCOUNT_ID=<YOUR_ACCOUNT_ID>
export CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN>

2. 创建流

创建名为 orders 的流。此请求启用 HTTP 端点,并要求使用 API token 向其生产记录。

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/k2/streams" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "orders",
    "http": {
      "enabled": true,
      "authentication": true
    }
  }'
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"id": "241fa65b438a4d539a19371f58bfdae0",
		"name": "orders",
		"retention_seconds": 604800,
		"endpoint": "https://241fa65b438a4d539a19371f58bfdae0.k2.cloudflarestorage.com",
		"http": {
			"enabled": true,
			"authentication": true
		},
		"worker_binding": {
			"enabled": true
		},
		"created_at": "2026-09-24T21:19:19.246Z",
		"modified_at": "2026-09-24T21:19:19.246Z"
	}
}

响应包括:

  • id:流 ID。用于构建流端点。
  • endpoint:生产和消费记录的基础 URL。
  • retention_seconds:K2 保留记录的时长。默认为七天(604800 秒)。

将流 ID 和端点导出为 shell 变量:

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

流配置选项

字段 必填 说明
name 是 1 到 128 个字母、数字或下划线。在账户内必须唯一。名称不区分大小写。
http.enabled 是 启用 HTTP /produce 端点。
http.authentication 否 通过 HTTP 生产时需要 API token。如果省略此字段,任何拥有端点 URL 的人都可以生产。
http.cors.origins 否 最多五个允许从浏览器生产的源,或 ["*"] 以允许任意源。
worker_binding.enabled 否 允许 Worker 通过绑定生产。默认为 true。
retention_seconds 否 记录保留期,从 3600(一小时)到 2592000(30 天)。默认为 604800(七天)。

http 或 worker_binding 至少必须启用一个。

3. 生产记录

向流的 /produce 端点发送包含两条记录的批次。记录 content 必须是标准 base64。在此示例中,每条记录包含 base64 编码的 JSON 订单事件。

curl "$K2_ENDPOINT/produce" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "records": [
      {
        "content": "eyJvcmRlcl9pZCI6MTAwMSwic3RhdHVzIjoiY3JlYXRlZCJ9",
        "headers": { "event-type": "order.created" }
      },
      {
        "content": "eyJvcmRlcl9pZCI6MTAwMiwic3RhdHVzIjoiY3JlYXRlZCJ9",
        "headers": { "event-type": "order.created" }
      }
    ]
  }'
{ "success": true }

success: true 响应表示 K2 存储了批次中的每条记录。

要编码自己的负载,请将其通过 base64 管道处理:

printf '%s' '{"order_id":1001,"status":"created"}' | base64

4. 创建订阅

订阅跟踪消费者已处理的记录。创建名为 orders-processor 的订阅,从流中最早的记录开始。

curl "$K2_ENDPOINT/subscriptions" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "orders-processor",
    "start_at": { "type": "earliest" }
  }'
{
	"result": { "id": "e2f747f8bccf453eb2767496779cd135" },
	"success": true,
	"errors": [],
	"messages": []
}

请求体包含:

  • name:1 到 128 个字母、数字、下划线或连字符。在流内必须唯一。
  • start_at.type:earliest 从最旧的仍保留记录读取。latest 跳过创建订阅时已存在的记录。

使用相同名称和设置创建订阅会返回现有订阅 ID,因此该请求可以安全重试。

将订阅 ID 导出为 shell 变量:

export SUBSCRIPTION_ID=<SUBSCRIPTION_ID>

5. 消费记录

请求最多 100 条记录的批次。worker_id 标识您的消费者。每个 worker 一次只能持有一个租约。

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
  }'
{
	"result": {
		"batch_id": "4f1c2a9e8b7d4c6f9a0e1d2c3b4a5968",
		"leased_until_ms": 1790165100000,
		"records": [
			{
				"timestamp_ms": 1790164800000,
				"content": "eyJvcmRlcl9pZCI6MTAwMSwic3RhdHVzIjoiY3JlYXRlZCJ9",
				"headers": { "event-type": "order.created" }
			},
			{
				"timestamp_ms": 1790164800000,
				"content": "eyJvcmRlcl9pZCI6MTAwMiwic3RhdHVzIjoiY3JlYXRlZCJ9",
				"headers": { "event-type": "order.created" }
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}

响应包含:

  • batch_id:已租出批次的 ID。确认批次时需要它。
  • leased_until_ms:租约到期时间,为自 Unix 纪元以来的毫秒数。租约持续五分钟。
  • records:批次中的记录。timestamp_ms 是 K2 收到记录的时间,为自 Unix 纪元以来的毫秒数。content 为 base64。

要解码记录内容,请将响应通过 jq 管道处理:

curl --silent "$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}' \
  | jq -r '.result.records[].content | @base64d'
{"order_id":1001,"status":"created"}
{"order_id":1002,"status":"created"}

由于 worker-1 仍持有其租约,第二次请求会返回同一批次并刷新租约。如果消费者丢失响应,可使用此行为恢复批次。

如果没有可读取的记录,响应会包含空的 records 数组,且 batch_id 为 null。请等待后再轮询。

将响应中的批次 ID 导出为 shell 变量:

export BATCH_ID=<BATCH_ID>

6. 确认批次

处理完记录后,确认该批次。这会将订阅推进到这些记录之后,并释放租约,以便 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": [] }

如果处理失败,请改为向 /nack 而不是 /ack 发送相同请求。K2 会在不推进订阅的情况下释放租约,并再次投递这些记录。

再次运行第 5 步的 consume 请求。由于您已确认第一批,响应将不包含记录。

7. 清理

删除订阅:

curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID" \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": { "id": "e2f747f8bccf453eb2767496779cd135" },
	"success": true,
	"errors": [],
	"messages": []
}

删除流及其所有记录:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/k2/streams/$STREAM_ID" \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{ "success": true, "errors": [], "messages": [], "result": {} }

后续步骤

限制

查看记录大小、批次大小和订阅限制。

这篇文档对您有帮助吗?