轻服务 SDK
轻服务 SDK,您可以通过这个 SDK 调用轻服务中的函数、上传文件和进行便捷地用户管理。SDK 目前支持在浏览器和 NodeJS 环境调用。
安装
NPM
$ npm install --save @byted-light/bcloud --registry=http://bnpm.byted.org/
YARN
$ yarn add @byted-light/bcloud --registry=http://bnpm.byted.org/
浏览器引入
<script type="text/javascript" src="https://unpkg.pstatp.com/byted-light/bcloud/1.0.0/dist/bcloud-browser.min.js"></script>
小程序
手动导入
- 点击打开 https://unpkg.pstatp.com/byted-light/bcloud/1.0.0/dist/bcloud-mp.min.js 并下载 JS 文件,移动到小程序
libs
目录。 - 在小程序中:
const BCloud = require('./libs/bcloud-mp.min.js');
WePY 和 mpvue
在 WePY 或 mpvue 中使用 SDK 时,可以直接通过 NPM 或 YARN 来安装。参见上方 NPM 或 YARN 章节。
配置域名白名单
如果要在线上小程序中使用 SDK,需要先配置域名白名单(参见 网络使用说明)。具体操作方法为:
- 登录 微信公众平台;
- 前往 设置 > 开发设置 > 服务器域名,点击 修改 按钮;
- 在「request 合法域名」项中填入 cloudapi.bytedance.com。
Quick Start
以下是一个使用 SDK 进行开发的简单例子:
const BCloud = require('bcloud');
const myServiceId = 'ttxxxxx';
const fnName = 'hello';
const bc = new BCloud({
serviceId: myServiceId,
});
bc.run(fnName, { message: 'world' })
.then(data => {
})
.catch(error => {
});
下面,将详细介绍 SDK 的使用。
初始化
const BCloud = require('bcloud');
const myServiceId = 'ttxxxxx';
const bc = new BCloud({
serviceId: myServiceId,
});
用户
通过 bc.user
可以访问和「用户」相关的所有功能,具体API如下:
注册
user.signUp(username: string, password: string, attrs: object = {}) => Promise
使用「用户名 + 密码」注册一个新用户,成功后的用户信息会保存在轻服务应用数据库的 _user
表中。
参数名 | 说明 | 类型 | 是否必填 | 默认值 |
---|
username | 新用户的用户名 | string | 是 | - |
password | 新用户的密码 | string | 是 | - |
attrs | 用户的附加属性,会同时被记录到 _user 表中 | object | 否 | {} |
例如,注册一个用户的示例例代码如下(用户名 peter_pan
密码 loves_bcloud
):
bc.user.signUp(
'peter_pan',
'loves_bcloud',
{ email: 'peter@cloud.bytedance.com' }
)
.then(() => {
})
.catch((error) => {
});
用户名密码登录
user.logIn(username: string, password: string) => Promise
参数名 | 说明 | 类型 | 是否必填 | 默认值 |
---|
username | 登录用户的用户名 | string | 是 | - |
password | 登录用户的密码 | string | 是 | - |
示例:
bc.user.logIn('peter_pan', 'loves_bcloud')
.then(() => {
})
.catch((error) => {
});
第三方平台 OAuth 登录
通过这个 API 可以快速便捷地进行第三方 OAuth 授权登录,具体配置及使用指南请查看 OAuth 使用指南。
user.logInByOAuth(options: object) => Promise
options
具体参数如下:
platform
:必填,平台名称。目前仅支持 bytedanceInternal
(头条内部 SSO),后续会添加其他平台支持。mode
:可选,验证页面打开模式。支持 popup
(弹窗模式,建议采用此模式)和 redirect
(重定向模式,在不支持弹窗的环境中可采用此模式),默认为 popup
。redirectURL
:可选,仅 mode
为 redirect
时生效。代表 OAuth 完成后跳转回的页面,默认为发起请求的初始页面。
通过弹窗模式调用示例:
await bc.user.logInByOAuth({
platform: 'bytedanceInternal'
}).then(() => {
}).catch(() => {
});
使用弹窗模式时,验证页面会以新窗口的形式打开。当用户授权完成后,此新窗口会自动关闭,此时你即可在代码的 then
回调中得到登录成功的消息。
通过重定向模式调用示例:
bc.user.logInByOAuth({
platform: 'bytedanceInternal',
mode: 'redirect',
redirectURL: 'https://my.domain/someRedirectPage'
});
通过重定向模式调用后,当前页面会直接被重定向到用户授权页面,整个授权完成后,该页面会被重定向到你指定的 redirectURL
中(示例中即为 https://my.domain/someRedirectPage
,若未指定则跳回发起请求页)。此时,在页面中你可以通过调用 bc.user.isLogin
得知用户是否已经完成登录。
判断用户是否登录
user.isLogin() => Promise<boolean>
示例:
bc.user.isLogin()
.then((isLogin) => {
if (isLogin) => {
} else {
}
});
登出
user.logOut() => void
用户登出时,SDK 会自动清理缓存的 SessionToken
。
示例:
bc.user.logOut();
bc.user.isLogin((isLogin) => {
console.log(isLogin);
});
文件
通过 bc.file
可以访问和「文件」相关的功能,如下:
文件上传
file.upload(filename: string, file: string | object | Blob | Uint8Array) => Promise
如果上传文件成功,Promise
返回的结果中将包含 url
字段,代表该文件的网络地址。
通过 SDK 上传文件时请注意:
- 文件名必须设置,且尽量包含正确的扩展名。轻服务会通过扩展名来判断文件类型,以便进行有效地处理。
- 不必担心文件名冲突。因为轻服务会为每个上传文件添加唯一的 ID,所以即便上传多个同名文件,返回的 URL 也各自独立。
- 文件大小不能超过 10MB。
参数名 | 说明 | 类型 | 是否必填 | 默认值 |
---|
filename | 上传文件的文件名 | string | 是 | - |
file | 上传文件的内容 | `string | object | Blob |
通过 Base64 字符串上传文件
bc.file.upload('text_base64.txt', 'SGVsbG8gV29ybGQ=')
.then((data) => {
console.log(data.url);
})
.catch((error) => {
});
通过本地文件对象上传文件(仅浏览器端)
在浏览器环境下,大多数情况下会让用户通过文件选择框选取文件,这时候可以直接通过本地的文件对象来上传文件。例如,页面上有一个文件选择框如下:
<input type="file" id="fileInput" />
使用如下代码可以完成上传操作:
const fileInputElement = document.getElementById('fileInput');
if (fileInputElement.files.length > 0) {
const file = fileInputElement.files[0];
const filename = file.name;
bc.file.upload(filename, file)
.then((data) => {
console.log(data.url);
})
.catch((error) => {
});
}
通过文件路径上传文件(仅 Node.js 和小程序端)
const path = require('path');
const file = { path: path.join(__dirname, 'PATH_TO_FILE') };
bc.file.upload('text_path_node.txt', file)
.then((data) => {
console.log(data.url);
})
.catch((error) => {
});
wx.chooseImage({
success(res) {
const file = {
path: res.tempFilePaths[0]
};
bc.file.upload('text_path_mp.txt', file)
.then((data) => {
console.log(data.url);
})
.catch((error) => {
});
}
});
通过 Uint8Array 对象上传文件
const file = Uint8Array.from([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]);
const file = fs.readFileSync('PATH_TO_FILE');
bc.file.upload('text_array.txt', file)
.then((data) => {
console.log(data.url);
})
.catch((error) => {
});
调用云函数
run(fnName: string, params: object = {}, options: RequestOptions = {}) => Promise
根据 fnName
调用该服务中的云函数,请首先确保云端服务中存在对应的函数名,更多和云函数相关的信息可查看 认识云函数。
参数名 | 说明 | 类型 | 是否必填 | 默认值 |
---|
fnName | 调用的云函数名 | string | 是 | - |
params | 传递给云函数的参数信息,在云函数中也通过 params 对象获取 | object | 否 | {} |
options | 请求的附带信息 | RequestOptions | 否 | {} |
RequestOptions
的结构如下:
type RequestOptions = AxiosRequestConfig = {
headers?: object,
method?: string,
params?: object,
...
};
完整的 options
参数信息可参考:https://github.com/axios/axios#request-config
例如,调用一个位于轻服务中的云函数 hello
,并且传递一段消息:
bc.run('hello', { message: 'bcoud' })
.then((data) => {
})
.catch((error) => {
});
更新日志
见 轻服务 SDK 更新日志