Skip to content

Latest commit

 

History

History
467 lines (327 loc) · 11.8 KB

API.md

File metadata and controls

467 lines (327 loc) · 11.8 KB
Raw

Wafer 服务端 SDK API 文档

命名空间

const qcloud = require('wafer-node-sdk')(options)

SDK 初始化配置

require('wafer-node-sdk')(options)

该方法用于初始化 SDK 需要使用的各种配置项，需先于其他 API 调用。

参数
  • appId - 可选。微信小程序的 App id
  • appSecret - 可选。微信小程序的 App secret
  • useQcloudLogin - 必填。是否使用腾讯云代理登录小程序。会话登录需要使用小程序的 App id 和 App secret 来解密用户信息，腾讯云提供使用腾讯云 App id 和 App secret 代理请求微信进行解密。如果该项为 false，则需填写微信小程序 App id 和 App secret。默认为 true
  • mysql - 必填。MySQL 配置。不填则使用小程序解决方案分配机器中默认的 MySQL，若使用自行部署的 MySQL 数据库，则需提供一个类型为 object 的配置，具体配置项如下：
    • host - 必填。MySQL 主机名
    • user - 必填。MySQL 用户名
    • db - 必填。MySQL 数据库名
    • pass - 必填。MySQL 密码，若使用了腾讯云微信小程序解决方案，开发环境下，MySQL 的初始密码为您的微信小程序 appid
    • port - 选填。MySQL 端口（默认：3306）
    • char - 选填。MySQL 编码
  • cos - 必填。腾讯云对象存储配置信息，用于上传模块使用。
    • region - 必填。COS 的地域，具体查看：https://cloud.tencent.com/document/product/436/6224
    • fileBucket - 必填。COS 的 bucket 名
    • uploadFolder - 必填。COS 上传文件夹名
    • maxSize - 选填。COS 上传最大大小，默认 5M (单位：M)
    • field - 选填。COS 上传是 field 名称，默认为 file
  • serverHost - 必填。当前服务器的 hostname
  • tunnelServerUrl - 必填。信道服务器地址
  • tunnelSignatureKey - 必填。信道服务签名密钥
  • qcloudAppId - 必填。腾讯云 AppId
  • qcloudSecretId - 必填。腾讯云 SecretId
  • qcloudSecretKey - 必填。腾讯云 SecretKey
  • wxMessageToken - 必填。微信客服消息通知 token
  • wxLoginExpires - 可选。微信登录态有效期，默认 7200 秒（单位：秒）

如果购买了腾讯云小程序解决方案，配置项中 serverHost, tunnelServerUrl, tunnelSignatureKey, qcloudAppId, qcloudSecretId, qcloudSecretKey, wxMessageToken 由腾讯云自动下发到您的开发环境和生产环境上。

自动下发的 SDK 配置文件地址： /data/release/sdk.config.json

返回值

初始化之后会返回一个 SDK 的实例，提供以下所有的 API。

用户登录和校验

qcloud.auth.authorization(req)

登录授权接口，该接口会返回登录状态和用户信息，并将用户信息和登录态储存到 MySQL 里

参数
  • req - http.IncomingMessage 实例化对象
返回值

Promise 对象，.then 中可以得到登录状态和用户信息

返回数据格式
{
  loginState: number,  // 1表示登录成功，0表示登录失败
  userinfo: object
}
调用示例
// express
module.exports = (req, res) => {
  qcloud.auth.authorization(req).then(result => {
    // result : {
    //   loginState: 0  // 1表示登录成功，0表示登录失败
    //   userinfo: { // 用户信息 }
    // }
  })
}

qcloud.auth.validation(req)

登录态校验接口，该接口会从 MySQL 取出用户信息，校验登录态，返回登录状态和用户信息

参数
  • req - http.IncomingMessage 实例化对象
返回值

Promise 对象，.then 中可以得到登录状态和用户信息

