Docs
文档目录

函数 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)聚合检索。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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列出执行计划

端点详解

请求与响应

以下按端点逐个给出输入/输出规格、可复制的 curl 调用示例与响应示例。路径前缀 /v1;请求头 X-Appwrite-Project: <YOUR_PROJECT_ID> 与 X-Appwrite-Key: <YOUR_API_KEY> 对全部端点一致,示例中不再逐条解释。

函数 CRUD

GET /v1/functions

分页列出项目内全部函数,支持按名称、运行时、启用状态等属性过滤与关键词搜索(scope functions.read。SDK:Functions.list。)

输入

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:name、enabled、runtime、deploymentId、schedule、scheduleNext、schedulePrevious、timeout、entrypoint、commands、installationId。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 functionList:total(匹配总数,total=false 时不计算)+ functions[](当前页数据)。

元素模型 function 关键字段:

字段类型说明
$idstring函数 ID。
$createdAtstring函数创建时间(ISO 8601)。
$updatedAtstring函数更新时间(ISO 8601)。
executestring[]可执行此函数的角色数组。
namestring函数名称。
enabledboolean函数是否启用。
liveboolean函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。
loggingboolean关闭后执行记录不包含日志与错误,执行略快。
runtimestring函数构建与运行使用的运行时。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
scopesstring[]执行级自动生成 API Key 允许的 scope 列表。
eventsstring[]触发事件列表。
schedulestringCRON 格式的定时调度表达式。
timeoutinteger最大执行时长(秒)。

调用示例:

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)

参数位置类型必填默认/枚举说明
functionIdbodystring是—函数 ID。可自定义,或用 SDK 的 ID.unique() 生成;仅允许 a-z、A-Z、0-9、句点、连字符、下划线,不能以特殊字符开头。最长 36 字符。
namebodystring是—函数名称。最长 128 字符。
runtimebodystring是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 为准)执行运行时。
executebodystring[]否—拥有执行权限的角色字符串数组。默认不授予任何角色。最多 100 个角色,每个最长 64 字符。
eventsbodystring[]否—触发事件列表。最多 100 个。
schedulebodystring否—CRON 格式的定时调度表达式。
timeoutbodyinteger否—最大执行时长(秒)。
enabledbodyboolean否—是否启用函数。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbodyboolean否—关闭后执行记录不包含日志与错误,执行略快。
entrypointbodystring否—入口文件。路径相对于 providerRootDirectory。
commandsbodystring否—构建命令。
scopesbodystring[]否—每次执行自动生成的 API Key 允许的 scope 列表。最多 100 个。
installationIdbodystring否—用于 VCS 部署的 AppBase 安装 ID。
providerRepositoryIdbodystring否—函数关联的 VCS 仓库 ID。
providerBranchbodystring否—函数关联仓库的生产分支。
providerSilentModebodyboolean否—函数关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。
providerRootDirectorybodystring否—函数代码在关联仓库中的路径。
buildSpecificationbodystring否—构建规格固定为平台函数构建档位。
runtimeSpecificationbodystring否—函数执行使用的运行规格。
runtimeReplicasbodyinteger否—函数执行的可复用常驻运行时副本数。允许 1 / 2 / 3 / 5 / 10。
runtimeKeepAliveModebodystring否disabled / always / schedule运行时保活模式:disabled / always / schedule。
runtimeKeepAliveStartbodystring否可为 null每日保活窗口开始时间(HH:mm)。schedule 模式下必填。
runtimeKeepAliveEndbodystring否可为 null每日保活窗口结束时间(HH:mm)。schedule 模式下必填。
runtimeKeepAliveTimezonebodystring否africa/abidjan / africa/accra / africa/addis_ababa / africa/algiers / africa/asmara / africa/bamako / africa/bangui / africa/banjul ……(共 420 个)评估保活窗口使用的 IANA 时区名。
buildExecutionPlanbodystring否可为 null函数部署构建使用的执行计划。省略使用遗留默认值。
runtimeExecutionPlanbodystring否可为 null函数执行使用的执行计划。省略使用遗留默认值。
deploymentRetentionbodyinteger否—非激活部署删除前的保留天数。0 表示全部保留。

