函数
这是什么 / 何时用
服务端无服务器函数:响应 HTTP / SDK 调用 / 平台事件 / 定时任务,运行在隔离沙箱(托管环境经 ACS Agent Sandbox,本地 Docker 基于 OpenRuntimes)。何时用:后端逻辑代理(如复杂授权,见 permissions.md)、事件驱动处理、定时任务、轻量 API。
前置
- Server API Key:管理需
functions.write,**触发执行需execution.write**,读取记录需execution.read,查看需functions.read(创建 Key 时触发与管理的 scope 都勾选最保险)。 - 函数代码包为
.tar.gz(含入口文件与依赖清单,如package.json);Node 侧InputFile必须从 SDK 的file子路径导入(主模块不导出)。
使用骨架
- 查能力:创建 / 修改前先查目标实例实际开放的语言与规格——
functions.listRuntimes()与functions.listSpecifications()的交集才是可提交值;SDK 枚举只是候选,不承诺实例已开放。 - 创建函数:
functions.create({ functionId, name, runtime, execute?, events?, schedule?, timeout?, enabled?, logging?, entrypoint?, commands?, scopes?, runtimeSpecification?, runtimeReplicas?, runtimeKeepAliveMode?, ... })。 - 部署:
functions.createDeployment({ functionId, code: InputFile.fromPath('code.tar.gz', 'code.tar.gz'), activate: true, entrypoint, commands });状态流转waiting → processing → building → ready(failed/canceled为异常路径),自动化应在取消或长时间等待后重新读取 Deployment 并结合构建日志判断,不要只信一次 API 响应。 - 调用:
- Client / Server SDK:
functions.createExecution({ functionId, body, async, path?, method?, headers?, scheduledAt? })。 - 同步(
async: false)最长等 30 秒(客户端等待),函数本身超时由timeout控制(上限 900 秒);异步立即返回 execution ID,用getExecution轮询;scheduledAt支持未来定时(ISO 8601,分钟精度)。 - HTTP 直访函数 URL(需 execute 权限包含相应来源)。
- Client / Server SDK:
- 函数内再调 Agentbase:动态 API Key(
req.headers['x-appwrite-key'],权限 = 函数scopes参数,管理员视角)或调用者 JWT(x-appwrite-user-jwt,受行级权限约束);Client的 endpoint 用运行时注入的APPWRITE_FUNCTION_API_ENDPOINT(不是自己拼外部域名,自托管沙箱内 DNS 解析不了)。 - 事件与定时:
events数组订阅平台事件(如tablesdb.*.tables.*.rows.*.create、users.*.create);schedule填 Cron 表达式。 - 变量:
createVariable/listVariables/updateVariable/deleteVariable(secret: true加密存储,运行时经process.env读取)。 - 切换版本:
updateFunctionDeployment({ functionId, deploymentId })切换活跃部署。
关键参数与返回
多语言 / 多规格 / 多副本
| 配置 | 取值 | 说明 |
|---|---|---|
runtime | 如 node-22、python-3.9、go-1.23(以 listRuntimes() 为准) | 对应 SDK Runtime 枚举 |
runtimeSpecification | 如 s-0.5vcpu-1gb、s-1vcpu-2gb、s-2vcpu-4gb、s-4vcpu-8gb、s-8vcpu-16gb | 直接传 slug 字符串,必须出现在 listSpecifications() 已启用列表;Node SDK 无该枚举 |
runtimeReplicas | 1 / 2 / 3 / 5 / 10,默认 1 | 可复用运行时副本期望值 |
runtimeKeepAliveMode | disabled / always / schedule | warm 策略;schedule 需 runtimeKeepAliveStart/End(HH:mm)+ IANA runtimeKeepAliveTimezone |
warm 配置是 Function 级期望,不等于环境公共 warm pool 库存;公共池核查(warmPoolReplicas、库存 ready/available、createOnNoStock)属运维侧,SDK 不提供查询。
两套独立权限
| 配置 | 控制什么 | 典型值 |
|---|---|---|
execute | 谁可以触发(Client SDK / HTTP) | ['users']、['any']、['team:xxx'] |
scopes | 函数运行时动态 API Key 能访问的资源 | 按函数内实际调用最小化,如 databases.read/write、tables.read/write、rows.read/write、users.read |
与「部署脚本用的 API Key scopes」是两回事,不要互相顶替。
Execution 返回
$id、functionId、deploymentId、trigger(http/schedule/event)、status(waiting/processing/completed/failed/scheduled)、responseStatusCode、responseBody、duration、logs/errors(需 API Key 才可见,Client SDK 通常为空)。
错误与边界
- 触发执行报缺 scope:
createExecution要的是execution.write,不是functions.write。 - 同步执行 408:负载均衡 30 秒超时 + 冷启动;改异步 + 轮询。
- 自托管 DNS 失败(
curl error 6):函数内用了外部 URL 初始化 Client;改用APPWRITE_FUNCTION_API_ENDPOINT。 - 2.6.0 安全默认值(升级注意):
- Function / Site 受限身份运行:用户安装 / 构建命令不满足受限身份安全条件时直接失败,不回退为高权限执行。
- Function API Key 不再接受 query string 传递:用受保护 header(
x-appwrite-key)或平台运行时注入路径,避免 URL、日志、代理泄露。
- 修改
scopes/execute不需要重新部署代码,下一次createExecution起生效。 - 部署构建超时(
_APP_COMPUTE_BUILD_TIMEOUT,默认 900 秒)同时是构建期动态 API Key 的有效期。 - 构建失败优先看 Console 构建日志里的
commands与entrypoint。
SDK 类别差异
- Client SDK(Web):
createExecution触发(需 execute 权限,否则 403)、执行记录查询;看不到日志。 - Client SDK(Web)专项(2.9.0):Web SDK 直访执行路径查询端点(
/execution-paths*)返回 403general_resource_blocked——服务端按X-AppBase-SDK/X-SDK-Name=web/X-SDK-Platform=client请求头识别客户端面并拦截,路径查询仅限 Server SDK。 - Server SDK:全管理面(创建 / 部署 / 变量 / 触发 / 记录);Node
InputFile从file子路径导入。 - Console SDK:函数的站点级兄弟能力(Sites 部署、执行计划)同形管理,函数本体管理一般走 Server SDK。
- 差异入口:client-sdk/web.md、
server-sdk/nodejs.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
查能力与创建函数
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Functions } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // functions.write 最小 scope
const functions = new Functions(client);
const runtimes = await functions.listRuntimes(); // 实例实际开放的运行时
const specs = await functions.listSpecifications(); // 实例实际开放的构建/运行规格
// 两者的交集才是可提交值;SDK 枚举只是候选
const fn = await functions.create({
functionId: 'send-mailer',
name: '发送邮件',
runtime: 'node-22', // 以 listRuntimes() 实际返回为准
execute: ['users'], // 谁可以触发;默认不授予任何角色
entrypoint: 'src/main.ts',
commands: 'npm install',
scopes: ['users.read'], // 函数内动态 API Key 的权限,按需最小化
});import io.agentbase.services.Functions;
Functions functions = new Functions(client); // client 初始化见 server-sdk/java.md
functions.listRuntimes(); // 实例实际开放的运行时
functions.listSpecifications(); // 实例实际开放的构建/运行规格;两者交集才是可提交值
// functions.create(functionId, name, runtime, execute, events, schedule, timeout, ...,
// entrypoint, commands, scopes, ...):位置参数、可空位传 null;全签名见 Functions.javafrom agentbase.services.functions import Functions # 模块路径同 services.<功能> 约定
functions = Functions(client)
functions.list_runtimes() # 实例实际开放的运行时
functions.list_specifications() # 实例实际开放的构建/运行规格;两者交集才是可提交值
functions.create(
function_id='send-mailer', name='发送邮件', runtime='node-22',
execute=['users'], # 谁可以触发;默认不授予任何角色
entrypoint='src/main.ts', commands='npm install',
scopes=['users.read']) # 函数内动态 API Key 的权限,按需最小化functions := agentbase.NewFunctions(cl) // facade 构造器;cl 为已装载 API Key 的 Client
_, _ = functions.ListRuntimes() // 实例实际开放的运行时
_, _ = functions.ListSpecifications() // 实例实际开放的构建/运行规格;两者交集才是可提交值
fn, err := functions.Create("send-mailer", "发送邮件", "node-22",
functions.WithCreateExecute([]string{"users"}), // 谁可以触发;默认不授予任何角色
functions.WithCreateEntrypoint("src/main.ts"),
functions.WithCreateCommands("npm install"),
functions.WithCreateScopes([]string{"users.read"})) // 函数内动态 API Key 的权限
_ = fncurl -sS -X POST "$APPBASE_ENDPOINT/functions" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"functionId":"send-mailer","name":"发送邮件","runtime":"node-22","execute":["users"],"entrypoint":"src/main.ts","commands":"npm install","scopes":["users.read"]}'
# 返回 201;可提交 runtime 全量以 GET /functions/runtimes 为准部署代码包
createDeployment 上传 .tar.gz 代码包(multipart/form-data),构建异步进行(waiting → processing → building → ready),立即返回处于构建状态的部署记录。代码包上传仅 Node 与 REST 两面提供,Java / Python / Go 省略该页签。
- Node.js(Server)
- REST(curl)
import { Functions, InputFile } from 'agentbase-node-sdk';
const dep = await functions.createDeployment({
functionId: 'send-mailer',
code: InputFile.fromPath('code.tar.gz', 'code.tar.gz'),
activate: true,
entrypoint: 'src/main.ts',
commands: 'npm install',
});
// 取消或长时间等待后应重新读取部署记录并结合构建日志判断,不要只信一次 API 响应curl -sS -X POST "$APPBASE_ENDPOINT/functions/send-mailer/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-F "code=@./code.tar.gz" \
-F "activate=true" \
-F "entrypoint=src/main.ts" \
-F "commands=npm install"
# 返回 202(构建中);GET /functions/{functionId}/deployments/{deploymentId} 轮询状态触发执行与轮询
同步(async: false)客户端最长等 30 秒;异步立即返回 execution ID,用 getExecution 轮询;scheduledAt 支持未来定时(ISO 8601,分钟精度);也可经 HTTP 直访函数 URL 触发(需 execute 权限包含相应来源)。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const sync = await functions.createExecution({
functionId: 'send-mailer',
body: JSON.stringify({ to: 'a@b.c' }),
async: false, // 同步受约 30s 上限;长任务用 true + 轮询
path: '/',
method: 'POST',
headers: { 'X-Custom-Header': 'value' },
});
const bg = await functions.createExecution({ functionId: 'send-mailer', body: '', async: true });
const done = await functions.getExecution({ functionId: 'send-mailer', executionId: bg.$id }); // 轮询至 completed / failedimport { Functions } from 'agentbase-web-sdk'; // 前提:用户已登录
const functions = new Functions(client);
const execution = await functions.createExecution({
functionId: 'send-mailer',
body: JSON.stringify({ to: 'a@b.c' }),
async: false, // 需函数 execute 权限包含用户角色,否则 403;看不到日志
});import io.agentbase.models.Execution;
import io.agentbase.enums.ExecutionMethod;
Execution sync = functions.createExecution("send-mailer",
"{\"to\":\"a@b.c\"}", false, "/", ExecutionMethod.POST, null, null);
// 异步执行后用 functions.getExecution(functionId, executionId) 轮询sync = functions.create_execution(
function_id='send-mailer',
body='{"to":"a@b.c"}', # body 传 JSON 字符串
path='/', method='POST',
headers={'X-Custom-Header': 'value'},
**{'async': False}) # async 为 Python 保留字,以关键字解包传入;同步受约 30s 上限
bg = functions.create_execution(function_id='send-mailer', **{'async': True})
done = functions.get_execution(function_id='send-mailer', execution_id=bg.id) # 轮询至 completed / failedexec, err := functions.CreateExecution("send-mailer",
functions.WithCreateExecutionBody(`{"to":"a@b.c"}`),
functions.WithCreateExecutionAsync(false), // 同步受约 30s 上限;长任务用 true + 轮询
functions.WithCreateExecutionPath("/"),
functions.WithCreateExecutionMethod("POST"))
bg, err := functions.CreateExecution("send-mailer",
functions.WithCreateExecutionAsync(true))
done, err := functions.GetExecution("send-mailer", bg.Id) // 轮询至 completed / failed
_, _ = exec, donecurl -sS -X POST "$APPBASE_ENDPOINT/functions/send-mailer/executions" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"body":"{\"to\":\"a@b.c\"}","async":false,"path":"/","method":"POST","headers":{"X-Custom-Header":"value"}}'
# 返回 201;async=true 后用 GET /functions/{functionId}/executions/{executionId} 轮询
# scheduledAt 支持未来定时(ISO 8601,分钟精度)执行路径查询(2.9.0)
按请求路径回查执行记录:listExecutionPaths 列出已产生执行记录的去重请求路径(字符串升序、分页);listExecutionsByPath 按完整路径精确匹配(≤2048 字符,非前缀 / 非模糊)分页查询该路径下的执行。两者都要求 execution.read。
- Node.js(Server)
- REST(curl)
const paths = await functions.listExecutionPaths({ functionId: 'send-mailer' }); // { paths, total }
const onPath = await functions.listExecutionsByPath({
functionId: 'send-mailer',
path: '/webhook', // 完整路径精确匹配
}); // { executions, total }curl -sS "$APPBASE_ENDPOINT/functions/send-mailer/execution-paths" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS "$APPBASE_ENDPOINT/functions/send-mailer/execution-paths/executions?path=/webhook" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# path 为完整路径精确匹配(≤2048 字符)函数内再调 Agentbase
这是函数代码内部的能力面,不是管理 API 调用——本卡仅 Node(函数运行时)页签,其他语言运行时与 REST 无对应页签。Client 的 endpoint 用运行时注入的 APPWRITE_FUNCTION_API_ENDPOINT(自托管沙箱内解析不了外部域名);凭据二选一:动态 API Key(权限 = 函数 scopes 参数,管理员视角)或调用者 JWT(受行级权限约束)。
- Node.js(Server)
// 函数代码内部(Node 运行时)
import { Client } from 'agentbase-node-sdk';
export default async ({ req, res }) => {
// 方式一:动态 API Key(权限 = 函数 scopes 参数)
const admin = new Client()
.setEndpoint(process.env.APPWRITE_FUNCTION_API_ENDPOINT!) // 运行时注入,始终优先
.setProject(process.env.APPWRITE_FUNCTION_PROJECT_ID!)
.setKey(req.headers['x-appwrite-key']!);
// 方式二:调用者 JWT(SDK 触发时存在,受行级权限约束)
const jwt = req.headers['x-appwrite-user-jwt'];
if (jwt) {
const asUser = new Client()
.setEndpoint(process.env.APPWRITE_FUNCTION_API_ENDPOINT!)
.setProject(process.env.APPWRITE_FUNCTION_PROJECT_ID!)
.setJWT(jwt);
}
return res.json({ ok: true });
};事件与定时
events 订阅平台事件(如 users.*.create、tablesdb.*.tables.*.rows.*.create),schedule 填 CRON 表达式;两者也可在创建函数时一并传入。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await functions.update({
functionId: 'send-mailer',
events: ['users.*.create', 'tablesdb.*.tables.*.rows.*.create'],
schedule: '0 8 * * *',
});functions.update("send-mailer",
List.of("users.*.create", "tablesdb.*.tables.*.rows.*.create"),
"0 8 * * *"); // events / schedule;未提供的字段保留现值functions.update(function_id='send-mailer',
events=['users.*.create', 'tablesdb.*.tables.*.rows.*.create'],
schedule='0 8 * * *') # 未提供的字段保留现值_, err = functions.Update("send-mailer",
functions.WithUpdateEvents([]string{"users.*.create", "tablesdb.*.tables.*.rows.*.create"}),
functions.WithUpdateSchedule("0 8 * * *")) // 未提供的字段保留现值curl -sS -X PUT "$APPBASE_ENDPOINT/functions/send-mailer" -H 'Content-Type: application/json' -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" -d '{"events":["users.*.create","tablesdb.*.tables.*.rows.*.create"],"schedule":"0 8 * * *"}'
# 未提供的字段保留现值环境变量
构建与运行时以环境变量形式注入函数进程(函数内经 process.env 读取);secret: true 机密变量可更新/删除但读不回明文;修改后需重新部署(或重新激活部署)才对后续执行生效。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await functions.createVariable({
functionId: 'send-mailer',
key: 'DATABASE_URL',
value: 'postgres://...',
secret: true, // true = 加密存储,不可回读
});
const vars = await functions.listVariables({ functionId: 'send-mailer' });
await functions.updateVariable({
functionId: 'send-mailer',
variableId: '<variableId>',
key: 'DATABASE_URL',
value: 'postgres://new',
});
await functions.deleteVariable({ functionId: 'send-mailer', variableId: '<variableId>' });functions.createVariable("send-mailer", "DATABASE_URL",
"postgres://...", true); // secret=true 加密存储,不可回读
functions.listVariables("send-mailer");
functions.updateVariable("send-mailer", "<variableId>",
"DATABASE_URL", "postgres://new"); // key 必填
functions.deleteVariable("send-mailer", "<variableId>");functions.create_variable(function_id='send-mailer', key='DATABASE_URL',
value='postgres://...', secret=True) # True = 加密存储,不可回读
functions.list_variables(function_id='send-mailer')
functions.update_variable(function_id='send-mailer', variable_id='<variable_id>',
key='DATABASE_URL', value='postgres://new') # key 必填
functions.delete_variable(function_id='send-mailer', variable_id='<variable_id>')_, err = functions.CreateVariable("send-mailer", "DATABASE_URL",
functions.WithCreateVariableValue("postgres://..."),
functions.WithCreateVariableSecret(true)) // true = 加密存储,不可回读
_, err = functions.ListVariables("send-mailer")
_, err = functions.UpdateVariable("send-mailer", "<variableId>",
functions.WithUpdateVariableKey("DATABASE_URL"),
functions.WithUpdateVariableValue("postgres://new")) // key 必填
_, err = functions.DeleteVariable("send-mailer", "<variableId>")curl -sS -X POST "$APPBASE_ENDPOINT/functions/send-mailer/variables" -H 'Content-Type: application/json' -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" -d '{"key":"DATABASE_URL","value":"postgres://...","secret":true}'
# 返回 201;列表 GET /functions/{functionId}/variables(机密变量值掩码)
# 更新 PUT、删除 DELETE 走 /functions/{functionId}/variables/{variableId}(更新时 key 必填)切换活跃部署
updateFunctionDeployment 把激活部署指针切到既有部署,此后该函数的访问与执行都使用新激活部署的代码。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await functions.updateFunctionDeployment({
functionId: 'send-mailer',
deploymentId: '<deploymentId>',
});functions.updateFunctionDeployment("send-mailer", "<deploymentId>"); // 切换激活部署指针functions.update_function_deployment(function_id='send-mailer',
deployment_id='<deployment_id>') # 切换激活部署指针_, err = functions.UpdateFunctionDeployment("send-mailer",
functions.WithUpdateFunctionDeploymentDeploymentId("<deploymentId>")) // 切换激活部署指针curl -sS -X PATCH "$APPBASE_ENDPOINT/functions/send-mailer/deployment" -H 'Content-Type: application/json' -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" -d '{"deploymentId":"<deploymentId>"}'
# 路径是单数 deployment(切换激活),与列部署的 deployments 区分示例指引
- 各语言写法集中在语言树
examples/;v5 函数入口(context 对象)、注入 header / 环境变量清单、事件与 VCS 部署变量见skills/ob-agentbase/references/functions.md。
事实源
skills/ob-agentbase/references/functions.mdskills/ob-agentbase/references/client-sdk-complex-permissions.md(Function 代理授权)skills/ob-agentbase/references/release-2.6.0.md(受限身份与 Function API Key 传递规则)- appbase v2.9.0(tag v2.9.0,peeled
ebae9540…) - agentbase-sdks v2.9.0 specs(
functionsservice:listExecutionPaths/listExecutionsByPath,runtimeSpecification/runtimeReplicas/runtimeKeepAlive*参数)