返回数据格式
{
  loginState: number,  // 1表示登录成功，0表示登录失败
  userinfo: object
}
调用示例
// express
module.exports = (req, res) => {
  qcloud.auth.validation(req).then(result => {
    // result : {
    //   loginState: 0  // 1表示登录成功，0表示登录失败
    //   userinfo: { // 用户信息 }
    // }
  })
}

qcloud.auth.authorizationMiddleware(ctx[, next])

用户登录的 Koa 中间件，登录信息将会被写进 ctx.state.$wxInfo

参数

  • ctx - Koa Context Koa 上下文
  • next

调用示例

const { auth: { authorizationMiddleware } } = qcloud

// 颁发登录态
router.get('/login', authorizationMiddleware, ctx => {
  console.log(ctx.state.$wxInfo)
  // {
  //   loginState: 0  // 1表示登录成功，0表示登录失败
  //   userinfo: { // 用户信息 }
  // }
})

qcloud.auth.validationMiddleware(ctx[, next])

用户登录态校验的 Koa 中间件，登录信息将会被写进 ctx.state.$wxInfo

参数

  • ctx - Koa Context Koa 上下文
  • next

调用示例

const { auth: { validationMiddleware } } = qcloud

// 校验登录态
router.get('/user', validationMiddleware, ctx => {
  console.log(ctx.state.$wxInfo)
  // {
  //   loginState: 0  // 1表示登录成功，0表示登录失败
  //   userinfo: { // 用户信息 }
  // }
})

信道服务

qcloud.tunnel.getTunnelUrl(req)

获取信道地址接口。调用这个接口需要用户已经登录，请查看客服端示例

参数

  • req - http.IncomingMessage 实例化对象
返回值

Promise 对象，.then 中可以获得信道服务地址

返回数据格式
{
  tunnel: {
    tunnelId: string,    // 信道ID
    connectUrl: string   // 信道连接地址
  },
  userinfo: object       // 用户信息
}
调用示例
// express
module.exports = (req, res) => {
  qcloud.tunnel.getTunnelUrl(req).then(result => {
    // {
    //   tunnel: {
    //     tunnelId: string,    // 信道ID
    //     connectUrl: string   // 信道连接地址
    //   },
    //   userinfo: object       // 用户信息
    // }
    // 你需要在本地维护一个信道 ID 和用户信息的对应关系
  })
}

qcloud.tunnel.onTunnelMessage(body)

解析请求体获取信道服务 post 过来的信息

参数

  • req - http.IncomingMessage 实例化对象
返回值

Promise 对象，.then 中可以获得信道服务地址

返回数据格式
{
  type: string,             // 包类型，有 connect, message, close 三种
  tunnelId: string          // 信道 ID
  content: {
    messageType: string,    // 消息类型
    messageContent: string  // 消息内容
  }
}
调用示例
// express
module.exports = (req, res) => {
  qcloud.tunnel.onTunnelMessage(req.body).then(packet => {
    // {
    //   type: string,             // 包类型，有 connect, message, close 三种
    //   tunnelId: string          // 信道 ID
    //   content: {
    //     messageType: string,    // 消息类型
    //     messageContent: string  // 消息内容
    //   }
    // }
  })
}

qcloud.tunnel.broadcast(tunnelIds, messageType, messageContent)

向指定的多个 tunnelId 广播信息

参数

  • tunnelIds - 要广播的信道 ID 的列表数组
  • messageType - 信息类型
  • messageContent - 信息内容

返回数据

Promise 对象

调用示例

const { tunnel: { broadcast } } = qcloud

tunnel.broadcast(['abcdefghijk'], 'speak', 'hello world')
.then(result => {
    const invalidTunnelIds = result.data && result.data.invalidTunnelIds || []
    // { invalidTunnelIds: [] } // 会返回无效的信道ID
})

qcloud.tunnel.closeTunnel(tunnelId)

关闭指定的信道

参数

  • tunnelId - 要关闭的信道 ID

返回数据

Promise 对象

调用示例

tunnel.closeTunnel('abcdefghijk')

图片上传

qcloud.uploader(req)

图片上传接口，直接从请求中读取图片文件，并上传到指定的 COS 中。完全兼容直接接入微信小程序端的 wx.upload 接口。

