AgentbaseDocs
文档目录

函数

这是什么 / 何时用

服务端无服务器函数:响应 HTTP / SDK 调用 / 平台事件 / 定时任务,运行在隔离沙箱(托管环境经 ACS Agent Sandbox,本地 Docker 基于 OpenRuntimes)。何时用:后端逻辑代理(如复杂授权,见 permissions.md)、事件驱动处理、定时任务、轻量 API。

前置

使用骨架

关键参数与返回

多语言 / 多规格 / 多副本

配置取值说明
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 无该枚举
runtimeReplicas1 / 2 / 3 / 5 / 10,默认 1可复用运行时副本期望值
runtimeKeepAliveModedisabled / always / schedulewarm 策略;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 通常为空)。

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

查能力与创建函数

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 的权限,按需最小化
});

部署代码包

createDeployment 上传 .tar.gz 代码包(multipart/form-data),构建异步进行(waiting → processing → building → ready),立即返回处于构建状态的部署记录。代码包上传仅 Node 与 REST 两面提供,Java / Python / Go 省略该页签。

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 响应

触发执行与轮询

同步(async: false)客户端最长等 30 秒;异步立即返回 execution ID,用 getExecution 轮询;scheduledAt 支持未来定时(ISO 8601,分钟精度);也可经 HTTP 直访函数 URL 触发(需 execute 权限包含相应来源)。

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 / failed

执行路径查询(2.9.0)

按请求路径回查执行记录:listExecutionPaths 列出已产生执行记录的去重请求路径(字符串升序、分页);listExecutionsByPath 按完整路径精确匹配(≤2048 字符,非前缀 / 非模糊)分页查询该路径下的执行。两者都要求 execution.read。

const paths = await functions.listExecutionPaths({ functionId: 'send-mailer' });   // { paths, total }
const onPath = await functions.listExecutionsByPath({
    functionId: 'send-mailer',
    path: '/webhook',          // 完整路径精确匹配
});                            // { executions, total }

函数内再调 Agentbase

这是函数代码内部的能力面,不是管理 API 调用——本卡仅 Node(函数运行时)页签,其他语言运行时与 REST 无对应页签。Client 的 endpoint 用运行时注入的 APPWRITE_FUNCTION_API_ENDPOINT(自托管沙箱内解析不了外部域名);凭据二选一:动态 API Key(权限 = 函数 scopes 参数,管理员视角)或调用者 JWT(受行级权限约束)。

// 函数代码内部(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 表达式;两者也可在创建函数时一并传入。

await functions.update({
    functionId: 'send-mailer',
    events: ['users.*.create', 'tablesdb.*.tables.*.rows.*.create'],
    schedule: '0 8 * * *',
});

环境变量

构建与运行时以环境变量形式注入函数进程(函数内经 process.env 读取);secret: true 机密变量可更新/删除但读不回明文;修改后需重新部署(或重新激活部署)才对后续执行生效。

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>' });

切换活跃部署

updateFunctionDeployment 把激活部署指针切到既有部署,此后该函数的访问与执行都使用新激活部署的代码。

await functions.updateFunctionDeployment({
    functionId: 'send-mailer',
    deploymentId: '<deploymentId>',
});

示例指引

事实源