@ edgeone/ pages- blob (英语)

Blob 为 Edge One Pages 函数存储 SDK,提供持续的密钥值存储,跨部署.

安装

npm install @edgeone/pages-blob

使用量

Pages 函数( 自动认证)

import { getStore } from "@edgeone/pages-blob";

const store = getStore("my-store");

// Write
await store.set("key", "value");
await store.setJSON("config", { theme: "dark" });

// Read
const text = await store.get("key");
const json = await store.get("config", { type: "json" });

// Delete
await store.delete("key");

// List
const { blobs } = await store.list({ prefix: "users/" });

外部访问( API Token 模式)

从外部调用 Page 函数时, 您必须提供 两者 token 财务报告和审定财务报表 projectId。 。 。 .

获取您的 API 打开这里: https://pages.edgeone.ai/document/api-token 页面存档备份,存于互联网档案馆

const store = getStore({
  name: "my-store",
  projectId: "makers-urtsvuwmfvli", // required
  token: "c+KH5...", // required
});

选择 projectId 掷出 MissingProjectIdError。 。 。 .

一致性强(读后写)

默认读取使用最终一致性(CDN-cached,低延迟). 改为: 保证后读一致,使用 "strong"数字 :

// Store-level default — all reads use strong consistency
const store = getStore({ name: "my-store", consistency: "strong" });

// Per-call override
await store.get("key", { consistency: "strong" });
await store.list({ consistency: "strong" });

"eventual" 缓缓的; "strong" 保证 以绕过缓存层为代价的最新值 .

列出所有仓库

import { listStores } from "@edgeone/pages-blob";

// Inside Pages Functions
const { stores } = await listStores();

// External access (token mode) - both fields required
const { stores } = await listStores({
  projectId: "pages-urtsvuwmfvli",
  token: "c+KH5...",
});

从浏览器直接上传( 指定 URL)

对于大型文件上传,将浏览器交给一个预先签名的PUT URL,并让它 字节直接流到 Pages Blob —— 您的函数只看到一个很小的 URL 请求,而不是文件本身.

// Function side — generate a one-shot upload URL
import { getStore } from "@edgeone/pages-blob";

export async function onRequest({ request }) {
  const { name } = await request.json();
  const store = getStore("uploads");
  const { url, key, expiresAt } = await store.createUploadUrl(`files/${name}`, {
    expireSeconds: 3600,            // optional, default 3600
    contentType: "application/octet-stream", // optional, binds Content-Type
  });
  return Response.json({ url, key, expiresAt });
}

// Browser side — plain fetch, no SDK needed
const { url, key } = await fetch("/api/get-upload-url", {
  method: "POST",
  body: JSON.stringify({ name: file.name }),
}).then((r) => r.json());

await fetch(url, {
  method: "PUT",
  body: file,                       // File / Blob / ArrayBuffer
  headers: { "Content-Type": "application/octet-stream" }, // must match if `contentType` was set
});
// Bytes go straight from the browser to Pages Blob, never through your Function.

签名将 URL 绑定为: PUT 方法, 准确的密钥, 时间窗口 , 和(可选)内容类型。 其他方法,其他密钥,过期的 URL, 和不匹配的内容- Type 全部返回 403 .

API 密码

getStore(name | options)

获取 Store 实例 .

store.set(key, value, options?)

写个Blob. value 支持 string | ArrayBuffer | Blob | ReadableStream。 。 。 .

store.setJSON(key, value, options?)

写入 JSON( 自动序列化 ) 。 接受同样的 options 作为 store.set。 。 。 .

store.get(key, options?)

读一个Blob。 回返 null 如果它不存在的话.

• options.type数字 : "text" (默认) "json" | "arrayBuffer" | "blob" | "stream"
• options.consistency数字 : "eventual" | "strong" (覆盖存储级别默认值)

store.getWithHeaders(key, options?)

读取一个blob 连同所有响应标题。 回返 null 如果密钥不存在.

回返情况: { body: string, headers: Record<string, string> }

• options.consistency数字 : "eventual" | "strong"

store.delete(key)

删除 Blob .

store.list(options?)

名单 Blobs. 默认情况下自动汇总所有页面.

• options.prefix: 前缀过滤器
• options.directories: 按目录分组
• options.limit: 要返回的最大blob数( 默认: 所有)
• options.paginate: 设置为 false 手动页标
• options.cursor: 从上一个页形光标恢复
• options.consistency数字 : "eventual" | "strong"

回返情况: { blobs: Array<{ key, etag }>, directories: string[] }

store.createUploadUrl(key, options?)

构建一个预先签名的 PUT URL,以便浏览器/客户端可以直接向上传文件 Pages Blob, 不需要字节流过您的功能 .

回返情况: { url: string, key: string, expiresAt: number } 地点 expiresAt 是一个以秒计的Unix时间戳.

URL与PUT+这个精确的密钥+签名时间窗口(和 可选内容-Type). 任何其它用途返回 403.

listStores(options?)

列出项目下的所有 Store .

• options.projectId: 项目ID (所需经费 (供外部使用)
• options.token: 访问符 (所需经费 (供外部使用)
• options.consistency数字 : "eventual" | "strong"

回返情况: { stores: Array<{ name: string }> }

超过配额

当超过自由计划时, store.set(), (中文(简体) ), store.setJSON() 财务报告和审定财务报表 store.createUploadUrl() 掷出 QuotaExceededError (单位:千美元)code: "QUOTA_EXCEEDED"(中文(简体) ) 在发送任何字节之前.

err.overMetrics 列出目前每个超过限度的度量,例如:. ["pages-blob-storage"]。 。 。 .

import { QuotaExceededError } from "@edgeone/pages-blob";

try {
  await store.set("key", value);
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // err.reason === "storage" → delete objects or upgrade the plan
  }
}

用法定期检查,所以写作可以持续几分钟 过了极限后 继续失败几分钟 背着它.

URL 来自 createUploadUrl() 在超过配额之前发放的 在浏览器的PUT上以403,550或重置连接失败; SDK 无法 看看这个反应.