参数

  • req - http.IncomingMessage 实例化对象

返回数据

Promise 对象

返回数据格式

{
  imgUrl: string,     // 图片访问地址
  size: number,       // 图片大小
  mimeType: string,   // 图片 MIME 类型
  name: string        // 图片名称
}

调用示例

// express
module.exports = (req, res) => {
  qcloud.uploader(req).then(data => {
    console.log(data)
    // {
    //   imgUrl: 'http://test-121000000.cosgz.myqcloud.com/abcdef.jpg',
    //   size: 1048576,
    //   mimeType: 'image/jpeg',
    //   name: 'abcdef.jpg'
    // }
  })
}

数据库

由于 SDK 内部使用 Knex.js 连接数据库，SDK 暴露的 MySQL 实例就是 Knex.js 连接实例，具体使用方法可以查看 Knex.js 文档

客服消息

qcloud.message.checkSignature(signature, timestamp, nonce)

客服消息签名校验接口，具体文档可以参考微信接入指引

参数

  • signature - 请求的 query 中的 signature
  • timestamp - 请求的 query 中的 timestamp
  • nonce - 请求的 query 中的 nonce

返回数据

boolean - 签名是否有效

调用示例

const { message: { checkSignature } } = qcloud

/**
 * 响应 GET 请求（响应微信配置时的签名检查请求）
 */
router.get('/message', ctx => {
  const { signature, timestamp, nonce, echostr } = ctx.query
  if (checkSignature(signature, timestamp, nonce)) ctx.body = echostr
  else ctx.body = 'ERR_WHEN_CHECK_SIGNATURE'
})

// POST 请求的路由用来接收消息
router.post('/message', (ctx, next) {
    // 检查签名，确认是微信发出的请求
    const { signature, timestamp, nonce } = ctx.query
    if (!checkSignature(signature, timestamp, nonce)) ctx.body = 'ERR_WHEN_CHECK_SIGNATURE'

    /**
     * 解析微信发送过来的请求体
     * 可查看微信文档：https://mp.weixin.qq.com/debug/wxadoc/dev/api/custommsg/receive.html#接收消息和事件
     */
    const body = ctx.request.body

    ctx.body = 'success'
})

图像识别

**注意：**使用 .ci 相关接口需要开通万象优图，开通地址：https://console.cloud.tencent.com/ci

qcloud.ci.idCardIdentify(imageUrls, fileBucket, idCardType)

身份证识别接口

参数

  • imageUrls - 要识别的图片地址，可以先使用上传接口上传获得地址，然后再用本接口识别（多个）
  • fileBucket - 万象优图 Bucket
  • idCardType - 身份证类别（0：带头像那面，1：国徽那面）

返回数据

参考万象优图OCR-身份证识别

调用示例

const { ci } = require('../qcloud')

module.exports = async ctx => {
	const { data: identifyResult } = await ci.idCardIdentify(['https://mc.qcloudimg.com/image.jpg'], 'qcloudtest', 0)
    ctx.state.data = identifyResult.result_list
}

qcloud.ci.ocr(imageUrl, fileBucket)

普通文字印刷体识别

参数

  • imageUrl - 要识别的图片地址，可以先使用上传接口上传获得地址，然后再用本接口识别（单个）
  • fileBucket - 万象优图 Bucket

返回数据

参考万象优图OCR-通用印刷体识别

调用示例

const { ci } = require('../qcloud')

module.exports = async ctx => {
	const { data: ocrResult } = await ci.ocr('https://mc.qcloudimg.com/image.jpg', 'qcloudtest')
	ctx.state.data = ocrResult
}

语音识别

**注意：**使用 .voice 相关接口需要开通腾讯云智能语音，开通地址：https://console.cloud.tencent.com/aai

qcloud.voice.recognize(buffer, isEnd, voiceId, seq)

语音识别接口

参数

  • buffer - 语音分片的 buffer 数据
  • isEnd - 是否是最后一个分片
  • voiceId - 语音ID
  • seq - 分片序号

返回数据

Promise 对象

调用示例

参考语音识别 Demo。