输出:201,模型 function,字段:

字段类型说明
$idstring函数 ID。
$createdAtstring函数创建时间(ISO 8601)。
$updatedAtstring函数更新时间(ISO 8601)。
executestring[]可执行此函数的角色数组。
namestring函数名称。
enabledboolean函数是否启用。
liveboolean函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。
loggingboolean关闭后执行记录不包含日志与错误,执行略快。
runtimestring函数构建与运行使用的运行时。
deploymentRetentioninteger非激活部署保留天数,到期后自动删除。
deploymentIdstring当前激活的部署 ID。
deploymentCreatedAtstring激活部署的创建时间(ISO 8601)。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentCreatedAtstring最新部署的创建时间(ISO 8601)。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
scopesstring[]执行级自动生成 API Key 允许的 scope 列表。
varsvariable[]函数变量列表。
eventsstring[]触发事件列表。
schedulestringCRON 格式的定时调度表达式。
timeoutinteger最大执行时长(秒)。
entrypointstring部署代码的入口文件。
commandsstring部署的构建命令。
versionstring函数使用的 Open Runtimes 版本。
installationIdstring函数关联的 VCS(版本控制系统)安装 ID。
providerRepositoryIdstringVCS(版本控制系统)仓库 ID。
providerBranchstringVCS(版本控制系统)分支名。
providerRootDirectorystring函数代码在 VCS 仓库中的路径。
providerSilentModebooleanVCS 连接是否为静默模式。静默模式下不会在仓库的 PR / MR 上发表评论。
buildSpecificationstring构建使用的固定机器规格(CPU/内存档位)。
runtimeSpecificationstring运行使用的机器规格(CPU/内存档位)。
runtimeReplicasinteger函数执行的可复用常驻运行时副本数。
runtimeKeepAliveModestring运行时保活模式:disabled / always / schedule。
runtimeKeepAliveStartstring每日保活窗口开始时间(HH:mm)。
runtimeKeepAliveEndstring每日保活窗口结束时间(HH:mm)。
runtimeKeepAliveTimezonestring评估保活窗口使用的 IANA 时区名。
buildExecutionPlanstring部署构建使用的执行计划。
runtimeExecutionPlanstring函数执行使用的执行计划。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。

输出:200,模型 function(完整字段见前文),关键字段:

字段类型说明
$idstring函数 ID。
$createdAtstring函数创建时间(ISO 8601)。
$updatedAtstring函数更新时间(ISO 8601)。
executestring[]可执行此函数的角色数组。
namestring函数名称。
enabledboolean函数是否启用。
liveboolean函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。
loggingboolean关闭后执行记录不包含日志与错误,执行略快。
runtimestring函数构建与运行使用的运行时。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
scopesstring[]执行级自动生成 API Key 允许的 scope 列表。
eventsstring[]触发事件列表。
schedulestringCRON 格式的定时调度表达式。
timeoutinteger最大执行时长(秒)。

调用示例:

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)

