您可以通过两种方式向 K2 流写入记录:
每种输入都必须在流上启用。请参阅输入。
记录有两个字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
content |
bytes | 是 | 作为原始字节的记录负载。 |
headers |
string 到 string 的映射对象 | 否 | 关于记录的元数据。 |
记录以批次发送。批次必须至少包含一条记录,除最大批次大小外,记录数量没有其他限制。批次写入是原子的,因此批次中的所有记录要么全部成功记录,要么一条也不记录。
时间戳由服务器在收到批次时写入,目前用户无法覆盖。
有关记录、标头和批次大小限制,请参阅限制。
向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 库。
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。
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");
},
};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 |
否 | 发生内部错误。 |
- 通过订阅消费记录。