添加 APIs 自定义方法

一些用户级别的 APIs 支持添加自定方法

方法入参​

入参 即用于描述上述函数 params 的结构. 若函数无参数, 则不填写.

在微搭应用编辑器中使用数据源时, 会使用到数据源方法 入参 中描述的结构信息, 比如:

1. 数据源变量的定义中, 会根据入参提示的结构生成变量的配置表单(提示出字段的中文名, 根据不同类型显示不同的表单控件)
2. 表单容器关联数据源方法后, 会根据入参结构信息生成完整的表单, 如: 入参中 字段名称 会变成表单输入框的 字段标题, 入参中字段的 数据类型 可能会用于生成不同类型的输入框(手机号输入框/邮件输入框/开关选择器等), 入参中 枚举 信息会用于生成 多选输入框 或者下拉选框, 等等.

以上只是举例说明, 数据源方法入参在微搭应用编辑器中的使用场景很多, 故在填写 入参 时信息提供的越完整, 在微搭应用编辑器中使用时则越方便.

公共变量​

公共变量提供了一种跨方法的变量调用方式，可支持在多个APIs中进行引用，一般适用于静态变量如APIToken，ClientID等常量值，可以使用模板{{ }}方式引用。 例如设置公共变量ClientId, 使用{{vars.ClientId}}形式引用。

方法类型​

数据源方法根据实现方式, 分为两种:

• HTTP 请求: 仅外部数据源中提供该类型方法, 可简单对接第三方http接口, 可以通过简单的配置 HTTP 请求地址 、方法 、参数等等 即可往完成方法的配置
• 云函数: 通过编写js代码来实现更灵活的功能, 包括发起 HTTP 请求

HTTP请求​

HTTP请求底层也基于云开发的云函数能力封装, 提供了可视化、快速接入第三方 HTTP API 的功能.

HTTP 配置中配置的是 HTTP 请求底层的请求参数, 在配置 URL、 Query 和 Headers 的 value 、Body(仅请求方法Method为 POST 和 PUT时可配置) 可以使用模版 {{ }} 方式引用下述字段:

• 引用入参中定义的字段, 使用 {{ params.字段标识 }} 形式
• 引用环境变量信息, 使用 {{ env.字段标识 }} 形式, 如 {{ env.openId }}
• 引用公共量信息, 使用 {{ vars.字段标识 }} 形式

云函数​

云函数是一种特殊的Javascript函数, 底层基于云开发的云函数能力封装, 最终会运行在服务器端的 Nodejs 10.15 环境中, 可以通过函数的 context参数来访问 云开发node sdk 的所有能力。

云函数编写需注意以下几点:

• 云函数必须使用 module.exports 导出
• 云函数只接受两个参数:
  • params: 函数接受的参数, 即在方法入参描述的结构. 需保证实际使用时 params 与 方法入参 描述的结构一致
  • context: 云函数上下文对象, 方便在云函数中实现各种功能, 具体结构可参考 云函数context
• 云函数返回的结果, 即 return 语句返回的内容应当是一个 对象, 切应当与 方法出参 描述的一致
• 云函数中若发现错误, 可以直接throw new Error('xxxx')来抛出错误, 也可以使用 throw new TCBError(code, 'msg') 抛出错误并自定义错误代码.
• 云函数开发过程中可以在通过 console.log('xxxx') 输出日志, 再使用 方法测试 来测试查看日志
• 云函数运行的环境为 Nodejs 10.15, 注意不要使用当前版本不支持的js特性, 比如可选链等.

下边是为自建数据源添加自定义的创建方法的示例代码:

假设该自建数据源有两个自定义数据源字段 name、email, 以下代码将对参数进行校验, 并限制只能使用 qq 邮箱, 并最后返回新记录的ID

module.exports = async function (params, context) {
  // 输出日志, 方便调试, 在 方法测试 中可以看到日志
  console.log('params', params);
  if (!params.name || !params.email) throw new TCBError(1, 'name 或 email 不能为空');
  if (!/@qq\.com$/i.test(params.email)) throw new TCBError(2, '仅支持使用qq邮箱');
  const now = Date.now();
  // 追加创建时间、更新时间
  const newParams = Object.assign({}, params, {
    createdAt: now,
    updatedAt: now,
  });

  // 使用云开发的 collection 相关API添加记录
  const result = await context.collection.add(newParams);
  // 返回新记录的ID信息
  return { _id: result.id };
}

自定义代码 context​

context 为低码向云函数提供的上下文对象, 里面提供了操作数据库、调用云开发云函数的对象以及一些有用的环境变量.

环境变量​

环境说明​