参数位置类型必填默认/枚举说明
namebodystring是—函数名称。最长 128 字符。
runtimebodystring否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 为准);省略保留现值执行运行时。
executebodystring[]否[]拥有执行权限的角色字符串数组。默认不授予任何角色。最多 100 个角色,每个最长 64 字符。
eventsbodystring[]否[]触发事件列表。最多 100 个。
schedulebodystring否省略保留现值CRON 表达式。更新为非空值时须已有唯一的 compact 执行定时规则;缺失会报错,存在多条会冲突。
timeoutbodyinteger否15最大执行时长(秒)。
enabledbodyboolean否true是否启用函数。禁用后用户侧不可访问,但持 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbodyboolean否true关闭后执行记录不包含日志与错误,执行略快。
entrypointbodystring否空值沿用现值入口文件。路径相对于 providerRootDirectory。
commandsbodystring否""构建命令。
scopesbodystring[]否[]每次执行自动生成的 API Key 允许的 scope 列表。最多 100 个。
installationIdbodystring否""用于 VCS 部署的 AppBase 安装 ID。
providerRepositoryIdbodystring否null函数关联的 VCS 仓库 ID。
providerBranchbodystring否""函数关联仓库的生产分支。
providerSilentModebodyboolean否false函数关联仓库的 VCS 连接是否为静默模式。静默模式下不在 commit 与 PR 上发表评论。
providerRootDirectorybodystring否""函数代码在关联仓库中的路径。
buildSpecificationbodystring否平台固定构建规格构建规格固定为平台函数构建档位。
runtimeSpecificationbodystring否省略保留现值函数执行使用的运行规格。
runtimeReplicasbodyinteger否省略保留现值函数执行的可复用常驻运行时副本数。允许 1 / 2 / 3 / 5 / 10。
runtimeKeepAliveModebodystring否disabled / always / schedule;省略保留现值运行时保活模式:disabled / always / schedule。省略保持现值。
runtimeKeepAliveStartbodystring否省略取现值,非 schedule 模式归一化为 null每日保活窗口开始时间(HH:mm)。schedule 模式下必填。
runtimeKeepAliveEndbodystring否省略取现值,非 schedule 模式归一化为 null每日保活窗口结束时间(HH:mm)。schedule 模式下必填。
runtimeKeepAliveTimezonebodystring否省略保留现值评估保活窗口使用的 IANA 时区名。省略保持现值。
buildExecutionPlanbodystring否省略保留现值函数部署构建使用的执行计划。省略保持现值。
runtimeExecutionPlanbodystring否省略保留现值函数执行使用的执行计划。省略保持现值。
deploymentRetentionbodyinteger否0非激活部署删除前的保留天数。0 表示全部保留。
functionIdpathstring是—函数 ID。

输出:200,模型 function(完整字段见前文),关键字段:

字段类型说明
$idstring函数 ID。
$createdAtstring函数创建时间(ISO 8601)。
$updatedAtstring函数更新时间(ISO 8601)。
executestring[]可执行此函数的角色数组。
namestring函数名称。
enabledboolean函数是否启用。
liveboolean函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。
loggingboolean关闭后执行记录不包含日志与错误,执行略快。
runtimestring函数构建与运行使用的运行时。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
scopesstring[]执行级自动生成 API Key 允许的 scope 列表。
eventsstring[]触发事件列表。
schedulestringCRON 格式的定时调度表达式。
timeoutinteger最大执行时长(秒)。

调用说明:先查询当前配置,核对更新接口各字段的默认值,再提交需要保留的字段。不要直接使用只包含部分字段的更新请求。

响应示例:

