Docs
文档目录

限额与配额

这是什么 / 何时用

平台对项目/账号施加两类上限:

前置

示例中的 APPBASE_ENDPOINT 包含 /v1;APPBASE_SESSION_COOKIE 是登录后获得的完整 Cookie(名称和值),从本机受控环境装载。也可将 Cookie 换为 X-Appwrite-JWT 短期用户 JWT,勿同时混用业务项目 Key。

使用骨架

  1. 读当前配额:Console SDK(Node.js / Java)或 REST 读取 GET /projects/:projectId/quota-limits,返回 quota / sources / accountLimit / globalLimit——sources 说明每个字段值来自项目覆盖、账号 ceiling 还是全局默认。

  2. 更新项目配额:Console SDK(Node.js / Java)或 REST 调用 PATCH /projects/:projectId/quota-limits——部分更新,未传字段不变;0 表示不限(需上级 ceiling 允许)。

  3. 账号级配额:account.getQuotaLimits() / updateQuotaLimits(...) / deleteQuotaLimits(...)(删除覆盖回退继承值);listLimitsProjects() 只在部分 SDK 暴露,具体见 SDK 差异。

  4. 限频调优:PATCH /projects/:projectId/limits,body 为扁平的 5 个限频字段 + 4 个配额字段;响应含 rateLimit / quota / accountLimit / overrides。Console SDK 无该接口的 typed 封装时用 client.call('patch', ...),或用 REST。

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换调用方式;项目配额与限频卡片共享选择,账号配额卡片单独选择凭据路径。

项目配额(Quota)读写

项目级 Quota 四字段读写:读返回 quota / sources / accountLimit / globalLimit,写为部分更新(未传字段不变)。Node.js Console SDK 与 Java Console SDK 提供项目 quota 方法;Server SDK、Python / Go Console SDK 与 Web SDK 没有项目级 typed 方法,使用 REST。

// agentbase-node-sdk@2.10.0 的 Projects 没有项目级 getQuotaLimits / updateQuotaLimits。
// 项目 quota 请使用下方 Console SDK 页签或 REST;Server SDK 的 Account 仅管理账号级 quota。

账号级配额(Account Quota)

账号级读写 /account/quota-limits,以请求中的用户身份确定账号,不能仅凭 SDK 类型推断权限。Web Client 可使用当前用户 Session;管理平台账号时,使用 Console 上下文及该账号的 Session/JWT。

服务端自动化仅在目标环境已为平台账号签发并确认有效的 Account API Key 时使用此路径;Key 须具有 account scope,同时提供 X-Appwrite-Project: console、X-Appwrite-Key 和 Key 所属用户的 X-Appwrite-User。普通项目 Key 的 scope 集不包含 account,不能用项目 ID 代替用户 ID,也不能只调用 setKey 而省略用户头。账号 Key 与 Session/JWT 分开使用,不在同一 Client 中混装;凭据仅从受控环境装载,不写入文档、仓库或日志。本页不假定目标部署开放账号 Key 签发;没有已确认有效的账号 Key 时,使用 Console Session/JWT。

updateQuotaLimits 部分更新四字段,deleteQuotaLimits 删除覆盖回退继承值。Client Web、Server Node、Server/Console Java 还提供 listLimitsProjects;Console Node 有 quota 读写但没有该列表方法,Server Python/Go 也提供各自语言的账号级 quota API。生成方法存在不代表普通项目 Key 可调用,上述账号级能力也不等于项目级 quota 支持。

Client SDK 的读取示例见 client-sdk/web.md 与 JavaScript 示例;本页 Console 和 REST 页签展示账号管理路径。

// 账号级走 Console Session/JWT(非项目 API Key)
await sdk.forConsole.account.getQuotaLimits();
await sdk.forConsole.account.updateQuotaLimits({ tablesPerProject: 120 });   // 四 quota 字段部分更新
await sdk.forConsole.account.deleteQuotaLimits();   // 删除覆盖,回退继承值
// Console Node SDK 不提供 listLimitsProjects()

限频调优(综合 /limits:限频 + 配额)

/limits 一次读写 5 个限频字段 + 4 个配额字段;限频字段必须为正整数(没有 0=不限 语义),响应含 rateLimit / quota / accountLimit / overrides。Web Client 只提供账号级 quota,不提供项目级 quota 或 rate-limit 管理;项目级 /limits 的 typed 方法仅在 console-java Projects(getLimits(projectId) / updateLimits(projectId, 5 个限频字段 + 4 个配额字段) / deleteLimits(projectId, keys));server-java / server-python / server-go 的 Projects 均无,统一走 REST(Console 无 typed 封装时用 client.call,见卡内);账号级 /account/limits 在已提供该功能的 Server/Console SDK Account 中有 typed 方法。

// agentbase-node-sdk@2.10.0 的 Projects 没有 getLimits / updateLimits。
// 项目限频使用下方 Console 页签或 REST;Account 的同名方法是账号级接口。

示例指引