微搭生成出的应用分为两种:

• 体验应用: 用于在微搭中开发测试应用. 在应用编辑器中通过预览区的 实时真实预览 开关、编辑器顶部的 预览 以及顶部 发布对话框 中的发布方式 体验得到的应用均属于 体验应用.
• 正式应用: 用于正式发布给终端用户使用. 在应用编辑器通过顶部 发布对话框 中的发布方式 正式 得到的应用即为 正式应用.

体验应用 和 正式应用 调用的数据源及微搭后端支撑服务的数据则是互相隔离、互不影响的, 分别会调用到不同的后端环境:

• 体验环境: 被 体验应用 调用.
• 正式环境: 被 正式应用 调用.

用户在微搭的数据源管理中, 新建/编辑保存数据源的时候, 则会自动更新 体验环境 的数据源. 当数据源测试验证通过后, 点击数据源管理中的 立即发布 按钮则会将数据源更新至 正式环境.

方法测试​

数据源的方法(http请求及云函数)配置好后, 使用方法测试进行测试验证. 在「提交参数」中填写测试使用的参数, 点「运行测试」即可测试, 在测试输出的结果中可以看到方法运行的日志信息. 测试通过后, 点击 出参映射 即可快速填写 方法出参

在编写云函数的时候, 可以代码中使用 console.log 来输出日志, 在方法测试的「日志」中可以查看到日志信息.

方法出参​

云函数代码最后返回的结果即为函数出参.

在微搭应用编辑器中使用数据源时, 会使用到数据源方法出参中描述的结构信息, 比如:

1. 数据源变量会使用关联的数据源方法的出参生成示例数据
2. 表格关联数据源方法后, 会根据出参结构信息生成表格的表头信息

以上只是举例说明, 数据源方法出参在微搭应用编辑器中的使用场景很多, 故在填写 出参 时信息提供的越完整, 在微搭应用编辑器中使用时则越方便.

HTTP方法出参中的字段映射​

在HTTP方法中, 使用 方法测试 的出参映射后, 填充的出参结构与HTTP请求原始返回结果结构一致.

HTTP方法的出参提供了 字段映射 的功能, 可对最终前端应用拿到的数据结构进行调整:

• 可以删除出参中不需要的字段, 删除后, 前端应用调用该方法时则不会返回相应字段
• 可以编辑出参中的字段, 字段中的 字段标识 为前端应用使用数据源时拿到的字段名称, 而 字段映射 则为该字段对应HTTP请求原始返回结果的字段路径, 即: 将 字段映射 路径所对应的值赋值给名称为 字段标识 的字段
  • 修改 字段标识, 修改后, 前端应用拿到的字段名称则为修改后的名称
  • 修改 字段映射, 修改后, 当前字段则在原始响应结果中从 字段映射 所描述的路径里取值

修改 字段映射 需要注意以下几点:

• 字段映射的值为对象的路径字符串, 如: abc 、abc.ed 、abc.ed.cf[0].g. 使用时注意路径是存在的, 否则将映射失败, 最终导致该方法报错
• 可使用代表原始响应结果的特殊的字符串 $root, 在填写字段映射时 $root.abc 与 abc 效果一致, 一般可以省略 $root
• 在需要对对象数组进行映射时, 可使用代表映射时循环的元素自身 $item(可使用 $item.xxx 来指定对象某个字段) 及 循环索引序号 $index(从0开始). 注意, 数组字段需映射到原始响应结果中对应的对象数组

常见问题​

如何在云函数中使用第三方依赖​

目前在云函数中可以使用 request 和 @cloudbase/js-sdk 这两个内置库. 暂时未提供使用其他依赖的方式.

直接使用 node 函数 require 引入相关依赖即可, 如:

const request = require('request');

module.exports = function (params, context) {
  return new Promise(function (resolve, reject) {
    request('xxxxx', ...)
  })
};

如何在云函数中发起 HTTP 请求​

可借助npm 包 request 来实现, 具体使用可参考下边代码:

/**
* 使用 npm 包 request 发送HTTP请求, 详细使用文档可以参考
*  https://github.com/request/request#readme
*/
const request = require('request');

/** 依据 http状态码 判断请求是否成功 */
function isSuccessStatusCode(code) {
 return code >= 200 && code < 300;
}