{
  "$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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 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)

参数位置类型必填默认/枚举说明
deploymentIdbodystring是—部署 ID。
functionIdpathstring是—函数 ID。

输出:200,模型 function(完整字段见前文),关键字段:

字段类型说明
$idstring函数 ID。
$createdAtstring函数创建时间(ISO 8601)。
$updatedAtstring函数更新时间(ISO 8601)。
executestring[]可执行此函数的角色数组。
namestring函数名称。
enabledboolean函数是否启用。
liveboolean函数是否已按最新配置部署。修改变量/入口/构建命令等需重新部署的配置后变为 false,重新部署后恢复 true。
loggingboolean关闭后执行记录不包含日志与错误,执行略快。
runtimestring函数构建与运行使用的运行时。
deploymentIdstring当前激活的部署 ID。
latestDeploymentIdstring最新(不一定激活)部署 ID。
latestDeploymentStatusstring最新部署的状态:waiting / processing / building / ready / failed。
scopesstring[]执行级自动生成 API Key 允许的 scope 列表。
eventsstring[]触发事件列表。
schedulestringCRON 格式的定时调度表达式。
timeoutinteger最大执行时长(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:buildSize、sourceSize、totalSize、buildDuration、status、activate、type。最多 100 条、每条最长 4096 字符。
searchquerystring否—搜索词,模糊过滤列表结果。最长 256 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。

输出:200,模型 deploymentList:total(匹配总数,total=false 时不计算)+ deployments[](当前页数据)。

元素模型 deployment 关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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" 上传)

参数位置类型必填默认/枚举说明
entrypointbody(表单)string否可为 null入口文件。
commandsbody(表单)string否可为 null构建命令。
codebody(表单)string是—gzip 压缩的代码包(artifactMode=source),或可执行 JAR(artifactMode=java-jar)。使用 AppBase CLI 时传代码目录路径,CLI 会自动打包;路径须位于当前目录内。
artifactModebody(表单)string否source / java-jar(默认 source)上传模式(2.10.0 新增):source 为 gzip 源码包;java-jar 为 Java 17 可执行 JAR(真实入口为 manifest 的 Main-Class;Index.java 是兼容标识;JAR 上限默认 100,000,000 字节,同时受套餐部署上限约束)。
activatebody(表单)boolean是—构建完成后是否自动激活该部署。
functionIdpathstring是—函数 ID。

JAR 模式要求目标 Function 的运行时为 java-17.0,包内包含 manifest 指定的入口类,应用监听端口 3000 并提供 /__opr/health;不需要填写源码入口和构建命令。分片上传时各片保持相同 artifactMode。202 仅表示接收部署,需继续检查状态达到 ready、Function 当前 deploymentId 与目标一致,并验证实际 execution;activate=true 不是执行成功保证。

输出:202,模型 deployment,字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
$updatedAtstring部署更新时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
screenshotLightstring浅色主题截图的文件 ID。
screenshotDarkstring深色主题截图的文件 ID。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildLogsstring构建日志。
buildDurationinteger当前构建耗时(秒)。
providerRepositoryNamestringVCS 提供商仓库名。
providerRepositoryOwnerstringVCS 仓库属主名。
providerRepositoryUrlstringVCS 仓库地址。
providerCommitHashstringVCS 提交哈希。
providerCommitAuthorUrlstringVCS 提交作者主页。
providerCommitAuthorstringVCS 提交作者名。
providerCommitMessagestring提交信息。
providerCommitUrlstringVCS 提交地址。
providerBranchstringVCS 仓库分支。
providerBranchUrlstringVCS 仓库分支。

调用示例:

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)

参数位置类型必填默认/枚举说明
deploymentIdbodystring是—部署 ID。
buildIdbodystring否—本次构建 ID。
functionIdpathstring是—函数 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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)

参数位置类型必填默认/枚举说明
repositorybodystring是—模板仓库名。
ownerbodystring是—模板仓库属主。
rootDirectorybodystring是—函数代码在模板仓库中的路径。
typebodystring是commit / branch / tagreference 的类型:commit / branch / tag。
referencebodystring是—reference 的值:提交哈希、分支名或发布标签。
activatebodyboolean否—构建完成后是否自动激活该部署。
functionIdpathstring是—函数 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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)

参数位置类型必填默认/枚举说明
typebodystring是branch / commitreference 的类型:branch / commit。
referencebodystring是—创建部署的 VCS 引用:分支名或提交哈希(随 type 而定)。
activatebodyboolean否—构建完成后是否自动激活该部署。
functionIdpathstring是—函数 ID。

输出:202,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
deploymentIdpathstring是—部署 ID。

输出:200,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
deploymentIdpathstring是—部署 ID。
typequerystring否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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
deploymentIdpathstring是—部署 ID。

输出:200,模型 deployment(完整字段见前文),关键字段:

字段类型说明
$idstring部署 ID。
$createdAtstring部署创建时间(ISO 8601)。
typestring部署类型。
artifactModestring上传模式:source / java-jar(2.10.0 新增)。
resourceIdstring所属资源 ID。
resourceTypestring所属资源类型。
entrypointstring执行部署代码使用的入口文件。
sourceSizeinteger源码包大小(字节)。
buildSizeinteger构建产物大小(字节)。
totalSizeinteger总大小(源码 + 构建产物,字节)。
buildIdstring当前构建 ID。
activateboolean构建完成后是否自动激活。
statusstring部署状态:waiting / processing / building / ready / canceled / failed。
buildDurationinteger当前构建耗时(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
deploymentIdpathstring是—部署 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)

