AgentbaseDocs
文档目录

项目 API

项目自身的管理面:项目变量(构建/运行期注入的环境变量)与表模式转换(table mode conversion,把库表批量迁移到目标表池模式)。

服务与资源边界

项目 API(/v1/project/*)提供单个 Agentbase 项目(如展示项目 enterprise-ai-hub-210)自身的全局管理能力,包含两大子域:

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:project.read / project.write。

端点总览

本模块共包含 12 个端点:前 5 个端点负责项目变量(/project/variables*)的 CRUD;后 7 个端点负责表模式转换任务(/project/table-mode-conversions*)的目标枚举、任务创建、启动迁移、正式切换、应急回滚与源数据删除。

端点清单

方法 + 路径用途
GET /project/variables列出项目变量
POST /project/variables创建项目变量
GET /project/variables/{variableId}获取变量
PUT /project/variables/{variableId}更新变量
DELETE /project/variables/{variableId}删除变量
GET /project/table-mode-conversions转换列表
POST /project/table-mode-conversions发起转换
GET .../table-mode-conversions/targets可用目标模式/标签
GET .../table-mode-conversions/{conversionId}转换详情
PATCH .../{conversionId}/start启动转换
PATCH .../{conversionId}/cutover切换(cutover)
PATCH .../{conversionId}/rollback回滚
PATCH .../{conversionId}/source-data/delete删除源数据

端点详解

请求与响应

以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例变量约定见 通用约定。

GET /v1/project/variables

列出项目级变量。secret 变量的 value 在列表中被掩码。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []可过滤字段:key、resourceType、resourceId、secret;分页用 limit(n)/offset(n)
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 variableList 模型:total + variables[]。variable 字段结构见 [POST /v1/project/variables](#post-v1projectvariables)。

字段类型说明
totalinteger匹配查询的变量总数
variables[]variable[]变量对象

调用示例:

curl \
  "https://<your-endpoint>/v1/project/variables?queries[]=limit(25)&total=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "variables": [
    {
      "$id": "66a9d9b804d8e",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "key": "API_KEY",
      "value": "whsec_9f8e7d6c5b4a",
      "secret": false,
      "resourceType": "project",
      "resourceId": ""
    }
  ]
}

POST /v1/project/variables

创建项目变量。变量在 Functions / Sites 构建与运行时注入为环境变量(函数级/站点级同名 key 覆盖项目级)。

输入:

参数位置类型必填默认/枚举说明
variableIdbodystring是变量 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,最长 36 字符
keybodystring是变量键(环境变量名),最长 255 字符
valuebodystring是变量值,最长 8192 字符
secretbodyboolean否默认 false设为 true 后值仅在构建/运行时对项目可见,任何管理 API 读取都返回掩码;secret 属性不可反向切换

输出:201,返回 variable 模型。完整字段表:

字段类型说明
$idstring变量 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
keystring变量键(注入为环境变量名)
valuestring变量值;secret 变量在读取端点中被掩码
secretboolean是否为 secret 变量
resourceTypestring归属服务:project(项目级)或 function(函数级)
resourceIdstring归属资源 ID;项目级变量为空串

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/project/variables" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "variableId": "66a9d9b804d8e",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false
}'

响应示例:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

需要保密的凭据(第三方密钥、签名密钥)应设 secret=true:后续读取端点对 value 返回掩码,只能更新或删除,不能回看原文。

GET /v1/project/variables/{variableId}

按 ID 获取单个项目变量(secret 变量的 value 为掩码)。

输入:

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

输出:200,返回 variable 模型,字段见 [POST /v1/project/variables](#post-v1projectvariables)。

调用示例:

curl \
  "https://<your-endpoint>/v1/project/variables/66a9d9b804d8e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY",
  "value": "whsec_9f8e7d6c5b4a",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

PUT /v1/project/variables/{variableId}

更新项目变量的 key/value/secret 标记。secret 变量一经创建不可改回非 secret(反之亦然),只能删除重建。

输入:

参数位置类型必填默认/枚举说明
variableIdpathstring是变量 ID
keybodystring否新键名,最长 255 字符
valuebodystring否新值,最长 8192 字符
secretbodyboolean否secret 标记(不可与创建时相反)

输出:200,返回 variable 模型。

调用示例:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/project/variables/66a9d9b804d8e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "API_KEY_V2",
  "value": "whsec_aa11bb22cc33"
}'

响应示例:

{
  "$id": "66a9d9b804d8e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "key": "API_KEY_V2",
  "value": "whsec_aa11bb22cc33",
  "secret": false,
  "resourceType": "project",
  "resourceId": ""
}

DELETE /v1/project/variables/{variableId}

删除项目变量。下次构建/运行注入时该环境变量消失。

输入:

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

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/project/variables/66a9d9b804d8e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/project/table-mode-conversions

列出项目的全部表模式转换任务(历史与进行中)。

输入:

无请求参数。

输出:200,返回 projectTableModeConversionList 模型:total + conversions[]。conversion 字段结构见 [POST /v1/project/table-mode-conversions](#post-v1projecttable-mode-conversions)。

字段类型说明
totalinteger转换任务总数
conversions[]projectTableModeConversion[]转换任务对象

调用示例:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "conversions": [
    {
      "$id": "conversion-1",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "projectId": "YOUR_PROJECT_ID",
      "sourcePool": "shared-v2",
      "sourceTableMode": "shared",
      "targetPool": "json-v2",
      "targetTableMode": "jsontable",
      "targetTag": "production",
      "status": "created",
      "progressTotal": 100,
      "progressDone": 0,
      "batchSize": 1000,
      "freezeWindowMaxSecs": 3600,
      "retentionSeconds": 2592000,
      "sourceDataDeleteAt": null,
      "sourceDataDeletedAt": null,
      "sourceDataDeleteStatus": "pending",
      "sourceDataDeleteError": null,
      "verificationReport": {},
      "errorMessage": null,
      "frozenAt": null,
      "cutoverAt": null,
      "rollbackDeadline": null
    }
  ]
}

POST /v1/project/table-mode-conversions

发起一次表模式转换(table mode conversion):把项目库表批量迁移到目标表池模式。创建后任务处于 created 状态,需经 [.../start](#patch-v1projecttable-mode-conversionsconversionidstart) 启动回填。

输入:

参数位置类型必填默认/枚举说明
targetTableModebodystring否jsontable / shared目标表模式
targetPoolbodystring否目标池别名;省略时自动匹配可用目标池
targetTagbodystring否目标池标签;空串选择无标签回退池
batchSizebodyinteger否默认 1000回填批大小
freezeWindowMaxSecsbodyinteger否默认 3600切换阶段冻结写入窗口上限(秒)
retentionSecondsbodyinteger否默认 2592000(30 天)切换后源数据保留时长(秒),即回滚窗口

输出:201,返回 projectTableModeConversion 模型。完整字段表:

字段类型说明
$idstring转换任务 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
projectIdstring项目 ID
sourcePool / sourceTableModestring源池别名与源表模式
targetPool / targetTableMode / targetTagstring目标池别名、目标表模式(jsontable / shared)与目标池标签
statusstring状态机:created → backfill(回填)→ verifying(验证)→ frozen/cutover(冻结写入/切换)→ completed,异常为 failed,可 rollback
progressTotal / progressDoneinteger待迁移记录总数与已完成数
batchSizeinteger回填批大小
freezeWindowMaxSecsinteger冻结写入窗口上限(秒)
retentionSecondsinteger切换后源数据保留时长(秒)
sourceDataDeleteAt / sourceDataDeletedAt / sourceDataDeleteStatus / sourceDataDeleteErrorstring源数据清理计划时间/完成时间/状态/失败原因
verificationReportobject验证报告(验证完成后可用)
errorMessagestring失败原因(转换失败时)
frozenAt / cutoverAt / rollbackDeadlinestring冻结写入时间/切换时间/回滚截止时间(ISO 8601)

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/project/table-mode-conversions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000
}'

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "created",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

创建前可先调 [GET .../targets](#get-v1projecttable-mode-conversionstargets) 确认可用目标模式与标签;目标不可用(无匹配池/标签)时创建即失败。

GET /v1/project/table-mode-conversions/targets

列出当前可用目标表模式与池标签,作为发起转换前的选型依据。

输入:

无请求参数。

输出:200,返回 projectTableModeConversionTargetPoolList 模型。

字段类型说明
sourcePool / sourceTableModestring当前源池别名与源表模式
targetModes[]object[]各目标模式及可选标签:tableMode、label、supported(源模式是否支持迁移到该模式)、available(是否存在可选池)、totalPools、tags[](每项含 tag、name、label、poolCount)
totalinteger目标池总数
pools[]object[]目标池明细:alias、status、region、tableMode、tags[]、projectCount

调用示例:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions/targets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetModes": [
    {
      "tableMode": "jsontable",
      "label": "JSON table",
      "supported": true,
      "available": true,
      "totalPools": 2,
      "tags": [
        {
          "tag": "production",
          "name": "production",
          "label": "Production",
          "poolCount": 1
        },
        {
          "tag": "",
          "name": "no-tag",
          "label": "No tag",
          "poolCount": 1
        }
      ]
    }
  ],
  "total": 2,
  "pools": [
    {
      "alias": "json-v2",
      "status": "active",
      "region": "cn-hangzhou",
      "tableMode": "jsontable",
      "tags": [
        "production"
      ],
      "projectCount": 5
    }
  ]
}

GET /v1/project/table-mode-conversions/{conversionId}

获取转换任务详情:状态、回填进度与各阶段时间戳。轮询此端点跟踪任务进度。

输入:

参数位置类型必填默认/枚举说明
conversionIdpathstring是转换任务 ID

输出:200,返回 projectTableModeConversion 模型,字段见 [POST /v1/project/table-mode-conversions](#post-v1projecttable-mode-conversions)。status 为 backfill 时关注 progressDone/progressTotal。

调用示例:

curl \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "backfill",
  "progressTotal": 100,
  "progressDone": 25,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/start

启动转换:开始回填源数据到目标池(状态 created → backfill)。进行中的任务重复 start 返回冲突。

输入:

参数位置类型必填默认/枚举说明
conversionIdpathstring是转换任务 ID

输出:200,返回 projectTableModeConversion(status 变为 backfill)。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/start" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "backfill",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/cutover

执行切换:短暂冻结写入、校验后把流量切到目标池。验证失败时默认拒绝切换,force=true 可跳过验证强制切换(回滚窗口仍保留)。

输入:

参数位置类型必填默认/枚举说明
conversionIdpathstring是转换任务 ID
forcebodyboolean否默认 false验证失败仍强制切换

输出:200,返回 projectTableModeConversion(status 进入 cutover/completed,cutoverAt、rollbackDeadline 填充)。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/cutover" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "force": false
}'

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "completed",
  "progressTotal": 100,
  "progressDone": 100,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": "2020-10-15T06:38:00.000+00:00",
  "cutoverAt": "2020-10-15T06:38:00.000+00:00",
  "rollbackDeadline": "2020-10-15T06:38:00.000+00:00"
}

PATCH /v1/project/table-mode-conversions/{conversionId}/rollback

回滚到源池。仅在 rollbackDeadline(retentionSeconds 决定)内有效;状态机外的回滚返回冲突。

输入:

参数位置类型必填默认/枚举说明
conversionIdpathstring是转换任务 ID

输出:200,返回 projectTableModeConversion(状态回到回滚相关状态机节点)。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/rollback" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "rollback",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": null,
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

PATCH /v1/project/table-mode-conversions/{conversionId}/source-data/delete

删除已完成切换任务的源数据。仅对已完成 cutover 的转换有效;删除后不可再回滚,属不可逆操作。

输入:

参数位置类型必填默认/枚举说明
conversionIdpathstring是转换任务 ID

输出:200,返回 projectTableModeConversion(sourceDataDeleteStatus 从 pending 推进,完成后 sourceDataDeletedAt 填充)。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/project/table-mode-conversions/conversion-1/source-data/delete" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "conversion-1",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "projectId": "YOUR_PROJECT_ID",
  "sourcePool": "shared-v2",
  "sourceTableMode": "shared",
  "targetPool": "json-v2",
  "targetTableMode": "jsontable",
  "targetTag": "production",
  "status": "completed",
  "progressTotal": 100,
  "progressDone": 0,
  "batchSize": 1000,
  "freezeWindowMaxSecs": 3600,
  "retentionSeconds": 2592000,
  "sourceDataDeleteAt": "2020-10-15T06:38:00.000+00:00",
  "sourceDataDeletedAt": null,
  "sourceDataDeleteStatus": "pending",
  "sourceDataDeleteError": null,
  "verificationReport": {},
  "errorMessage": null,
  "frozenAt": null,
  "cutoverAt": null,
  "rollbackDeadline": null
}

错误与边界

与 Server SDK 的对应

service.method端点
Project.listVariables / createVariable / getVariable / updateVariable / deleteVariable/project/variables*
Project.listProjectTableModeConversions / createProjectTableModeConversion / listProjectTableModeConversionTargets / getProjectTableModeConversion/project/table-mode-conversions*
Project.startProjectTableModeConversion / cutoverProjectTableModeConversion / rollbackProjectTableModeConversion / deleteProjectTableModeConversionSourceData.../{conversionId}/start、cutover、rollback、source-data/delete

事实源