bcloud

轻服务 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>

小程序

手动导入

1. 点击打开 https://unpkg.pstatp.com/byted-light/bcloud/1.0.0/dist/bcloud-mp.min.js 并下载 JS 文件，移动到小程序 libs 目录。
2. 在小程序中：

   // 注意填写正确的相对路径
   const BCloud = require('./libs/bcloud-mp.min.js');
   

WePY 和 mpvue

在 WePY 或 mpvue 中使用 SDK 时，可以直接通过 NPM 或 YARN 来安装。参见上方 NPM 或 YARN 章节。

配置域名白名单

如果要在线上小程序中使用 SDK，需要先配置域名白名单（参见 网络使用说明）。具体操作方法为：

1. 登录 微信公众平台；
2. 前往 设置 > 开发设置 > 服务器域名，点击 修改 按钮；
3. 在「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'; // 在轻服务中创建的服务 ID

// 初始化轻服务实例
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: '[e-mail]' }
)
  .then(() => {
    // 注册并登录成功，之后的调用中可在云函数中通过 context.user 拿到对应用户信息
  })
  .catch((error) => {
    // 注册失败
  });

用户名密码登录

user.logIn(username: string, password: string) => Promise

参数名	说明	类型	是否必填	默认值
username	登录用户的用户名	string	是	-
password	登录用户的密码	string	是	-

示例：

bc.user.logIn('peter_pan', 'loves_bcloud')
  .then(() => {
    // 登录成功，之后的调用中可在云函数中通过 context.user 拿到对应用户信息
  })
  .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(() => {
  // 登录成功，之后的调用中可在云函数中通过 context.user.bytedanceInternal 拿到对应用户在 bytedanceInternal 平台的第三方信息
}).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);   // fasle
});

文件

通过 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 和小程序端）

• 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]);

// 在 Node.js 环境中，直接通过文件系统读取到的对象也可以作为参数传递
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,    // 请求方法，不指定的话默认为 POST
  params?: object,    // URL 参数，云函数中会体现在 context.query 中
  ... // 完整参数请参考下方链接
};

完整的 options 参数信息可参考：https://github.com/axios/axios#request-config

例如，调用一个位于轻服务中的云函数 hello，并且传递一段消息：

bc.run('hello', { message: 'bcoud' })
  .then((data) => {
    // 云函数调用成功
  })
  .catch((error) => {
    // 调用失败，进行错误处理
  });

更新日志

见 轻服务 SDK 更新日志