参数位置类型必填默认/枚举说明
bodybodystring否—执行请求体。默认空串。
asyncbodyboolean否—是否后台执行。默认 false。
pathbodystring否—执行路径,可含查询参数。默认 /。
methodbodystring否GET / POST / PUT / PATCH / DELETE / OPTIONS / HEADHTTP 方法。默认 POST。
headersbodyobject否—执行请求头。默认为空。
scheduledAtbodystring否可为 null定时执行时间(ISO 8601)。必须是未来时间,精度到分钟。
functionIdpathstring是—函数 ID。

输出:201,模型 execution,字段:

字段类型说明
$idstring执行记录 ID。
$createdAtstring执行记录创建时间(ISO 8601)。
$updatedAtstring执行记录更新时间(ISO 8601)。
$permissionsstring[]执行角色。
functionIdstring函数 ID。
deploymentIdstring触发本次执行使用的部署 ID。
triggerstring触发来源:http / schedule / event。
statusstring执行状态:waiting / processing / completed / failed / scheduled。
requestMethodstringHTTP 请求方法。
requestPathstringHTTP 请求路径(可含查询串)。
requestHeadersheaders[]HTTP 请求头键值对象。仅返回白名单内的头;同步创建的执行返回全部请求头。
responseStatusCodeintegerHTTP 响应状态码。
responseBodystring函数返回的 HTTP 响应体。
responseHeadersheaders[]HTTP 响应头键值对象。仅返回白名单内的头;同步创建的执行返回全部响应头。
logsstring函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
errorsstring函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
durationnumber资源(函数/站点)执行耗时(秒)。
scheduledAtstring定时执行时间。留空则立即排队执行。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
queriesquerystring[]否默认 []查询字符串数组,由 SDK 的 Query 构造器生成(形如 limit(25)、equal("name","x"));支持过滤、排序、分页(limit / cursorAfter / cursorBefore);可过滤属性:trigger、status、responseStatusCode、duration、requestMethod、requestPath、deploymentId。最多 100 条、每条最长 4096 字符。
totalqueryboolean否默认 true设为 false 时跳过总数计算,返回的 total 固定为 0。
pathquerystring否默认空完整请求路径或正则,查询字符串参与匹配;Node Server 对象参数名为 xpath。
pathMatchquerystring否exact / regex,默认 exact正则不带 /…/ 分隔符,非法表达式被拒绝。
methodquerystring否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 关键字段:

