FnProject API v2 接口详解与使用指南

概述

FnProject 是一个开源的 Serverless 平台，提供了一套完整的 API 接口用于管理应用程序、函数和触发器。本文将对 FnProject API v2 版本进行详细解析，帮助开发者理解和使用这套接口。

基础信息

API 基础路径为 /v2，支持 HTTP 和 HTTPS 协议。所有请求和响应默认使用 JSON 格式。

核心资源

API 主要围绕三个核心资源展开：

1. 应用程序(Apps)：函数和触发器的容器
2. 函数(Fns)：实际执行的代码单元
3. 触发器(Triggers)：触发函数执行的事件源

应用程序(Apps)接口

获取应用程序列表

端点：GET /apps

参数：

• cursor：分页游标
• perPage：每页数量
• name：按名称过滤

响应：返回应用程序列表，包含分页信息

创建应用程序

端点：POST /apps

请求体：应用程序定义对象，包含：

• name：应用程序名称
• config：应用程序配置
• annotations：应用程序注解
• syslog_url：日志输出地址
• shape：处理器架构类型

响应：返回创建成功的应用程序详情

获取单个应用程序

端点：GET /apps/{appID}

参数：appID 路径参数

响应：返回指定应用程序的详细信息

更新应用程序

端点：PUT /apps/{appID}

参数：appID 路径参数 请求体：需要更新的应用程序属性

响应：返回更新后的应用程序详情

删除应用程序

端点：DELETE /apps/{appID}

参数：appID 路径参数

响应：204 表示删除成功

函数(Fns)接口

获取函数列表

端点：GET /fns

参数：

• appID：所属应用程序ID
• cursor：分页游标
• perPage：每页数量
• name：按名称过滤

响应：返回函数列表，包含分页信息

创建函数

端点：POST /fns

请求体：函数定义对象，包含：

• name：函数名称
• app_id：所属应用程序ID
• image：容器镜像地址
• memory：内存限制(MiB)
• timeout：执行超时时间(秒)
• idle_timeout：空闲超时时间(秒)
• config：函数配置
• annotations：函数注解
• shape：处理器架构类型

响应：返回创建成功的函数详情

获取单个函数

端点：GET /fns/{fnID}

参数：fnID 路径参数

响应：返回指定函数的详细信息

更新函数

端点：PUT /fns/{fnID}

参数：fnID 路径参数 请求体：需要更新的函数属性

响应：返回更新后的函数详情

删除函数

端点：DELETE /fns/{fnID}

参数：fnID 路径参数

响应：204 表示删除成功

触发器(Triggers)接口

获取触发器列表

端点：GET /triggers

参数：

• appID：所属应用程序ID
• fnID：所属函数ID
• cursor：分页游标
• perPage：每页数量
• name：按名称过滤

响应：返回触发器列表，包含分页信息

创建触发器

端点：POST /triggers

请求体：触发器定义对象，包含：

• name：触发器名称
• type：触发器类型(如schedule, http, queue)
• source：触发器源URI
• fn_id：关联函数ID
• app_id：关联应用程序ID
• annotations：触发器注解

响应：返回创建成功的触发器详情

获取单个触发器

端点：GET /triggers/{triggerID}

参数：triggerID 路径参数

响应：返回指定触发器的详细信息

更新触发器

端点：PUT /triggers/{triggerID}

参数：triggerID 路径参数 请求体：需要更新的触发器属性

响应：返回更新后的触发器详情

删除触发器

端点：DELETE /triggers/{triggerID}

参数：triggerID 路径参数

响应：204 表示删除成功

数据模型详解

应用程序(App)模型

{
  "id": "string",  // 只读
  "name": "string",  // 只读
  "config": {},  // 键值对配置
  "annotations": {},  // 注解
  "syslog_url": "string",  // 可为空
  "created_at": "date-time",  // 只读
  "updated_at": "date-time",  // 只读
  "shape": "GENERIC_X86|GENERIC_ARM|GENERIC_X86_ARM"  // 处理器架构
}

函数(Fn)模型

{
  "id": "string",  // 只读
  "name": "string",
  "app_id": "string",
  "image": "string",
  "memory": "uint64",  // MiB
  "timeout": "int32",  // 默认30秒
  "idle_timeout": "int32",  // 默认30秒
  "config": {},  // 键值对配置
  "annotations": {},  // 注解
  "created_at": "date-time",  // 只读
  "updated_at": "date-time",  // 只读
  "shape": "GENERIC_X86|GENERIC_ARM|GENERIC_X86_ARM"  // 处理器架构
}

触发器(Trigger)模型

{
  "id": "string",  // 只读
  "name": "string",
  "type": "string",  // 如schedule, http, queue
  "source": "string",  // URI路径
  "fn_id": "string",  // 只读
  "app_id": "string",  // 只读
  "annotations": {},  // 注解
  "created_at": "date-time",  // 只读
  "updated_at": "date-time"  // 只读
}

最佳实践

1. 命名规范：应用程序和函数名称只能包含字母数字、-和_字符
2. 配置管理：使用config字段存储环境变量和配置信息
3. 日志收集：通过syslog_url配置集中式日志收集
4. 资源分配：合理设置memory和timeout参数
5. 处理器架构：根据函数需求选择合适的shape值

错误处理

所有接口都可能返回以下错误：

• 400：参数缺失或无效
• 404：资源不存在
• 409：名称冲突
• 500：服务器内部错误

错误响应格式：

{
  "message": "错误描述",
  "error": {
    "detail": "详细错误信息"
  }
}

通过本文的详细解析，开发者可以全面了解 FnProject API v2 的功能和使用方法，从而更好地构建和管理 Serverless 应用。