创建自定义应用
本章将展示如何设计开发一个在快速开始中出现的“简易博客”应用,以具体案例说明如何开发自定义应用。
简介
当你未在应用市场中发现符合你需求的应用时,或者当你想要设计应用发布到应用市场赚取 RU 时,你可以创建自定义应用。
应用是一些相关功能 API 的组合。比如说我们有一些商品 API,一些订单 API,一些用户 API,它们加起来就组成了一个电商应用。
应用可以在界面上分类展示,易于辨认管理,也可以用文档做统一的描述介绍。它有独立的数据库结构和配置项,用于每个环境使用。
创建
我们现在开始创建自定义应用。
点击左侧目录栏“应用中心”进入到应用中心。可以看到当前组织的所有应用。
控制台应用中心的应用有两种类型,一种是自定义定义,一种是从应用市场安装的第三方应用。第三方应用无法编辑,只能配置应用设置和查看文档使用。自定义应用可以进入编辑。
点击右上角的“创建应用”按钮。在对话框中填写相关信息后确认,我们就成功创建了一个只有基本信息的空应用。
你可以前往一些无版权图标网站找一个合适的应用 logo。比如此处我们用谷歌图标。
应用 ID 是应用的标识,尽量为英文字母。
应用名称要简短易懂,便于用户理解使用。
应用描述为更多详情简介。
应用分类决定应用的分类归属,便于用户查找浏览。
编辑
创建后会自动跳转到刚刚创建应用的编辑页面,我们来编辑它的功能,实现一个完整的应用。
编辑页面分为多个模块,上图是应用的基本信息模块:
- 应用 Logo
- 应用 ID
- 应用名称
- 应用描述
- 应用分类
- 应用标签
- 应用演示地址
- 应用示例代码地址
- 付费类型
- 应用文档
- 应用是否上架到应用市场或下架
- 最新版本
- 发布版本
点击右侧的“保存”按钮可以保存当前修改。
点击右侧的“发布版本”将会创建当前编辑的dev
版本的 API 一个版本镜像。
点击右侧的“上架”/“下架”按钮可以进行应用的上架下架。
更多应用资料的详细说明请查看应用发布章节
其他选项卡可以分别切换为:云数据库,API,配置,自定义函数。
云数据库
在做任何事之前,我们都应该先把数据库结构做好,好的数据库结构决定了应用成功的一半。
当然在这个示例中简易博客的结构非常简单,复杂应用可以在最佳实践中阅读。
切换选项到“云数据库”,现在我们还没有任何数据库表,所以首先创建一张,点击“新建表”:
这里我们输入“表 ID”:Post
;选择“表引擎”:A1
,该引擎决定了这个表有一个按时间自增的唯一 ID;输入“表备注”:文章表
。确认新建后可以看到下面出现了这个数据库,点击查看。
给主键 ID 设置为postId
,备注:文章ID
。
再设置一些文章表的字段如上图所示,然后保存,现在我们就有一张能存文章数据的表了。
更多云数据库的详细说明请查看云数据库)章节
API
有了数据库结构后,我们就可以设计 API 了,现在切换到 API 选项卡,点击“新建 API”:
这里我们输入“API”:getManyPost
,“名称”:查询多个文章
,后面的先省略,直接确认。
可以看到 API 列表中已经出现了getManyPost
,界面出现该 API 的详情:
在 API 详情中,主要是 4 个功能区:
- 基础信息:包含 API 的名称、描述、文档、版本等信息,点击“基础资料”可修改。右侧版本区域可选择版本和创建新版本。
- 基础功能:该版本 API 的开关、成本、定价、返回步骤、token 鉴权、基础权限。
- 请求参数:说明使用该 API 需要哪些参数,用于生成文档和校验。
- 步骤:可以设计这个 API 的逻辑,是最主要的点。
基础信息先不管,基础功能中关闭“需要 token”,这样子这个 API 就可以被未登录的用户访问了。
API 成本会根据步骤不同自动变化,最后再设置一个合理的定价即可,你的 RU 收益等于定价-成本。
返回步骤先不管,默认全部步骤的数据都会返回。
因为这个 API 的作用只是为了查询所有文章,所以不需要参数,这里目标参数就不用填。
更多应用 API 的详细说明请查看应用 API章节
步骤
点击“添加步骤”,然后给刚添加的步骤起个名儿,输入“步骤 ID”:posts
。
选择步骤类型:数据库
,“应用”默认为本应用,“表”的选项中我们可以看到前面创建的Post
表,选择它。
然后选择“动作”为getMany
。意思是查询多条数据。
详细的数据库动作说明请见云数据库文档
我们需要查询返回所有字段,所以不用管“返回数据列”,默认是全部。
排序选择“倒序”,因为我们希望文章按时间倒序排列。
过滤条件略过,此为高级配置,暂时不用。
因为排序方式是倒序,所以末序 ID 的值要比前序的小,查询范围的前值我们选择“值来源”为无限大
,后值末序的“值来源”我们选择无限小
。
此时我们点击保存,就完成了这个简单的 API。
现在来点击“调试”按钮测试该 API:
在左侧选择你希望使用的环境和环境密匙,因为该 API 不需要 token,所以我们不选择携带 token。
当然你也可以用下方请求格式在自己喜欢的 API 客户端进行测试:
// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://环境地域.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "你的环境ID",
"keyid": "你的环境密匙ID",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "getManyPost",
version: "latest",
args: {}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))
得到结果如下:
{
"posts": {
"data": [],
"nextId": null
}
}
可以看到posts
步骤的data
为空数组,因为目前还暂时没有文章数据。
接下来我们创建储存文章的 API:createPost
并按如下设置:
添加两个参数title
和content
,代表请求这个 API 需要这两个参数。
这里主键postId
的值来源我们选择唯一微秒
,因为Post
表用的是A1
引擎,它会自动生成唯一性的微秒 ID。
然后数据列默认选择全部,title
和 content
字段的值来源选择API参数
,值为title
和content
,意思是这个两字段的值从请求中的args.title
和args.content
中获取。而创建时间我们选择时间戳由系统自动生成。
保存后我们来测试一下。
// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://环境地域.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "你的环境ID",
"keyid": "你的环境密匙ID",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "getManyPost",
version: "latest",
args: {
title: "第一篇文章",
content: "文章内容:清林云BaaS 示例",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))
得到结果如下:
{
"post": {
"postId": 1622557712604000
}
}
代表我们已经成功创建了一篇postId
为1622557712604000
的文章。
让我们再用getManyPost
API 查询一下,发现已经能成功查询到数据了:
恭喜你已经学会了基础的 API 设计!
其中“步骤”是涉及知识点最多的一块,如果你想要开发商业级别的应用,还需要再深入学习一下API 步骤文档。
配置及逻辑
当前的 API 和快速开始中的示例还有一点不同,那就是目前的createPost
还是公开的,可以被任何人请求,现在我们就来加一点配置。
切换到“应用配置”选项卡。
这里可以设置一些需要应用购买者使用应用所需要提前配置的数据项,用于 API 的步骤参数设置中。
比如说,我们设计的 API 步骤中有一步是获取微信用户信息,那么就要去请求微信的 api,但是我们没有其他人的微信开放平台密匙无法请求,让开发者在前端传输也是不可能的,那样会暴露平台密匙。这时候配置项就发挥了作用。
使用应用的人提前在这里配置好密匙,应用开发者就可以在步骤中选择值来源:应用配置
去得到他们配置好的数据。
这里“简易博客”的创建文章需要一个简单的密码保护,我们就在下方添加一个字段:postSecret
,类型为 string
,说明写:创建文章的密匙,配置后则会在创建文章时检查密匙
。
完成后点击保存。
此时我们返回 API 页面,将刚才的createPost
修改一下。
在post
步骤的右下角点击小加号,意思是在该步骤前面插入一个新步骤。注意不要点 × ,那个会删除该步骤。
可以看到这个步骤上面插入了一个新步骤,我们命名该步骤为check
,选择类型条件判断
。
“逻辑”选择=
。
“左值”的值来源选择应用配置
,“值”为配置字段postSecret
。
“右值”的值来源选择API参数
,“值”为:postSecret
。
“判断正确”选择继续
。
“判断失败”选择报错
,“值”写:错误的密码
。
点击右上角保存,我们就已经完成了一个简易的身份验证。
然后我们退回到应用中心,点击该应用的“配置”按钮,在配置页面输入一个postSecret
的密码后保存。
再来测试一下createPost
API:
// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第二篇文章",
content: "文章内容:清林云BaaS 示例",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))
失败返回值:
{
"errCode": 1,
"title": "错误的密码",
"type": "createPost",
"detail": "xxx",
"instance": "xxx"
}
发现请求失败了,报错为错误的密码
。
我们将密码放到请求args
中如下所示:
// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第二篇文章",
content: "文章内容:清林云BaaS 示例",
postSecret: "test",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))
成功返回值:
{
"post": {
"postId": 1622485599676000
}
}
发现这次成功了!
另外要怎么实现如同快速开始中的有配置则检测密码,没有配置则不检查密码的功能呢?可以在最前面再加一个“条件判断步骤”。如下所示:
意思是判断是否提前设置了应用配置,如果有则按顺序继续执行,如果没有则跳过 check 步骤的检查,去执行posts
步骤。更多步骤的功能会在后面章节进一步说明。
注:这是一个简单的配置项功能演示,请不要在商业产品中使用该方法。如果你需要保护你的应用安全,请使用“用户中心”这种 token 加密的应用去做。
更多应用配置的详细说明请查看应用配置章节
文档
接下来我们可能要上架这个应用,发布到应用市场,让更多人使用。
但是用户并不能仅仅通过名字和 API 就知道你的应用是干什么的。所以我们要填写相关资料并写一个简单的文档。
切换到“应用信息”选项卡。
依据提示填写信息,简单介绍一下你的应用,保存即可。如前面的图所示:
然后,我们需要发布版本,否则只会有dev
版本的 API 提供使用,发布后就有了正式版本的 API。
最后,如果你希望将该应用上架到应用市场,供其他用户也能安装使用,赚取 RU,那么点击右上角的“上架”按钮,我们的应用就发布到应用市场了,去查看一下吧!
应用数据
在创建应用后,左侧应用栏将会出现该应用,点击可以到该应用的数据页。
当前端调用该应用 API 时,可能会产生相关数据,在数据页可以对数据进行查询、编辑、删除等操作。
另外,我们将来也会推出“后台微前端”功能,应用开发者可以自行开发跟应用配套的后台前端代码,然后采用微前端的方式接入到清林云控制台来。
基础的数据操作可以由应用数据页完成,高级的操作由微前端模块实现。
这样,清林云 BaaS 就成功做到了为客户提供应用的界面管理能力,相当于包含了各种各样的 SaaS 软件。
所以说,清林云 BaaS 不仅仅是一个 BaaS 云平台,也是一个企业的操作系统。
更多
另外,API 的设计还有更多高级功能,多种多样的步骤类型以及自定义函数等,我们进入下面的章节学习。