字段类型说明
$idstring执行记录 ID。
$createdAtstring执行记录创建时间(ISO 8601)。
functionIdstring函数 ID。
deploymentIdstring触发本次执行使用的部署 ID。
triggerstring触发来源:http / schedule / event。
statusstring执行状态:waiting / processing / completed / failed / scheduled。
requestMethodstringHTTP 请求方法。
requestPathstringHTTP 请求路径(可含查询串)。
responseStatusCodeintegerHTTP 响应状态码。
responseBodystring函数返回的 HTTP 响应体。
logsstring函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
errorsstring函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
durationnumber资源(函数/站点)执行耗时(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
executionIdpathstring是—执行记录 ID。

输出:200,模型 execution(完整字段见前文),关键字段:

字段类型说明
$idstring执行记录 ID。
$createdAtstring执行记录创建时间(ISO 8601)。
functionIdstring函数 ID。
deploymentIdstring触发本次执行使用的部署 ID。
triggerstring触发来源:http / schedule / event。
statusstring执行状态:waiting / processing / completed / failed / scheduled。
requestMethodstringHTTP 请求方法。
requestPathstringHTTP 请求路径(可含查询串)。
responseStatusCodeintegerHTTP 响应状态码。
responseBodystring函数返回的 HTTP 响应体。
logsstring函数日志(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
errorsstring函数错误输出(末尾 4000 字符)。仅当使用 API Key 调用或作为 webhook 载荷返回时才有内容,否则为空串。
durationnumber资源(函数/站点)执行耗时(秒)。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
executionIdpathstring是—执行记录 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。

输入:

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
limitqueryinteger否25最大返回数量。
offsetqueryinteger否0跳过的记录数。
totalqueryboolean否true是否计算总数;false 时返回的 total 为 0。
pathquerystring否—按请求路径过滤(2.10.0 新增);配合 pathMatch 选择精确或正则匹配。
pathMatchquerystring否exact / regex(默认 exact)路径匹配模式(2.10.0 新增)。
methodquerystring否GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD按 HTTP 方法过滤(2.10.0 新增)。

输出:200,模型 executionPathList。

字段类型说明
totalinteger去重请求路径总数。
pathsstring[]本页去重请求路径。

调用示例:

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。

输入:

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
pathquerystring是—执行请求路径;默认精确匹配,pathMatch=regex 时为正则(2.10.0 起)。
queriesquerystring[]否[]SDK Query 字符串数组;最多 100 项,每项最长 4096 字符。
totalqueryboolean否true是否计算总数;false 时返回的 total 为 0。
pathMatchquerystring否exact / regex(默认 exact)路径匹配模式(2.10.0 新增)。
methodquerystring否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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。

输出:200,模型 runtimeStatus,字段:

字段类型说明
statusstring运行时状态摘要。
coveragestring状态数据覆盖范围。
updatedAtstring底层资源最近更新时间。
messagestring面向用户的安全状态消息。

调用示例:

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 关键字段:

字段类型说明
$idstring运行时 ID。
keystring所属运行时键名。
namestring运行时名称。
versionstring运行时版本。
basestring构建该运行时使用的基础 Docker 镜像。
imagestringDocker Hub 镜像名。
supportsstring[]支持的 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 关键字段:

字段类型说明
memoryinteger内存大小(MB)。
cpusnumberCPU 核数。
enabledboolean该规格是否启用。
slugstring规格标识(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。)

输入

参数位置类型必填默认/枚举说明
runtimequerystring否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 关键字段:

字段类型说明
idstring稳定的执行计划 ID。
namestring执行计划展示名。
summarystring执行计划简述。
suitableForstring该执行计划支持的资源类型。
recommendedboolean是否为推荐执行计划。
availabilitystring该执行计划的可用性。
effectiveOnstring所选执行计划的生效时机。

调用示例:

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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。

输出:200,模型 variableList:total(匹配总数,total=false 时不计算)+ variables[](当前页数据)。

元素模型 variable 关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 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)

参数位置类型必填默认/枚举说明
keybodystring是—变量键名。最长 255 字符。
valuebodystring是—变量值。最长 8192 字符。
secretbodyboolean否—机密变量可更新/删除,但只有函数可在构建与运行时读取。
functionIdpathstring是—函数 ID。

输出:201,模型 variable,字段:

字段类型说明
$idstring变量 ID。
$createdAtstring变量创建时间(ISO 8601)。
$updatedAtstring变量创建时间(ISO 8601)。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
variableIdpathstring是—变量 ID。

输出:200,模型 variable(完整字段见前文),关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 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)

参数位置类型必填默认/枚举说明
keybodystring是—变量键名。最长 255 字符。
valuebodystring否可为 null变量值。最长 8192 字符。
secretbodyboolean否可为 null机密变量可更新/删除,但只有函数可在构建与运行时读取。
functionIdpathstring是—函数 ID。
variableIdpathstring是—变量 ID。

输出:200,模型 variable(完整字段见前文),关键字段:

字段类型说明
$idstring变量 ID。
keystring变量键名。
valuestring变量值。
secretboolean是否为机密变量。机密变量只能更新或删除,不能读取。
resourceTypestring变量所属服务:project / function。
resourceIdstring变量所属资源 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。)

输入

参数位置类型必填默认/枚举说明
functionIdpathstring是—函数 ID。
variableIdpathstring是—变量 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>"

响应示例:

_二进制流或无响应体(见输出说明)。_

错误与边界

与 Server SDK 的对应

service.method端点
Functions.list / create / get / update / delete/functions CRUD
Functions.updateFunctionDeploymentPATCH /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.getRuntimeStatusGET /functions/{functionId}/runtime-status
Functions.listVariables / createVariable / getVariable / updateVariable / deleteVariable/functions/{functionId}/variables*
Functions.listRuntimesGET /functions/runtimes
Functions.listSpecificationsGET /functions/specifications
Functions.listExecutionPlansGET /functions/execution-plans