module.exports = function (params, context) {
  // params 即为入参定义的结构, 可以在 request 的请求配置中使用 params
  return new Promise(function (resolve, reject) {
    request(
      {
        url: 'https://reqres.in/api/users?page=1&per_page=3',
        method: 'GET',
        // 将 json 为 true, 响应结果的 body 会被自动转换为对象,
        //   在POST请求中, 也会自动设置将 Content-Type 设置为 application/json
        json: true
      },
      function (err, response, body) {
        if (err) return reject(err);
        if (!isSuccessStatusCode(response.statusCode))
          return reject(new Error('request failed: ' + response.statusCode));
        return resolve(body);
      }
    );
  });
};

如何为使用模版创建的第三方数据源集成新的方法​

在创建外部数据源时, 若使用非空白模版来创建, 则在该数据源云函数的 context 上会多出 httpAuth 对象. 通过 context.httpAuth 对象, 可以访问该类型外部数据源的认证信息.

context.httpAuth 类型定义如下:

IAuthData​

下述除 authInfo外的字段均使用 authInfo 构造而来, 为方便使用而封装, 亦可自行阅读第三方官方接口文档来构造.

腾讯会议认证信息​

腾讯文档认证信息​

自定义云函数示例:

/**
 * 创建腾讯会议, 官方接口文档 https://cloud.tencent.com/document/product/1095/42417
 */
const request = require('request');

/** 依据 http状态码 判断请求是否成功 */
function isSuccessStatusCode(code) {
  return code >= 200 && code < 300;
}

module.exports = async function (params, context){
  const { subject, type, start_time, end_time, password } = params;
  // request 请求配置信息
  const requestConfig = {
    uri: 'https://api.meeting.qq.com/v1/meetings',
    method: 'POST',
    body: {
      instanceid: 1,
      subject,
      type,
      start_time: `${Math.floor(start_time / 1000)}`,
      end_time: `${Math.floor(end_time / 1000)}`,
      password,
    },
    // 将 json 为 true, 响应结果的 body 会被自动转换为对象,
    //   在POST请求中, 也会自动设置将 Content-Type 设置为 application/json
    json: true
  };
  // 获取认证信息
  const authData = await context.httpAuth.getAuthData(requestConfig);
  // 合并配置信息
  const finalRequestConfig = mergeAuthData(requestConfig, authData);
  // params 即为入参定义的结构, 可以在 request 的请求配置中使用 params
  return new Promise(function (resolve, reject) {
    // 注意: request 的回掉函数为 async 函数, 因函数内有一个 await 调用
    request(finalRequestConfig, async function (err, response, body) {
        if (err) return reject(err);
        if (!isSuccessStatusCode(response.statusCode)) {
          // 失败时, body 中会包含详细错误信息
          return reject(new Error(`request failed: code: ${response.statusCode}, msg: ${JSON.stringify(body)}`));
        }
        let result = body
        // 数据源实际未针对 腾讯会议 提供 transformResponse, 下边这段代码亦可以去掉
        if (context.httpAuth.transformResponse) {
          result = await context.httpAuth.transformResponse(body, response);
        }
        // 成功时 body 为空
        return resolve(result);
      }
    );
  });
}

/**
 * 将request 请求配置与 IAuthData 中的进行合并
 */
function mergeAuthData(requestConfig, authData) {
  const newConfig = Object.assign({}, requestConfig);
  if (authData.uri) {
    newConfig.uri = authData.uri;
  }
  if (authData.body) {
    if (requestConfig.form) {
      newConfig.form = Object.assign(newConfig.form || {}, authData.body);
    } else if (!newConfig.body || typeof newConfig.body === 'object') {
      newConfig.body = Object.assign(newConfig.body || {}, authData.body);
      // 再次设置 contentType 为json, 避免 requestConfig.body 为空时未设置 contentType 的问题
      newConfig.json = true;
    }
  }
  if (authData.headers) {
    newConfig.headers = Object.assign(newConfig.headers || {}, authData.headers);
  }

  if (authData.qs) {
    newConfig.qs = Object.assign(newConfig.qs || {}, authData.qs);
  }
  return newConfig;
}

内置第三方数据源的官方API文档​

腾讯文档:

• 对外开放接口：https://docs.qq.com/open/wiki/sheetapi/v2/

目前微搭仅接入了 sheet 相关的接口, 可根据接口文档接入其他其他API.

腾讯会议:

• 对外开放接口：https://cloud.tencent.com/document/product/1095/42417

微搭采用 OAuth2.0 方式接入的腾讯会议, 目前只有会议管理相关API支持 OAuth2.0 方式调用, 会议管理相关API也已全部内置进会议的数据源模版中.
会议管理相关API的参数非常丰富, 为方便用户使用, 微搭侧封装时仅提供了必填的常用参数. 若需要使用微搭模版中未支持的参数, 可参考腾讯会议官方API文档来修改会议数据源中对应方法的封装.