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

生产记录

最后更新 查看 MarkdownAgent 设置

您可以通过两种方式向 K2 流写入记录:

  • 通过 HTTP,向流的 /produce 端点发送 POST 请求。
  • 从 Worker,在 Workers 绑定上调用 send()。

每种输入都必须在流上启用。请参阅输入。

记录和批次

记录有两个字段:

字段 类型 必填 说明
content bytes 是 作为原始字节的记录负载。
headers string 到 string 的映射对象 否 关于记录的元数据。

记录以批次发送。批次必须至少包含一条记录,除最大批次大小外,记录数量没有其他限制。批次写入是原子的,因此批次中的所有记录要么全部成功记录,要么一条也不记录。

时间戳由服务器在收到批次时写入,目前用户无法覆盖。

有关记录、标头和批次大小限制,请参阅限制。

通过 HTTP 生产

向https://<STREAM_ID>.k2.cloudflarestorage.com/produce 发送 POST 请求。请求体是带有records 数组的 JSON 对象。记录 content 必须是标准 base64。

curl "https://$STREAM_ID.k2.cloudflarestorage.com/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"
      }
    ]
  }'
{ "success": true }

请求必须满足以下要求:

  • Content-Type 标头必须为 application/json。
  • 要压缩请求体,请对其进行 gzip 并设置 Content-Encoding: gzip 标头。大小限制同时适用于解压前和解压后。
  • content 必须是带有正确填充的标准 base64。不支持 URL-safe base64。
  • 请求体不能包含 records 以外的字段,记录不能包含 content 和 headers 以外的字段。
  • 如果 HTTP 输入启用了身份验证,请在 Authorization 标头中包含 API token。

从浏览器生产

要从网页生产,请将站点的源添加到流的 CORS 配置。

不要在浏览器中运行的代码里包含 API token,因为访问该页面的任何人都可以读取它。要从浏览器生产,流的 HTTP 输入必须禁用身份验证。这会使 /produce 端点公开,因此任何知道流 ID 的人都可以向该流写入记录。请在消费者中验证记录。

const encoder = new TextEncoder();

const records = [{ order_id: 1001, status: "created" }].map((event) => ({
	content: encoder.encode(JSON.stringify(event)).toBase64(),
	headers: { "event-type": "order.created" },
}));

const response = await fetch(
	"https://<STREAM_ID>.k2.cloudflarestorage.com/produce",
	{
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({ records }),
	},
);

const result = await response.json();
if (!result.success) {
	console.error(`Produce failed: ${result.error.message}`);
}

Uint8Array.prototype.toBase64() 可在较新的浏览器中使用。对于较旧的浏览器,请使用 btoa() 或 base64 库。

从 Worker 生产

Workers 绑定让 Worker 无需 API token 即可向流生产。绑定会为您处理身份验证。

配置绑定

在 Wrangler 配置文件中添加 k2 绑定。将 stream 设置为要生产到的流 ID:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "orders-producer",
  "main": "src/index.ts",
  "upload_source_maps": true,
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "k2": [
    {
      "binding": "ORDERS",
      "stream": "<STREAM_ID>"
    }
  ]
}
name = "orders-producer"
main = "src/index.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-14"

[[k2]]
binding = "ORDERS"
stream = "<STREAM_ID>"
字段 说明
binding Worker 代码中的绑定名称。在此示例中,绑定为 env.ORDERS。
stream 流 ID,32 个小写十六进制字符。流必须与 Worker 位于同一账户中。

要绑定到多个流,请为每个流添加一个 [[k2]] 条目。

部署时,Cloudflare 会检查该流是否存在于您的账户中,以及您是否有权使用它。如果检查失败,部署会失败并返回以下错误之一:

代码 说明
10399 绑定没有 stream 字段,或值不是 32 个小写十六进制字符的流 ID。
10400 您正在部署到的账户中不存在该流。
10401 您没有绑定此流的权限。
10402 Cloudflare 无法验证该绑定。请再次尝试部署。

发送记录

在绑定上调用 send(),并传入记录数组。记录 content 必须是ArrayBuffer 或 Uint8Array。批次中的每条记录必须使用相同类型。

此示例使用 wrangler types 根据 Wrangler 配置生成的 Env 类型。添加绑定后运行 npx wrangler types。

src/index.jsjs
export default {
	async fetch(request, env) {
		const event = { order_id: 1001, status: "created" };
		const encoder = new TextEncoder();

		const result = await env.ORDERS.send([
			{
				content: encoder.encode(JSON.stringify(event)),
				headers: { "event-type": "order.created" },
			},
		]);

		if (!result.success) {
			console.error(`Produce failed: ${result.error.message}`);
			return new Response("Failed to record event", {
				status: result.error.retryable ? 503 : 500,
			});
		}

		return new Response("Event recorded");
	},
};
src/index.tsts
export default {
	async fetch(request, env): Promise<Response> {
		const event = { order_id: 1001, status: "created" };
		const encoder = new TextEncoder();

		const result = await env.ORDERS.send([
			{
				content: encoder.encode(JSON.stringify(event)),
				headers: { "event-type": "order.created" },
			},
		]);

		if (!result.success) {
			console.error(`Produce failed: ${result.error.message}`);
			return new Response("Failed to record event", {
				status: result.error.retryable ? 503 : 500,
			});
		}

		return new Response("Event recorded");
	},
} satisfies ExportedHandler<Env>;

当 K2 拒绝批次时,send() 不会抛出。相反,它返回结果对象。每次调用后检查 result.success。

不支持字符串内容,包括 base64 字符串。发送前请使用 TextEncoder 将文本编码为字节。

处理错误

当批次失败时,K2 会返回错误对象,而不是 { "success": true }。通过 HTTP 时,响应还会具有非 200 的状态码。

{
	"success": false,
	"error": {
		"code": 10211,
		"message": "K2 is temporarily unavailable",
		"retryable": true
	}
}

如果 retryable 为 true,则 K2 未存储该批次。请使用指数退避重试同一批次。

如果 retryable 为 false,请不要在未更改批次的情况下重试。某些失败(例如 10212)结果未知:批次可能已存储,也可能尚未存储。K2 不会对记录去重,因此重试可能会将批次存储两次。请设计消费者以处理重复记录。

生产错误代码

代码 HTTP 状态 可重试 说明
10200 404 否 流不存在,或输入未启用。
10204 400 否 请求无效。例如 JSON 或 base64 格式错误,或标头超出大小限制。
10205 415 否 Content-Type 标头不是 application/json。
10206 413 否 请求超过 5 MB。
10207 413 否 一条记录超过 1 MB。
10208 401 否 流需要身份验证,且请求没有 Authorization 标头。
10209 401 否 Authorization 标头格式错误或 API token 无效。
10210 403 否 API token 没有向此流生产的权限。
10211 503 是 K2 暂时不可用。批次未被存储。
10212 503 否 K2 无法追加该批次。批次可能已存储,也可能尚未存储。
10213 500 否 发生内部错误。

后续步骤

这篇文档对您有帮助吗?