函数 API
函数全生命周期接口:创建多语言函数、代码/模板/VCS 部署、构建与运行状态、同步/异步/定时执行、执行记录、函数变量、运行规格与副本。站点(Sites)的对应接口形态同构,见 sites。
服务与资源边界
函数 API(/v1/functions/*)提供项目级 Serverless 计算引擎的管理与执行接口:支持多语言运行时(Node.js / Python / Go / Java / PHP / Dart / .NET 等)、多种代码来源(multipart/form-data 压缩包上传、模板克隆、Git VCS 仓库分支联动)、多规格容器与热保活副本(Warm Runtime)、函数级专属环境变量、事件触发与 Cron 定时调度,以及同步/异步函数执行与按路径(execution-paths)聚合检索。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/functions。 - 资源:
function({functionId})、deployment(部署包,{deploymentId})、execution(执行记录,{executionId})、variable({variableId})。 - 顶层枚举端点:
/functions/runtimes(可用运行时)、/functions/specifications(构建/运行规格)、/functions/execution-plans(执行计划)。
认证与权限
认证与请求头约定见 通用约定。本域 scope:functions.read / functions.write(函数、部署、变量、规格)、execution.read / execution.write(执行与执行记录)、public(运行时列表)。
安全要点:为每次执行自动生成的 API Key 不接受 query string 传递——执行上下文中的项目凭证只能经请求头注入;函数 scopes 数组决定该执行级 Key 的能力上限。
端点总览
Functions 模块共提供 30 个端点,分为:函数本体 CRUD 与激活部署切换(6 个)、部署包构建与生命周期管理(9 个)、函数同步/异步触发与执行记录/请求路径检索(6 个)、运行时副本状态与函数变量管理(6 个)以及全局可用运行时/规格/执行计划枚举(3 个)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /functions | 列出函数 |
POST /functions | 创建函数 |
GET /functions/{functionId} | 获取函数 |
PUT /functions/{functionId} | 更新函数配置 |
DELETE /functions/{functionId} | 删除函数 |
PATCH /functions/{functionId}/deployment | 切换激活部署 |
GET /functions/{functionId}/deployments | 列出部署 |
POST /functions/{functionId}/deployments | 上传代码创建部署 |
POST /functions/{functionId}/deployments/duplicate | 复制既有部署 |
POST /functions/{functionId}/deployments/template | 从模板创建部署 |
POST /functions/{functionId}/deployments/vcs | 从 VCS 分支/提交创建部署 |
GET /functions/{functionId}/deployments/{deploymentId} | 获取部署 |
GET /functions/{functionId}/deployments/{deploymentId}/download | 下载部署产物 |
PATCH /functions/{functionId}/deployments/{deploymentId}/status | 手动标记部署状态 |
DELETE /functions/{functionId}/deployments/{deploymentId} | 删除部署 |
POST /functions/{functionId}/executions | 执行函数 |
GET /functions/{functionId}/executions | 列出执行记录 |
GET /functions/{functionId}/executions/{executionId} | 获取执行记录 |
GET /functions/{functionId}/execution-paths | 分页列出去重请求路径(2.10.0 起 +path / pathMatch / method 过滤) |
GET /functions/{functionId}/execution-paths/executions | 按路径查询执行记录(path 必填;2.10.0 起 +pathMatch / method) |
DELETE /functions/{functionId}/executions/{executionId} | 删除执行记录 |
GET /functions/{functionId}/runtime-status | 运行时状态(副本/保活) |
GET /functions/{functionId}/variables | 列出函数变量 |
POST /functions/{functionId}/variables | 创建变量 |
GET /functions/{functionId}/variables/{variableId} | 获取变量 |
PUT /functions/{functionId}/variables/{variableId} | 更新变量 |
DELETE /functions/{functionId}/variables/{variableId} | 删除变量 |
GET /functions/runtimes | 列出可用运行时(public) |
GET /functions/specifications | 列出构建/运行规格 |
GET /functions/execution-plans | 列出执行计划 |
端点详解
- **同步与异步执行(
async参数)**:调用POST /v1/functions/{functionId}/executions时,async=false(默认)阻塞等待函数返回完整responseBody、responseStatusCode与logs;async=true立即返回202 Accepted与status: "waiting"的execution对象,由后台队列调度执行。 - 动态注入执行级临时密钥:每次执行时平台按函数配置的
scopes数组动态签发短时APPWRITE_FUNCTION_API_KEY注入容器环境,函数内部通过请求头回访当前项目资源。
请求与响应
以下按端点逐个给出输入/输出规格、可复制的 curl 调用示例与响应示例。路径前缀 /v1;请求头 X-Appwrite-Project: <YOUR_PROJECT_ID> 与 X-Appwrite-Key: <YOUR_API_KEY> 对全部端点一致,示例中不再逐条解释。
函数 CRUD
GET /v1/functions
分页列出项目内全部函数,支持按名称、运行时、启用状态等属性过滤与关键词搜索(scope functions.read。SDK:Functions.list。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、enabled、runtime、deploymentId、schedule、scheduleNext、schedulePrevious、timeout、entrypoint、commands、installationId。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 functionList:total(匹配总数,total=false 时不计算)+ functions[](当前页数据)。
元素模型 function 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 函数 ID。 |
$createdAt | string | 函数创建时间(ISO 8601)。 |
$updatedAt | string | 函数更新时间(ISO 8601)。 |
execute | string[] | 可执行此函数的角色数组。 |
name | string | 函数名称。 |
enabled | boolean | 函数是否启用。 |
live | boolean | 函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。 |
logging | boolean | 关闭后执行记录不包含日志与错误,执行略快。 |
runtime | string | 函数构建与运行使用的运行时。 |
deploymentId | string | 当前激活的部署 ID。 |
latestDeploymentId | string | 最新(不一定激活)部署 ID。 |
latestDeploymentStatus | string | 最新部署的状态:waiting / processing / building / ready / failed。 |
scopes | string[] | 执行级自动生成 API Key 允许的 scope 列表。 |
events | string[] | 触发事件列表。 |
schedule | string | CRON 格式的定时调度表达式。 |
timeout | integer | 最大执行时长(秒)。 |
调用示例:
curl -G "https://<your-endpoint>/v1/functions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=hello"响应示例:
{
"total": 5,
"functions": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}
]
}POST /v1/functions
创建函数:定义运行时、入口与构建命令、触发事件、CRON 调度、构建/运行规格以及执行级 API Key 的 scope(scope functions.write。SDK:Functions.create。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | body | string | 是 | — | 函数 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。 |
name | body | string | 是 | — | 函数名称。最长 128 字符。 |
runtime | body | string | 是 | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 ……(全量以 GET /functions/runtimes 为准) | 执行运行时。 |
execute | body | string[] | 否 | — | 拥有执行权限的角色字符串数组。默认不授予任何角色。最多 100 个角色,每个最长 64 字符。 |
events | body | string[] | 否 | — | 触发事件列表。最多 100 个。 |
schedule | body | string | 否 | — | CRON 格式的定时调度表达式。 |
timeout | body | integer | 否 | — | 最大执行时长(秒)。 |
enabled | body | boolean | 否 | — | 是否启用函数。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。 |
logging | body | boolean | 否 | — | 关闭后执行记录不包含日志与错误,执行略快。 |
entrypoint | body | string | 否 | — | 入口文件。路径相对于 providerRootDirectory。 |
commands | body | string | 否 | — | 构建命令。 |
scopes | body | string[] | 否 | — | 每次执行自动生成的 API Key 允许的 scope 列表。最多 100 个。 |
installationId | body | string | 否 | — | 用于 VCS 部署的 AppBase 安装 ID。 |
providerRepositoryId | body | string | 否 | — | 函数关联的 VCS 仓库 ID。 |
providerBranch | body | string | 否 | — | 函数关联仓库的生产分支。 |
providerSilentMode | body | boolean | 否 | — | 函数关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。 |
providerRootDirectory | body | string | 否 | — | 函数代码在关联仓库中的路径。 |
buildSpecification | body | string | 否 | — | 构建规格固定为平台函数构建档位。 |
runtimeSpecification | body | string | 否 | — | 函数执行使用的运行规格。 |
runtimeReplicas | body | integer | 否 | — | 函数执行的可复用常驻运行时副本数。允许 1 / 2 / 3 / 5 / 10。 |
runtimeKeepAliveMode | body | string | 否 | disabled / always / schedule | 运行时保活模式:disabled / always / schedule。 |
runtimeKeepAliveStart | body | string | 否 | 可为 null | 每日保活窗口开始时间(HH:mm)。schedule 模式下必填。 |
runtimeKeepAliveEnd | body | string | 否 | 可为 null | 每日保活窗口结束时间(HH:mm)。schedule 模式下必填。 |
runtimeKeepAliveTimezone | body | string | 否 | africa/abidjan / africa/accra / africa/addis_ababa / africa/algiers / africa/asmara / africa/bamako / africa/bangui / africa/banjul ……(共 420 个) | 评估保活窗口使用的 IANA 时区名。 |
buildExecutionPlan | body | string | 否 | 可为 null | 函数部署构建使用的执行计划。省略使用遗留默认值。 |
runtimeExecutionPlan | body | string | 否 | 可为 null | 函数执行使用的执行计划。省略使用遗留默认值。 |
deploymentRetention | body | integer | 否 | — | 非激活部署删除前的保留天数。0 表示全部保留。 |
输出:201,模型 function,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 函数 ID。 |
$createdAt | string | 函数创建时间(ISO 8601)。 |
$updatedAt | string | 函数更新时间(ISO 8601)。 |
execute | string[] | 可执行此函数的角色数组。 |
name | string | 函数名称。 |
enabled | boolean | 函数是否启用。 |
live | boolean | 函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。 |
logging | boolean | 关闭后执行记录不包含日志与错误,执行略快。 |
runtime | string | 函数构建与运行使用的运行时。 |
deploymentRetention | integer | 非激活部署保留天数,到期后自动删除。 |
deploymentId | string | 当前激活的部署 ID。 |
deploymentCreatedAt | string | 激活部署的创建时间(ISO 8601)。 |
latestDeploymentId | string | 最新(不一定激活)部署 ID。 |
latestDeploymentCreatedAt | string | 最新部署的创建时间(ISO 8601)。 |
latestDeploymentStatus | string | 最新部署的状态:waiting / processing / building / ready / failed。 |
scopes | string[] | 执行级自动生成 API Key 允许的 scope 列表。 |
vars | variable[] | 函数变量列表。 |
events | string[] | 触发事件列表。 |
schedule | string | CRON 格式的定时调度表达式。 |
timeout | integer | 最大执行时长(秒)。 |
entrypoint | string | 部署代码的入口文件。 |
commands | string | 部署的构建命令。 |
version | string | 函数使用的 Open Runtimes 版本。 |
installationId | string | 函数关联的 VCS(版本控制系统)安装 ID。 |
providerRepositoryId | string | VCS(版本控制系统)仓库 ID。 |
providerBranch | string | VCS(版本控制系统)分支名。 |
providerRootDirectory | string | 函数代码在 VCS 仓库中的路径。 |
providerSilentMode | boolean | VCS 连接是否为静默模式。静默模式下不会在仓库的 PR / MR 上发表评论。 |
buildSpecification | string | 构建使用的固定机器规格(CPU/内存档位)。 |
runtimeSpecification | string | 运行使用的机器规格(CPU/内存档位)。 |
runtimeReplicas | integer | 函数执行的可复用常驻运行时副本数。 |
runtimeKeepAliveMode | string | 运行时保活模式:disabled / always / schedule。 |
runtimeKeepAliveStart | string | 每日保活窗口开始时间(HH:mm)。 |
runtimeKeepAliveEnd | string | 每日保活窗口结束时间(HH:mm)。 |
runtimeKeepAliveTimezone | string | 评估保活窗口使用的 IANA 时区名。 |
buildExecutionPlan | string | 部署构建使用的执行计划。 |
runtimeExecutionPlan | string | 函数执行使用的执行计划。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"functionId": "hello-world",
"name": "My Function",
"runtime": "node-22",
"execute": [
"users"
],
"events": [
"users.*.create"
],
"schedule": "0 8 * * *",
"timeout": 15,
"scopes": [
"databases.read",
"documents.read",
"users.read"
],
"entrypoint": "src/main.js",
"commands": "npm install"
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}GET /v1/functions/{functionId}
按 ID 读取单个函数的完整配置,含激活/最新部署指针与 live 标记(scope functions.read。SDK:Functions.get。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
输出:200,模型 function(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 函数 ID。 |
$createdAt | string | 函数创建时间(ISO 8601)。 |
$updatedAt | string | 函数更新时间(ISO 8601)。 |
execute | string[] | 可执行此函数的角色数组。 |
name | string | 函数名称。 |
enabled | boolean | 函数是否启用。 |
live | boolean | 函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。 |
logging | boolean | 关闭后执行记录不包含日志与错误,执行略快。 |
runtime | string | 函数构建与运行使用的运行时。 |
deploymentId | string | 当前激活的部署 ID。 |
latestDeploymentId | string | 最新(不一定激活)部署 ID。 |
latestDeploymentStatus | string | 最新部署的状态:waiting / processing / building / ready / failed。 |
scopes | string[] | 执行级自动生成 API Key 允许的 scope 列表。 |
events | string[] | 触发事件列表。 |
schedule | string | CRON 格式的定时调度表达式。 |
timeout | integer | 最大执行时长(秒)。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}PUT /v1/functions/{functionId}
更新函数配置:未提供的字段保留现值;修改需重新部署的配置后函数 live 变为 false(scope functions.write。SDK:Functions.update。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 是 | — | 函数名称。最长 128 字符。 |
runtime | body | string | 否 | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 ……(全量以 GET /functions/runtimes 为准) | 执行运行时。 |
execute | body | string[] | 否 | — | 拥有执行权限的角色字符串数组。默认不授予任何角色。最多 100 个角色,每个最长 64 字符。 |
events | body | string[] | 否 | — | 触发事件列表。最多 100 个。 |
schedule | body | string | 否 | — | CRON 格式的定时调度表达式。 |
timeout | body | integer | 否 | — | 最大执行时长(秒)。 |
enabled | body | boolean | 否 | — | 是否启用函数。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。 |
logging | body | boolean | 否 | — | 关闭后执行记录不包含日志与错误,执行略快。 |
entrypoint | body | string | 否 | — | 入口文件。路径相对于 providerRootDirectory。 |
commands | body | string | 否 | — | 构建命令。 |
scopes | body | string[] | 否 | — | 每次执行自动生成的 API Key 允许的 scope 列表。最多 100 个。 |
installationId | body | string | 否 | — | 用于 VCS 部署的 AppBase 安装 ID。 |
providerRepositoryId | body | string | 否 | 可为 null | 函数关联的 VCS 仓库 ID。 |
providerBranch | body | string | 否 | — | 函数关联仓库的生产分支。 |
providerSilentMode | body | boolean | 否 | — | 函数关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。 |
providerRootDirectory | body | string | 否 | — | 函数代码在关联仓库中的路径。 |
buildSpecification | body | string | 否 | — | 构建规格固定为平台函数构建档位。 |
runtimeSpecification | body | string | 否 | — | 函数执行使用的运行规格。 |
runtimeReplicas | body | integer | 否 | — | 函数执行的可复用常驻运行时副本数。允许 1 / 2 / 3 / 5 / 10。 |
runtimeKeepAliveMode | body | string | 否 | disabled / always / schedule | 运行时保活模式:disabled / always / schedule。省略保持现值。 |
runtimeKeepAliveStart | body | string | 否 | 可为 null | 每日保活窗口开始时间(HH:mm)。schedule 模式下必填。省略保持现值。 |
runtimeKeepAliveEnd | body | string | 否 | 可为 null | 每日保活窗口结束时间(HH:mm)。schedule 模式下必填。省略保持现值。 |
runtimeKeepAliveTimezone | body | string | 否 | africa/abidjan / africa/accra / africa/addis_ababa / africa/algiers / africa/asmara / africa/bamako / africa/bangui / africa/banjul ……(共 420 个) | 评估保活窗口使用的 IANA 时区名。省略保持现值。 |
buildExecutionPlan | body | string | 否 | 可为 null | 函数部署构建使用的执行计划。省略保持现值。 |
runtimeExecutionPlan | body | string | 否 | 可为 null | 函数执行使用的执行计划。省略保持现值。 |
deploymentRetention | body | integer | 否 | — | 非激活部署删除前的保留天数。0 表示全部保留。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:200,模型 function(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 函数 ID。 |
$createdAt | string | 函数创建时间(ISO 8601)。 |
$updatedAt | string | 函数更新时间(ISO 8601)。 |
execute | string[] | 可执行此函数的角色数组。 |
name | string | 函数名称。 |
enabled | boolean | 函数是否启用。 |
live | boolean | 函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。 |
logging | boolean | 关闭后执行记录不包含日志与错误,执行略快。 |
runtime | string | 函数构建与运行使用的运行时。 |
deploymentId | string | 当前激活的部署 ID。 |
latestDeploymentId | string | 最新(不一定激活)部署 ID。 |
latestDeploymentStatus | string | 最新部署的状态:waiting / processing / building / ready / failed。 |
scopes | string[] | 执行级自动生成 API Key 允许的 scope 列表。 |
events | string[] | 触发事件列表。 |
schedule | string | CRON 格式的定时调度表达式。 |
timeout | integer | 最大执行时长(秒)。 |
调用示例:
curl -X PUT "https://<your-endpoint>/v1/functions/<FUNCTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "My Function",
"enabled": true,
"logging": true,
"schedule": "0 8 * * *",
"timeout": 15,
"entrypoint": "src/main.js",
"commands": "npm install",
"runtime": "node-22"
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}DELETE /v1/functions/{functionId}
按 ID 删除函数(scope functions.write。SDK:Functions.delete。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
PATCH /v1/functions/{functionId}/deployment
切换函数的激活部署:此后该函数的访问与执行都使用新激活部署的代码(scope functions.write。SDK:Functions.updateFunctionDeployment。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
deploymentId | body | string | 是 | — | 部署 ID。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:200,模型 function(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 函数 ID。 |
$createdAt | string | 函数创建时间(ISO 8601)。 |
$updatedAt | string | 函数更新时间(ISO 8601)。 |
execute | string[] | 可执行此函数的角色数组。 |
name | string | 函数名称。 |
enabled | boolean | 函数是否启用。 |
live | boolean | 函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。 |
logging | boolean | 关闭后执行记录不包含日志与错误,执行略快。 |
runtime | string | 函数构建与运行使用的运行时。 |
deploymentId | string | 当前激活的部署 ID。 |
latestDeploymentId | string | 最新(不一定激活)部署 ID。 |
latestDeploymentStatus | string | 最新部署的状态:waiting / processing / building / ready / failed。 |
scopes | string[] | 执行级自动生成 API Key 允许的 scope 列表。 |
events | string[] | 触发事件列表。 |
schedule | string | CRON 格式的定时调度表达式。 |
timeout | integer | 最大执行时长(秒)。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deploymentId": "5e5ea5c16897e"
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"execute": [
"users"
],
"name": "My Function",
"enabled": true,
"live": true,
"logging": true,
"runtime": "node-22",
"deploymentRetention": 7,
"deploymentId": "5e5ea5c16897e",
"deploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentId": "5e5ea5c16897e",
"latestDeploymentCreatedAt": "2020-10-15T06:38:00.000+00:00",
"latestDeploymentStatus": "ready",
"scopes": [
"databases.read",
"documents.read"
],
"vars": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
],
"events": [
"users.*.create"
],
"schedule": "5 4 * * *",
"timeout": 300,
"entrypoint": "index.js",
"commands": "npm install",
"version": "v2",
"installationId": "6m40at4ejk5h2u9s1hboo",
"providerRepositoryId": "appbase",
"providerBranch": "main",
"providerRootDirectory": "functions/helloWorld",
"providerSilentMode": false,
"buildSpecification": "s-1vcpu-2gb",
"runtimeSpecification": "s-1vcpu-2gb",
"runtimeReplicas": 3,
"runtimeKeepAliveMode": "schedule",
"runtimeKeepAliveStart": "08:00",
"runtimeKeepAliveEnd": "22:00",
"runtimeKeepAliveTimezone": "Asia/Shanghai",
"buildExecutionPlan": "standard-build",
"runtimeExecutionPlan": "standard-runtime"
}部署
GET /v1/functions/{functionId}/deployments
分页列出该函数的全部部署,用于构建历史与状态巡检(scope functions.read。SDK:Deployments.listDeployments。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:buildSize、sourceSize、totalSize、buildDuration、status、activate、type。最多 100 条、每条最长 4096 字符。 |
search | query | string | 否 | — | 搜索词,模糊过滤列表结果。最长 256 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
输出:200,模型 deploymentList:total(匹配总数,total=false 时不计算)+ deployments[](当前页数据)。
元素模型 deployment 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)" \
--data-urlencode "search=hello"响应示例:
{
"total": 5,
"deployments": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}
]
}POST /v1/functions/{functionId}/deployments
上传源码 gzip 包或 Java 17 预构建 JAR 创建新部署(multipart/form-data);构建异步进行,立即返回 202 与部署记录(scope functions.write;Functions SDK:createDeployment)。
输入(multipart/form-data,文件字段用 -F "code=@./code.tgz" 上传)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
entrypoint | body(表单) | string | 否 | 可为 null | 入口文件。 |
commands | body(表单) | string | 否 | 可为 null | 构建命令。 |
code | body(表单) | string | 是 | — | gzip 压缩的代码包(artifactMode=source),或可执行 JAR(artifactMode=java-jar)。使用 AppBase CLI 时传代码目录路径,CLI 会自动打包;路径须位于当前目录内。 |
artifactMode | body(表单) | string | 否 | source / java-jar(默认 source) | 上传模式(2.10.0 新增):source 为 gzip 源码包;java-jar 为 Java 17 可执行 JAR(真实入口为 manifest 的 Main-Class;Index.java 是兼容标识;JAR 上限默认 100,000,000 字节,同时受套餐部署上限约束)。 |
activate | body(表单) | boolean | 是 | — | 构建完成后是否自动激活该部署。 |
functionId | path | string | 是 | — | 函数 ID。 |
JAR 模式要求目标 Function 的运行时为 java-17.0,包内包含 manifest 指定的入口类,应用监听端口 3000 并提供 /__opr/health;不需要填写源码入口和构建命令。分片上传时各片保持相同 artifactMode。202 仅表示接收部署,需继续检查状态达到 ready、Function 当前 deploymentId 与目标一致,并验证实际 execution;activate=true 不是执行成功保证。
输出:202,模型 deployment,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
$updatedAt | string | 部署更新时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
screenshotLight | string | 浅色主题截图的文件 ID。 |
screenshotDark | string | 深色主题截图的文件 ID。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildLogs | string | 构建日志。 |
buildDuration | integer | 当前构建耗时(秒)。 |
providerRepositoryName | string | VCS 提供商仓库名。 |
providerRepositoryOwner | string | VCS 仓库属主名。 |
providerRepositoryUrl | string | VCS 仓库地址。 |
providerCommitHash | string | VCS 提交哈希。 |
providerCommitAuthorUrl | string | VCS 提交作者主页。 |
providerCommitAuthor | string | VCS 提交作者名。 |
providerCommitMessage | string | 提交信息。 |
providerCommitUrl | string | VCS 提交地址。 |
providerBranch | string | VCS 仓库分支。 |
providerBranchUrl | string | VCS 仓库分支。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-F "entrypoint=src/main.js" \
-F "commands=npm install" \
-F "code=@./code.tgz" \
-F "activate=true"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/duplicate
基于既有部署发起新构建:按函数当前配置(含修改后的入口/构建命令)重新打包,不重复上传源码(scope functions.write。SDK:Deployments.createDuplicateDeployment。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
deploymentId | body | string | 是 | — | 部署 ID。 |
buildId | body | string | 否 | — | 本次构建 ID。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:202,模型 deployment(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/duplicate" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deploymentId": "5e5ea5c16897e",
"buildId": "6aa2d1b8c2e8f"
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/template
从模板仓库创建部署:指定模板的仓库、属主、目录与引用(commit/branch/tag)(scope functions.write。SDK:Deployments.createTemplateDeployment。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
repository | body | string | 是 | — | 模板仓库名。 |
owner | body | string | 是 | — | 模板仓库属主。 |
rootDirectory | body | string | 是 | — | 函数代码在模板仓库中的路径。 |
type | body | string | 是 | commit / branch / tag | reference 的类型:commit / branch / tag。 |
reference | body | string | 是 | — | reference 的值:提交哈希、分支名或发布标签。 |
activate | body | boolean | 否 | — | 构建完成后是否自动激活该部署。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:202,模型 deployment(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/template" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"repository": "agentbase/function-templates",
"owner": "agentbase",
"rootDirectory": "hello-world",
"type": "commit",
"reference": "prod",
"activate": true
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}POST /v1/functions/{functionId}/deployments/vcs
对已关联 VCS 的函数,从其仓库的分支或提交创建部署(scope functions.write。SDK:Deployments.createVcsDeployment。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
type | body | string | 是 | branch / commit | reference 的类型:branch / commit。 |
reference | body | string | 是 | — | 创建部署的 VCS 引用:分支名或提交哈希(随 type 而定)。 |
activate | body | boolean | 否 | — | 构建完成后是否自动激活该部署。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:202,模型 deployment(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/vcs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"type": "commit",
"reference": "prod",
"activate": true
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}GET /v1/functions/{functionId}/deployments/{deploymentId}
读取单个部署详情,是轮询构建状态的标准入口(scope functions.read。SDK:Deployments.getDeployment。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
deploymentId | path | string | 是 | — | 部署 ID。 |
输出:200,模型 deployment(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}GET /v1/functions/{functionId}/deployments/{deploymentId}/download
下载部署的源码包(type=source)或构建产物(type=output),返回附件二进制流(scope functions.read。SDK:Deployments.getDeploymentDownload。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
deploymentId | path | string | 是 | — | 部署 ID。 |
type | query | string | 否 | source / output;默认 "source" | 下载内容:source(源码包)或 output(构建产物)。 |
输出:200,二进制文件流(Content-Disposition: attachment 附件下载;type=source 为源码包,type=output 为构建产物)。
调用示例:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>/download" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-o deployment.tgz \
--data-urlencode "type=source"响应示例:
_二进制流或无响应体(见输出说明)。_
PATCH /v1/functions/{functionId}/deployments/{deploymentId}/status
取消进行中或排队中的部署构建:进行中的构建被停止、标记 canceled;已完成(ready)或已失败(failed)的构建不可取消(scope functions.write。SDK:Deployments.updateDeploymentStatus。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
deploymentId | path | string | 是 | — | 部署 ID。 |
输出:200,模型 deployment(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 部署 ID。 |
$createdAt | string | 部署创建时间(ISO 8601)。 |
type | string | 部署类型。 |
artifactMode | string | 上传模式:source / java-jar(2.10.0 新增)。 |
resourceId | string | 所属资源 ID。 |
resourceType | string | 所属资源类型。 |
entrypoint | string | 执行部署代码使用的入口文件。 |
sourceSize | integer | 源码包大小(字节)。 |
buildSize | integer | 构建产物大小(字节)。 |
totalSize | integer | 总大小(源码 + 构建产物,字节)。 |
buildId | string | 当前构建 ID。 |
activate | boolean | 构建完成后是否自动激活。 |
status | string | 部署状态:waiting / processing / building / ready / canceled / failed。 |
buildDuration | integer | 当前构建耗时(秒)。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"type": "upload",
"resourceId": "hello-world",
"resourceType": "function",
"entrypoint": "index.js",
"sourceSize": 128,
"buildSize": 128,
"totalSize": 128,
"buildId": "6aa2d1b8c2e8f",
"activate": true,
"screenshotLight": "5e5ea5c16897e",
"screenshotDark": "5e5ea5c16897e",
"status": "ready",
"buildLogs": "Compiling source files...",
"buildDuration": 128,
"providerRepositoryName": "database",
"providerRepositoryOwner": "utopia",
"providerRepositoryUrl": "https://github.com/vermakhushboo/g4-node-function",
"providerCommitHash": "7c3f25d",
"providerCommitAuthorUrl": "https://github.com/vermakhushboo",
"providerCommitAuthor": "Khushboo Verma",
"providerCommitMessage": "Update index.js",
"providerCommitUrl": "https://github.com/vermakhushboo/g4-node-function/commit/60c0416257a9cbcdd96b2d370c38d8f8d150ccfb",
"providerBranch": "0.7.x",
"providerBranchUrl": "https://github.com/vermakhushboo/appwrite/tree/0.7.x"
}DELETE /v1/functions/{functionId}/deployments/{deploymentId}
删除指定部署(激活中的部署应先切换到其他部署再删除)(scope functions.write。SDK:Deployments.deleteDeployment。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
deploymentId | path | string | 是 | — | 部署 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/deployments/<DEPLOYMENT_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
执行
POST /v1/functions/{functionId}/executions
触发一次函数执行:同步等待结果、async=true 后台执行轮询记录、或 scheduledAt 定时执行(scope execution.write。SDK:Executions.createExecution。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
body | body | string | 否 | — | 执行请求体。默认空串。 |
async | body | boolean | 否 | — | 是否后台执行。默认 false。 |
path | body | string | 否 | — | 执行路径,可含查询参数。默认 /。 |
method | body | string | 否 | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | HTTP 方法。默认 POST。 |
headers | body | object | 否 | — | 执行请求头。默认为空。 |
scheduledAt | body | string | 否 | 可为 null | 定时执行时间(ISO 8601)。必须是未来时间,精度到分钟。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:201,模型 execution,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 执行记录 ID。 |
$createdAt | string | 执行记录创建时间(ISO 8601)。 |
$updatedAt | string | 执行记录更新时间(ISO 8601)。 |
$permissions | string[] | 执行角色。 |
functionId | string | 函数 ID。 |
deploymentId | string | 触发本次执行使用的部署 ID。 |
trigger | string | 触发来源:http / schedule / event。 |
status | string | 执行状态:waiting / processing / completed / failed / scheduled。 |
requestMethod | string | HTTP 请求方法。 |
requestPath | string | HTTP 请求路径(可含查询串)。 |
requestHeaders | headers[] | HTTP 请求头键值对象。仅返回白名单内的头;同步创建的执行返回全部请求头。 |
responseStatusCode | integer | HTTP 响应状态码。 |
responseBody | string | 函数返回的 HTTP 响应体。 |
responseHeaders | headers[] | HTTP 响应头键值对象。仅返回白名单内的头;同步创建的执行返回全部响应头。 |
logs | string | 函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
errors | string | 函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
duration | number | 资源(函数/站点)执行耗时(秒)。 |
scheduledAt | string | 定时执行时间。留空则立即排队执行。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"body": "{\"now\": true}",
"async": false,
"path": "/",
"method": "POST",
"headers": {
"X-Custom-Header": "value"
}
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}GET /v1/functions/{functionId}/executions
分页列出该函数的执行记录,可按状态、时长、触发时间过滤(scope execution.read。SDK:Functions.listExecutions。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
queries | query | string[] | 否 | 默认 [] | 查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:trigger、status、responseStatusCode、duration、requestMethod、requestPath、deploymentId。最多 100 条、每条最长 4096 字符。 |
total | query | boolean | 否 | 默认 true | 设为 false 时跳过总数计算,返回的 total 固定为 0。 |
path | query | string | 否 | 默认空 | 完整请求路径或正则,查询字符串参与匹配;Node Server 对象参数名为 xpath。 |
pathMatch | query | string | 否 | exact / regex,默认 exact | 正则不带 /…/ 分隔符,非法表达式被拒绝。 |
method | query | string | 否 | GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS | 与路径和 queries 条件同时生效;省略时保留所有方法。 |
Agentbase Web SDK 的执行记录列表与路径列表访问会返回 403 general_resource_blocked;请用 Console 或受控服务端身份读取,不通过修改 SDK 标识绕过限制。该列表限制不覆盖按 ID 查询单条 execution。
输出:200,模型 executionList:total(匹配总数,total=false 时不计算)+ executions[](当前页数据)。
元素模型 execution 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 执行记录 ID。 |
$createdAt | string | 执行记录创建时间(ISO 8601)。 |
functionId | string | 函数 ID。 |
deploymentId | string | 触发本次执行使用的部署 ID。 |
trigger | string | 触发来源:http / schedule / event。 |
status | string | 执行状态:waiting / processing / completed / failed / scheduled。 |
requestMethod | string | HTTP 请求方法。 |
requestPath | string | HTTP 请求路径(可含查询串)。 |
responseStatusCode | integer | HTTP 响应状态码。 |
responseBody | string | 函数返回的 HTTP 响应体。 |
logs | string | 函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
errors | string | 函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
duration | number | 资源(函数/站点)执行耗时(秒)。 |
调用示例:
curl -G "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "queries[]=limit(25)"响应示例:
{
"total": 5,
"executions": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}
]
}GET /v1/functions/{functionId}/executions/{executionId}
读取单条执行记录:async=true 或定时执行后获取结果与日志的入口(scope execution.read。SDK:Executions.getExecution。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
executionId | path | string | 是 | — | 执行记录 ID。 |
输出:200,模型 execution(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 执行记录 ID。 |
$createdAt | string | 执行记录创建时间(ISO 8601)。 |
functionId | string | 函数 ID。 |
deploymentId | string | 触发本次执行使用的部署 ID。 |
trigger | string | 触发来源:http / schedule / event。 |
status | string | 执行状态:waiting / processing / completed / failed / scheduled。 |
requestMethod | string | HTTP 请求方法。 |
requestPath | string | HTTP 请求路径(可含查询串)。 |
responseStatusCode | integer | HTTP 响应状态码。 |
responseBody | string | 函数返回的 HTTP 响应体。 |
logs | string | 函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
errors | string | 函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。 |
duration | number | 资源(函数/站点)执行耗时(秒)。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions/<EXECUTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
""
],
"functionId": "hello-world",
"deploymentId": "5e5ea5c16897e",
"trigger": "http",
"status": "completed",
"requestMethod": "POST",
"requestPath": "/articles?id=5",
"requestHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"responseStatusCode": 200,
"responseBody": "Hello from function!",
"responseHeaders": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"logs": "",
"errors": "",
"duration": 0.4,
"scheduledAt": null
}DELETE /v1/functions/{functionId}/executions/{executionId}
删除单条执行记录(仅清理记录,不影响函数)(scope execution.write。SDK:Executions.deleteExecution。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
executionId | path | string | 是 | — | 执行记录 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/executions/<EXECUTION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
GET /v1/functions/{functionId}/execution-paths
分页列出已有执行记录的去重请求路径。
scope:execution.read;Server SDK:Functions.listExecutionPaths。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
limit | query | integer | 否 | 25 | 最大返回数量。 |
offset | query | integer | 否 | 0 | 跳过的记录数。 |
total | query | boolean | 否 | true | 是否计算总数;false 时返回的 total 为 0。 |
path | query | string | 否 | — | 按请求路径过滤(2.10.0 新增);配合 pathMatch 选择精确或正则匹配。 |
pathMatch | query | string | 否 | exact / regex(默认 exact) | 路径匹配模式(2.10.0 新增)。 |
method | query | string | 否 | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | 按 HTTP 方法过滤(2.10.0 新增)。 |
输出:200,模型 executionPathList。
| 字段 | 类型 | 说明 |
|---|---|---|
total | integer | 去重请求路径总数。 |
paths | string[] | 本页去重请求路径。 |
调用示例:
curl --get "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/execution-paths" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/functions/{functionId}/execution-paths/executions
按请求路径分页查询执行记录。
scope:execution.read;Server SDK:Functions.listExecutionsByPath。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
path | query | string | 是 | — | 执行请求路径;默认精确匹配,pathMatch=regex 时为正则(2.10.0 起)。 |
queries | query | string[] | 否 | [] | SDK Query 字符串数组;最多 100 项,每项最长 4096 字符。 |
total | query | boolean | 否 | true | 是否计算总数;false 时返回的 total 为 0。 |
pathMatch | query | string | 否 | exact / regex(默认 exact) | 路径匹配模式(2.10.0 新增)。 |
method | query | string | 否 | GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD | 按 HTTP 方法过滤(2.10.0 新增)。 |
输出:200,模型 executionList。
返回 executions 执行记录数组与 total;执行记录字段见本页「执行」。
调用示例:
curl --get "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/execution-paths/executions" \
--data-urlencode "path=/webhook" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"运行时状态与枚举
GET /v1/functions/{functionId}/runtime-status
读取函数常驻运行时的安全状态摘要(healthy / attention / limited / maintenance / unknown)(scope functions.read。SDK:Functions.getRuntimeStatus。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
输出:200,模型 runtimeStatus,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 运行时状态摘要。 |
coverage | string | 状态数据覆盖范围。 |
updatedAt | string | 底层资源最近更新时间。 |
message | string | 面向用户的安全状态消息。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/runtime-status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"status": "healthy",
"coverage": "configuration-only",
"updatedAt": "2026-07-12T00:00:00.000+00:00",
"message": "All runtime replicas are healthy."
}GET /v1/functions/runtimes
列出当前实例全部可用运行时(public scope,无需 API Key 以外的授权即可读取)(scope public。SDK:Runtimes.listRuntimes。)
输入:仅路径参数,无查询与请求体。
输出:200,模型 runtimeList:total(匹配总数,total=false 时不计算)+ runtimes[](当前页数据)。
元素模型 runtime 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 运行时 ID。 |
key | string | 所属运行时键名。 |
name | string | 运行时名称。 |
version | string | 运行时版本。 |
base | string | 构建该运行时使用的基础 Docker 镜像。 |
image | string | Docker Hub 镜像名。 |
supports | string[] | 支持的 CPU 架构列表。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/runtimes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 5,
"runtimes": [
{
"$id": "66f1a2b3c4d5e6f7",
"key": "python",
"name": "Python",
"version": "3.8",
"base": "python:3.8-alpine",
"image": "appbase\\/runtime-for-python:3.8",
"logo": "python.png",
"supports": [
"amd64"
]
}
]
}GET /v1/functions/specifications
列出实例允许的构建/运行机器规格(CPU 与内存档位)(scope functions.read。SDK:Runtimes.listSpecifications。)
输入:仅路径参数,无查询与请求体。
输出:200,模型 specificationList:total(匹配总数,total=false 时不计算)+ specifications[](当前页数据)。
元素模型 specification 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
memory | integer | 内存大小(MB)。 |
cpus | number | CPU 核数。 |
enabled | boolean | 该规格是否启用。 |
slug | string | 规格标识(slug)。 |
模型 specificationList 附加字段:defaultRuntimeSpecification(string,2.10.0 新增)——平台管理员配置的新函数默认运行规格 slug;对当前套餐或算力不可用时为 null。新创建 Function 未显式指定规格时应用该默认值。
调用示例:
curl "https://<your-endpoint>/v1/functions/specifications" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 5,
"specifications": [
{
"memory": 512,
"cpus": 1,
"enabled": true,
"slug": "s-1vcpu-512mb"
}
]
}GET /v1/functions/execution-plans
列出函数构建/运行可用的执行计划(资源档位套餐),可按运行时过滤(scope functions.read。SDK:ExecutionPlans.listExecutionPlans。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
runtime | query | string | 否 | node-14.5 / node-16.0 / node-18.0 / node-19.0 / node-20.0 / node-21.0 / node-22 / node-23 ……(全量以 GET /functions/runtimes 为准) | 用于过滤执行计划的函数运行时。 |
输出:200,模型 executionPlanList:total(匹配总数,total=false 时不计算)+ executionPlans[](当前页数据)。
元素模型 executionPlan 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 稳定的执行计划 ID。 |
name | string | 执行计划展示名。 |
summary | string | 执行计划简述。 |
suitableFor | string | 该执行计划支持的资源类型。 |
recommended | boolean | 是否为推荐执行计划。 |
availability | string | 该执行计划的可用性。 |
effectiveOn | string | 所选执行计划的生效时机。 |
调用示例:
curl -G "https://<your-endpoint>/v1/functions/execution-plans" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode "runtime=node-22"响应示例:
{
"total": 5,
"executionPlans": [
{
"id": "legacy-default",
"name": "Default runtime",
"summary": "Use the verified shared runtime baseline.",
"suitableFor": "Supported Function and Site runtimes.",
"recommended": true,
"availability": "available",
"effectiveOn": "Next build or execution.",
"disabledReason": null
}
]
}函数变量
GET /v1/functions/{functionId}/variables
列出该函数的全部环境变量(机密变量的值不回显明文)(scope functions.read。SDK:Variables.listVariables。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
输出:200,模型 variableList:total(匹配总数,total=false 时不计算)+ variables[](当前页数据)。
元素模型 variable 关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 变量 ID。 |
key | string | 变量键名。 |
value | string | 变量值。 |
secret | boolean | 是否为机密变量。机密变量只能更新或删除,不能读取。 |
resourceType | string | 变量所属服务:project / function。 |
resourceId | string | 变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 5,
"variables": [
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}
]
}POST /v1/functions/{functionId}/variables
创建函数环境变量:构建与运行时以环境变量形式注入函数进程(scope functions.write。SDK:Variables.createVariable。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
key | body | string | 是 | — | 变量键名。最长 255 字符。 |
value | body | string | 是 | — | 变量值。最长 8192 字符。 |
secret | body | boolean | 否 | — | 机密变量可更新/删除,但只有函数可在构建与运行时读取。 |
functionId | path | string | 是 | — | 函数 ID。 |
输出:201,模型 variable,字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 变量 ID。 |
$createdAt | string | 变量创建时间(ISO 8601)。 |
$updatedAt | string | 变量创建时间(ISO 8601)。 |
key | string | 变量键名。 |
value | string | 变量值。 |
secret | boolean | 是否为机密变量。机密变量只能更新或删除,不能读取。 |
resourceType | string | 变量所属服务:project / function。 |
resourceId | string | 变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}GET /v1/functions/{functionId}/variables/{variableId}
按 ID 读取单个变量(机密变量值被掩码)(scope functions.read。SDK:Variables.getVariable。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
variableId | path | string | 是 | — | 变量 ID。 |
输出:200,模型 variable(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 变量 ID。 |
key | string | 变量键名。 |
value | string | 变量值。 |
secret | boolean | 是否为机密变量。机密变量只能更新或删除,不能读取。 |
resourceType | string | 变量所属服务:project / function。 |
resourceId | string | 变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。 |
调用示例:
curl "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}PUT /v1/functions/{functionId}/variables/{variableId}
更新变量:修改后需重新部署(或重新激活部署)才对后续执行生效(scope functions.write。SDK:Variables.updateVariable。)
输入(application/json)
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
key | body | string | 是 | — | 变量键名。最长 255 字符。 |
value | body | string | 否 | 可为 null | 变量值。最长 8192 字符。 |
secret | body | boolean | 否 | 可为 null | 机密变量可更新/删除,但只有函数可在构建与运行时读取。 |
functionId | path | string | 是 | — | 函数 ID。 |
variableId | path | string | 是 | — | 变量 ID。 |
输出:200,模型 variable(完整字段见前文),关键字段:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 变量 ID。 |
key | string | 变量键名。 |
value | string | 变量值。 |
secret | boolean | 是否为机密变量。机密变量只能更新或删除,不能读取。 |
resourceType | string | 变量所属服务:project / function。 |
resourceId | string | 变量所属资源 ID。resourceType=project 时为空;resourceType=function 时为函数 ID。 |
调用示例:
curl -X PUT "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false
}'响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "API_KEY",
"value": "myPa$$word1",
"secret": false,
"resourceType": "function",
"resourceId": "hello-world"
}DELETE /v1/functions/{functionId}/variables/{variableId}
删除指定变量(scope functions.write。SDK:Variables.deleteVariable。)
输入
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
functionId | path | string | 是 | — | 函数 ID。 |
variableId | path | string | 是 | — | 变量 ID。 |
输出:204 无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
_二进制流或无响应体(见输出说明)。_
错误与边界
- 函数/部署/执行/变量不存在:
404+function_not_found/deployment_not_found/execution_not_found/variable_not_found。 - 重复 ID:
409+function_already_exists/variable_already_exists。 - 构建失败:部署
status=failed,构建输出在部署记录的buildLogs;PATCH .../deployments/{deploymentId}/status只能取消进行中/排队中的构建(标记为canceled),不能替代修复。 - 同步执行受
timeout约束,超时返回执行记录failed;async=true与scheduledAt的执行无同步响应体。 runtime值必须来自GET /functions/runtimes;runtimeReplicas只接受1/2/3/5/10;keep-aliveschedule模式缺 start/end 返回参数错误。- 执行级 API Key 禁止经 query string 传递;在
headers里透传凭证时注意不要记录进日志(logging=false可关闭记录)。 - 部署包上限与构建时长受平台执行计划约束;
deploymentRetention触发的自动清理只删非 active 部署。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Functions.list / create / get / update / delete | /functions CRUD |
Functions.updateFunctionDeployment | PATCH /functions/{functionId}/deployment |
Functions.listDeployments / createDeployment / createDuplicateDeployment / createTemplateDeployment / createVcsDeployment / getDeployment / getDeploymentDownload / updateDeploymentStatus / deleteDeployment | /functions/{functionId}/deployments* |
Functions.createExecution / listExecutions / getExecution / deleteExecution | /functions/{functionId}/executions* |
Functions.listExecutionPaths / listExecutionsByPath | /functions/{functionId}/execution-paths* |
Functions.getRuntimeStatus | GET /functions/{functionId}/runtime-status |
Functions.listVariables / createVariable / getVariable / updateVariable / deleteVariable | /functions/{functionId}/variables* |
Functions.listRuntimes | GET /functions/runtimes |
Functions.listSpecifications | GET /functions/specifications |
Functions.listExecutionPlans | GET /functions/execution-plans |
事实源
- Server API spec:
agentbase-sdksv2.10.0specs/open-api3-latest-server.json(/functions域 20 个路径、runtime 与规格枚举;2.10.0:deployment模型 +artifactMode(source/java-jar)、specificationList+defaultRuntimeSpecification、execution-paths两个端点 +path/pathMatch/method过滤)。 - Server SDK 生成物:
server-nodejs/server-javav2.10.0Functionsservice(createDeployment新增artifactMode表单字段)。 - 语义深度参考:
skills/ob-agentbase/references/functions.md。