函数 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": "APP_ENV",
"value": "development",
"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": "APP_ENV",
"value": "development",
"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": "APP_ENV",
"value": "development",
"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}
更新函数配置(scope functions.write;SDK:Functions.update)。部分未传字段会采用默认值并写回,例如 execute、events 和 scopes 可能被清空;更新前请读取当前配置(scope functions.read),并显式提交需要保留的设置。执行计划等字段的省略行为见下表。修改配置可能需要重新部署。
输入(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 表达式。更新为非空值时须已有唯一的 compact 执行定时规则;缺失会报错,存在多条会冲突。 |
timeout | body | integer | 否 | 15 | 最大执行时长(秒)。 |
enabled | body | boolean | 否 | true | 是否启用函数。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。 |
logging | body | boolean | 否 | true | 关闭后执行记录不包含日志与错误,执行略快。 |
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 | 否 | false | 函数关联仓库的 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 | 否 | 省略取现值,非 schedule 模式归一化为 null | 每日保活窗口开始时间(HH:mm)。schedule 模式下必填。 |
runtimeKeepAliveEnd | body | string | 否 | 省略取现值,非 schedule 模式归一化为 null | 每日保活窗口结束时间(HH:mm)。schedule 模式下必填。 |
runtimeKeepAliveTimezone | body | string | 否 | 省略保留现值 | 评估保活窗口使用的 IANA 时区名。省略保持现值。 |
buildExecutionPlan | body | string | 否 | 省略保留现值 | 函数部署构建使用的执行计划。省略保持现值。 |
runtimeExecutionPlan | body | string | 否 | 省略保留现值 | 函数执行使用的执行计划。省略保持现值。 |
deploymentRetention | body | integer | 否 | 0 | 非激活部署删除前的保留天数。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 | 最大执行时长(秒)。 |
调用说明:先查询当前配置,核对更新接口各字段的默认值,再提交需要保留的字段。不要直接使用只包含部分字段的更新请求。
响应示例:
{
"$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": "APP_ENV",
"value": "development",
"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": "APP_ENV",
"value": "development",
"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": "APP_ENV",
"value": "development",
"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。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "Content-Type: application/json" \
-d '{
"key": "APP_ENV",
"value": "development",
"secret": false
}'
)响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"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": "APP_ENV",
"value": "development",
"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。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X PUT "https://<your-endpoint>/v1/functions/<FUNCTION_ID>/variables/<VARIABLE_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "Content-Type: application/json" \
-d '{
"key": "APP_ENV",
"value": "development",
"secret": false
}'
)响应示例:
{
"$id": "66f1a2b3c4d5e6f7",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"key": "APP_ENV",
"value": "development",
"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 |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
POST /functions | functions.write | functions.create |
PUT /functions/{functionId} | functions.write | functions.update |
GET /projects/{projectId}/schedules | schedules.read | projects.listSchedules |
POST /projects/{projectId}/schedules | schedules.write | projects.createSchedule |
GET /projects/{projectId}/schedules/{scheduleId} | schedules.read | projects.getSchedule |
PATCH /projects/{projectId}/schedules/{scheduleId} | schedules.write | projects.updateSchedule |
DELETE /projects/{projectId}/schedules/{scheduleId} | schedules.write | projects.deleteSchedule |
POST /functions
创建函数
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
functionId | body | 是 | string | — | 函数 ID。可自定义或使用 ID.unique() 生成;允许字母、数字、句点、连字符和下划线,不能以特殊字符开头,最多 36 个字符。 |
name | body | 是 | string | — | 函数名称,最多 128 个字符。 |
runtime | body | 是 | string | enum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 … | 执行运行时。 |
execute | body | 否 | array[string] | default=[] | 具有执行权限的角色字符串数组;默认不授予执行权限。最多 100 个角色,每项最多 64 个字符。 |
events | body | 否 | array[string] | default=[] | 事件列表,最多 100 项。 |
schedule | body | 否 | string | default="" | 定时规则的 CRON 表达式。 |
timeout | body | 否 | integer | format=int32; default=15 | 函数最大执行时间,单位秒。 |
enabled | body | 否 | boolean | default=true | 是否启用函数。禁用时用户无法访问,但持有 API Key 的 Server SDK 仍可访问;切换不会丢失数据。 |
logging | body | 否 | boolean | default=true | 禁用时执行结果不包含日志和错误,执行速度略有提升。 |
entrypoint | body | 否 | string | default="" | 入口文件,路径相对于 "providerRootDirectory"。 |
commands | body | 否 | string | default="" | 构建命令。 |
scopes | body | 否 | array[string] | default=[] | 每次执行自动生成的 API Key 所允许的权限列表,最多 100 项。 |
installationId | body | 否 | string | default="" | 版本控制系统部署使用的 Agentbase 安装 ID。 |
providerRepositoryId | body | 否 | string | default="" | 函数关联仓库的 ID。 |
providerBranch | body | 否 | string | default="" | 函数关联仓库的生产分支。 |
providerSilentMode | body | 否 | boolean | default=false | 函数关联仓库的版本控制连接是否启用静默模式;静默模式下不会在提交和 PR 中添加评论。 |
providerRootDirectory | body | 否 | string | default="" | 函数代码在关联仓库中的路径。 |
buildSpecification | body | 否 | string | default="s-1vcpu-2gb" | 构建规格固定使用平台的函数构建配置。 |
runtimeSpecification | body | 否 | string | default={} | 函数执行的运行时规格。 |
runtimeReplicas | body | 否 | integer | format=int32; default=1 | 可复用的函数运行时副本数,可选 1、2、3、5 或 10。 |
runtimeKeepAliveMode | body | 否 | string | enum=disabled, always, schedule; default="disabled" | 运行时保活模式,可选 disabled、always 或 schedule。 |
runtimeKeepAliveStart | body | 否 | string | — | 每日保活窗口的开始时间,格式 HH:mm;模式为 schedule 时必填。 |
runtimeKeepAliveEnd | body | 否 | string | — | 每日保活窗口的结束时间,格式 HH:mm;模式为 schedule 时必填。 |
runtimeKeepAliveTimezone | body | 否 | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC" | 计算保活窗口使用的 IANA 时区。 |
buildExecutionPlan | body | 否 | string | — | 函数部署构建使用的执行方案;不填时使用原有默认值。 |
runtimeExecutionPlan | body | 否 | string | — | 函数执行使用的执行方案;不填时使用原有默认值。 |
deploymentRetention | body | 否 | integer | format=int32; default=0 | 非活动部署在删除前保留的天数;0 表示全部保留。 |
成功响应:HTTP 201 — function.
返回字段:$id (string), $createdAt (string), $updatedAt (string), execute (array), name (string), enabled (boolean), live (boolean), logging (boolean), runtime (string), deploymentRetention (integer), deploymentId (string), deploymentCreatedAt (string), latestDeploymentId (string), latestDeploymentCreatedAt (string), latestDeploymentStatus (string), scopes (array), vars (array), events (array), schedule (string), timeout (integer), entrypoint (string), commands (string), version (string), installationId (string), providerRepositoryId (string), providerBranch (string), providerRootDirectory (string), providerSilentMode (boolean), buildSpecification (string), runtimeSpecification (string), runtimeReplicas (integer), runtimeKeepAliveMode (string), runtimeKeepAliveStart (string), runtimeKeepAliveEnd (string), runtimeKeepAliveTimezone (string), buildExecutionPlan (string), runtimeExecutionPlan (string).
PUT /functions/{functionId}
更新函数
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
functionId | path | 是 | string | — | 函数 ID。 |
name | body | 是 | string | — | 函数名称,最多 128 个字符。 |
runtime | body | 否 | string | enum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 …; default="" | 执行运行时。 |
execute | body | 否 | array[string] | default=[] | 具有执行权限的角色字符串数组;默认不授予执行权限。最多 100 个角色,每项最多 64 个字符。 |
events | body | 否 | array[string] | default=[] | 事件列表,最多 100 项。 |
schedule | body | 否 | string | default="" | 定时规则的 CRON 表达式。 |
timeout | body | 否 | integer | format=int32; default=15 | 最大执行时间,单位秒。 |
enabled | body | 否 | boolean | default=true | 是否启用函数。禁用时用户无法访问,但持有 API Key 的 Server SDK 仍可访问;切换不会丢失数据。 |
logging | body | 否 | boolean | default=true | 禁用时执行结果不包含日志和错误,执行速度略有提升。 |
entrypoint | body | 否 | string | default="" | 入口文件,路径相对于 "providerRootDirectory"。 |
commands | body | 否 | string | default="" | 构建命令。 |
scopes | body | 否 | array[string] | default=[] | 每次执行自动生成的 API Key 所允许的权限列表,最多 100 项。 |
installationId | body | 否 | string | default="" | 版本控制系统部署使用的 Agentbase 安装 ID。 |
providerRepositoryId | body | 否 | string | — | 函数关联仓库的 ID。 |
providerBranch | body | 否 | string | default="" | 函数关联仓库的生产分支。 |
providerSilentMode | body | 否 | boolean | default=false | 函数关联仓库的版本控制连接是否启用静默模式;静默模式下不会在提交和 PR 中添加评论。 |
providerRootDirectory | body | 否 | string | default="" | 函数代码在关联仓库中的路径。 |
buildSpecification | body | 否 | string | default="s-1vcpu-2gb" | 构建规格固定使用平台的函数构建配置。 |
runtimeSpecification | body | 否 | string | default={} | 函数执行的运行时规格。 |
runtimeReplicas | body | 否 | integer | format=int32; default=1 | 可复用的函数运行时副本数,可选 1、2、3、5 或 10。 |
runtimeKeepAliveMode | body | 否 | string | enum=disabled, always, schedule; default="disabled" | 运行时保活模式,可选 disabled、always 或 schedule;不填时保持原值。 |
runtimeKeepAliveStart | body | 否 | string | — | 每日保活开始时间,格式 HH:mm;模式为 schedule 时必填,不填时保持原值。 |
runtimeKeepAliveEnd | body | 否 | string | — | 每日保活结束时间,格式 HH:mm;模式为 schedule 时必填,不填时保持原值。 |
runtimeKeepAliveTimezone | body | 否 | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC" | 计算保活窗口使用的 IANA 时区;不填时保持原值。 |
buildExecutionPlan | body | 否 | string | — | 函数部署构建的执行方案;不填时保持原值。 |
runtimeExecutionPlan | body | 否 | string | — | 函数执行的执行方案;不填时保持原值。 |
deploymentRetention | body | 否 | integer | format=int32; default=0 | 非活动部署在删除前保留的天数;0 表示全部保留。 |
成功响应:HTTP 200 — function.
返回字段:$id (string), $createdAt (string), $updatedAt (string), execute (array), name (string), enabled (boolean), live (boolean), logging (boolean), runtime (string), deploymentRetention (integer), deploymentId (string), deploymentCreatedAt (string), latestDeploymentId (string), latestDeploymentCreatedAt (string), latestDeploymentStatus (string), scopes (array), vars (array), events (array), schedule (string), timeout (integer), entrypoint (string), commands (string), version (string), installationId (string), providerRepositoryId (string), providerBranch (string), providerRootDirectory (string), providerSilentMode (boolean), buildSpecification (string), runtimeSpecification (string), runtimeReplicas (integer), runtimeKeepAliveMode (string), runtimeKeepAliveStart (string), runtimeKeepAliveEnd (string), runtimeKeepAliveTimezone (string), buildExecutionPlan (string), runtimeExecutionPlan (string).
GET /projects/{projectId}/schedules
列出定时任务
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 项目唯一 ID。 |
queries | query | 否 | array[string] | default=[] | 通过 SDK 的 Query 类生成的查询字符串数组,最多 100 项,每项最多 4096 个字符。可按 resourceType、resourceId、projectId、schedule、scheduleType、purpose、compact、active、region 过滤。 |
total | query | 否 | boolean | default=true | 设为 false 时不计算总数,返回的总数为 0。 |
成功响应:HTTP 200 — scheduleList.
返回字段:total (integer), schedules (array), hasMore (boolean).
POST /projects/{projectId}/schedules
创建定时任务
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 项目唯一 ID。 |
resourceType | body | 是 | string | enum=functions, function, multi-cron-function, execution, message | 定时任务的资源类型,可选 functions、function、multi-cron-function、execution、message。 |
resourceId | body | 是 | string | — | 与该定时任务关联的资源 ID。 |
schedule | body | 是 | string | — | 与 scheduleType 对应的 Cron 表达式或 JSON 规则。 |
active | body | 否 | boolean | default=false | 定时任务是否启用。 |
data | body | 否 | string | — | JSON 字符串形式的定时任务数据,用于保存执行所需的资源上下文。 |
scheduleType | body | 否 | string | enum=cron, interval, quartz; default="cron" | 周期函数规则类型;创建后不可更改。 |
成功响应:HTTP 201 — schedule.
返回字段:$id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
GET /projects/{projectId}/schedules/{scheduleId}
查询定时任务
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 项目唯一 ID。 |
scheduleId | path | 是 | string | — | 定时任务 ID。 |
成功响应:HTTP 200 — schedule.
返回字段:$id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
PATCH /projects/{projectId}/schedules/{scheduleId}
更新定时任务
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 项目唯一 ID。 |
scheduleId | path | 是 | string | — | 定时任务唯一 ID。 |
schedule | body | 否 | string | — | 与现有定时任务类型对应的规则表达式或 JSON。 |
active | body | 否 | boolean | — | 定时任务是否启用。 |
data | body | 否 | string | — | JSON 对象文本;body 包含发送给函数的 JSON 文本。 |
scheduleType | body | 否 | string | enum=cron, interval, quartz | 现有规则类型,不允许更改。 |
成功响应:HTTP 200 — schedule.
返回字段:$id (string), $createdAt (string), $updatedAt (string), resourceType (string), resourceId (string), resourceUpdatedAt (string), projectId (string), scheduleType (string), purpose (string), compact (boolean), configRevision (string), schedule (string), data (object), active (boolean), region (string).
DELETE /projects/{projectId}/schedules/{scheduleId}
删除定时任务
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 项目唯一 ID。 |
scheduleId | path | 是 | string | — | 定时任务唯一 ID。 |
成功响应:HTTP 204 — No content.
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。