2.12.0 接口与兼容增量

以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。

HTTPScopeSDK
POST /functionsfunctions.writefunctions.create
PUT /functions/{functionId}functions.writefunctions.update
GET /projects/{projectId}/schedulesschedules.readprojects.listSchedules
POST /projects/{projectId}/schedulesschedules.writeprojects.createSchedule
GET /projects/{projectId}/schedules/{scheduleId}schedules.readprojects.getSchedule
PATCH /projects/{projectId}/schedules/{scheduleId}schedules.writeprojects.updateSchedule
DELETE /projects/{projectId}/schedules/{scheduleId}schedules.writeprojects.deleteSchedule

POST /functions

创建函数

参数位置必填类型约束 / 默认值含义
functionIdbody是string—函数 ID。可自定义或使用 ID.unique() 生成;允许字母、数字、句点、连字符和下划线,不能以特殊字符开头,最多 36 个字符。
namebody是string—函数名称,最多 128 个字符。
runtimebody是stringenum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 …执行运行时。
executebody否array[string]default=[]具有执行权限的角色字符串数组;默认不授予执行权限。最多 100 个角色,每项最多 64 个字符。
eventsbody否array[string]default=[]事件列表,最多 100 项。
schedulebody否stringdefault=""定时规则的 CRON 表达式。
timeoutbody否integerformat=int32; default=15函数最大执行时间,单位秒。
enabledbody否booleandefault=true是否启用函数。禁用时用户无法访问,但持有 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbody否booleandefault=true禁用时执行结果不包含日志和错误,执行速度略有提升。
entrypointbody否stringdefault=""入口文件,路径相对于 "providerRootDirectory"。
commandsbody否stringdefault=""构建命令。
scopesbody否array[string]default=[]每次执行自动生成的 API Key 所允许的权限列表,最多 100 项。
installationIdbody否stringdefault=""版本控制系统部署使用的 Agentbase 安装 ID。
providerRepositoryIdbody否stringdefault=""函数关联仓库的 ID。
providerBranchbody否stringdefault=""函数关联仓库的生产分支。
providerSilentModebody否booleandefault=false函数关联仓库的版本控制连接是否启用静默模式;静默模式下不会在提交和 PR 中添加评论。
providerRootDirectorybody否stringdefault=""函数代码在关联仓库中的路径。
buildSpecificationbody否stringdefault="s-1vcpu-2gb"构建规格固定使用平台的函数构建配置。
runtimeSpecificationbody否stringdefault={}函数执行的运行时规格。
runtimeReplicasbody否integerformat=int32; default=1可复用的函数运行时副本数,可选 1、2、3、5 或 10。
runtimeKeepAliveModebody否stringenum=disabled, always, schedule; default="disabled"运行时保活模式,可选 disabled、always 或 schedule。
runtimeKeepAliveStartbody否string—每日保活窗口的开始时间,格式 HH:mm;模式为 schedule 时必填。
runtimeKeepAliveEndbody否string—每日保活窗口的结束时间,格式 HH:mm;模式为 schedule 时必填。
runtimeKeepAliveTimezonebody否stringenum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC"计算保活窗口使用的 IANA 时区。
buildExecutionPlanbody否string—函数部署构建使用的执行方案;不填时使用原有默认值。
runtimeExecutionPlanbody否string—函数执行使用的执行方案;不填时使用原有默认值。
deploymentRetentionbody否integerformat=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}

更新函数

参数位置必填类型约束 / 默认值含义
functionIdpath是string—函数 ID。
namebody是string—函数名称,最多 128 个字符。
runtimebody否stringenum=node-14.5, node-16.0, node-18.0, node-19.0, node-20.0, node-21.0, node-22, node-23 …; default=""执行运行时。
executebody否array[string]default=[]具有执行权限的角色字符串数组;默认不授予执行权限。最多 100 个角色,每项最多 64 个字符。
eventsbody否array[string]default=[]事件列表,最多 100 项。
schedulebody否stringdefault=""定时规则的 CRON 表达式。
timeoutbody否integerformat=int32; default=15最大执行时间,单位秒。
enabledbody否booleandefault=true是否启用函数。禁用时用户无法访问,但持有 API Key 的 Server SDK 仍可访问;切换不会丢失数据。
loggingbody否booleandefault=true禁用时执行结果不包含日志和错误,执行速度略有提升。
entrypointbody否stringdefault=""入口文件,路径相对于 "providerRootDirectory"。
commandsbody否stringdefault=""构建命令。
scopesbody否array[string]default=[]每次执行自动生成的 API Key 所允许的权限列表,最多 100 项。
installationIdbody否stringdefault=""版本控制系统部署使用的 Agentbase 安装 ID。
providerRepositoryIdbody否string—函数关联仓库的 ID。
providerBranchbody否stringdefault=""函数关联仓库的生产分支。
providerSilentModebody否booleandefault=false函数关联仓库的版本控制连接是否启用静默模式;静默模式下不会在提交和 PR 中添加评论。
providerRootDirectorybody否stringdefault=""函数代码在关联仓库中的路径。
buildSpecificationbody否stringdefault="s-1vcpu-2gb"构建规格固定使用平台的函数构建配置。
runtimeSpecificationbody否stringdefault={}函数执行的运行时规格。
runtimeReplicasbody否integerformat=int32; default=1可复用的函数运行时副本数,可选 1、2、3、5 或 10。
runtimeKeepAliveModebody否stringenum=disabled, always, schedule; default="disabled"运行时保活模式,可选 disabled、always 或 schedule;不填时保持原值。
runtimeKeepAliveStartbody否string—每日保活开始时间,格式 HH:mm;模式为 schedule 时必填,不填时保持原值。
runtimeKeepAliveEndbody否string—每日保活结束时间,格式 HH:mm;模式为 schedule 时必填,不填时保持原值。
runtimeKeepAliveTimezonebody否stringenum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="UTC"计算保活窗口使用的 IANA 时区;不填时保持原值。
buildExecutionPlanbody否string—函数部署构建的执行方案;不填时保持原值。
runtimeExecutionPlanbody否string—函数执行的执行方案;不填时保持原值。
deploymentRetentionbody否integerformat=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

列出定时任务

参数位置必填类型约束 / 默认值含义
projectIdpath是string—项目唯一 ID。
queriesquery否array[string]default=[]通过 SDK 的 Query 类生成的查询字符串数组,最多 100 项,每项最多 4096 个字符。可按 resourceType、resourceId、projectId、schedule、scheduleType、purpose、compact、active、region 过滤。
totalquery否booleandefault=true设为 false 时不计算总数,返回的总数为 0。

成功响应:HTTP 200 — scheduleList.

返回字段:total (integer), schedules (array), hasMore (boolean).

POST /projects/{projectId}/schedules

创建定时任务

参数位置必填类型约束 / 默认值含义
projectIdpath是string—项目唯一 ID。
resourceTypebody是stringenum=functions, function, multi-cron-function, execution, message定时任务的资源类型,可选 functions、function、multi-cron-function、execution、message。
resourceIdbody是string—与该定时任务关联的资源 ID。
schedulebody是string—与 scheduleType 对应的 Cron 表达式或 JSON 规则。
activebody否booleandefault=false定时任务是否启用。
databody否string—JSON 字符串形式的定时任务数据,用于保存执行所需的资源上下文。
scheduleTypebody否stringenum=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}

查询定时任务

参数位置必填类型约束 / 默认值含义
projectIdpath是string—项目唯一 ID。
scheduleIdpath是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}

更新定时任务

参数位置必填类型约束 / 默认值含义
projectIdpath是string—项目唯一 ID。
scheduleIdpath是string—定时任务唯一 ID。
schedulebody否string—与现有定时任务类型对应的规则表达式或 JSON。
activebody否boolean—定时任务是否启用。
databody否string—JSON 对象文本;body 包含发送给函数的 JSON 文本。
scheduleTypebody否stringenum=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}

删除定时任务

参数位置必填类型约束 / 默认值含义
projectIdpath是string—项目唯一 ID。
scheduleIdpath是string—定时任务唯一 ID。

成功响应:HTTP 204 — No content.

错误与重试边界

400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。