小程序文档整理之 -- API（开放接口）

最新推荐文章于 2023-10-05 11:56:37 发布

VIP文章 bobobocai

最新推荐文章于 2023-10-05 11:56:37 发布

阅读量3.7w

点赞数 11

分类专栏：小程序文章标签： api 小程序

本文链接：https://blog.csdn.net/bobobocai/article/details/77651566

版权

 wx.login({
      success: function(res) {
   
          res.code//用户登录凭证（有效期五分钟）。开发者需要在开发者服务器后台调用 api，使用 code 换取 openid 和 session_key 等信息
          res.errMsg//调用结果
      },
      fail/complete: function(res) {
   //接口调用失败/结束的回调函数
      },
    });

code 换取 session_key(后台做的，不需要前台做)

这是一个 HTTPS 接口，开发者服务器使用登录凭证 code 获取 session_key 和 openid。

session_key 是对用户数据进行加密签名的密钥。为了自身应用安全，session_key 不应该在网络上传输。

接口地址：

https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

请求参数：

https://api.weixin.qq.com/sns/jscode2session
?appid=APPID//(必要)小程序唯一标识
&secret=SECRET(必要)小程序的 app secret
&js_code=JSCODE//(必要)登录时获取的 code
&grant_type=authorization_code//(必要)填写为 authorization_code

返回参数
//正常返回的JSON数据包
{
      "openid": "OPENID",//用户唯一标识
      "session_key": "SESSIONKEY",//会话密钥
      "unionid": "UNIONID"//用户在开放平台的唯一标识符。本字段在满足一定条件的情况下才返回。具体参看UnionID机制说明
}
//错误时返回JSON数据包(示例为Code无效)
{
    "errcode": 40029,
    "errmsg": "invalid code"
}

wx.checkSession(OBJECT)

通过上述接口获得的用户登录态拥有一定的时效性。用户越久未使用小程序，用户登录态越有可能失效。反之如果用户一直在使用小程序，则用户登录态一直保持有效。具体时效逻辑由微信维护，对开发者透明。开发者只需要调用wx.checkSession接口检测当前用户登录态是否有效。登录态过期后开发者可以再调用wx.login获取新的用户登录态。

wx.checkSession({
  success: function(){
   //接口调用成功的回调函数，登录态未过期
    //session 未过期，并且在本生命周期一直有效
  },
  fail: function(){
   //接口调用失败的回调函数，登录态已过期
    //登录态过期
    wx.login() //重新登录
    ....
  },
  complete: function(){
   //接口调用结束的回调函数（调用成功、失败都会执行）
  }
})

登录态维护

通过 wx.login 获取到用户登录态之后，需要维护登录态。

开发者要注意不应该直接把 session_key、openid 等字段作为用户的标识或者 session 的标识，而应该自己派发一个 session 登录态（请参考登录时序图）。对于开发者自己生成的 session，应该保证其安全性且不应该设置较长的过期时间。session 派发到小程序客户端之后，可将其存储在 storage ，用于后续通信使用。

通过 wx.checkSession 可以检测用户登录态是否失效。并决定是否调用 wx.login 重新获取登录态

用户数据的签名验证和加解密

数据签名校验

为了确保开放接口返回用户数据的安全性，微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验，确保数据的完整性。

1、签名校验算法涉及用户的session_key，通过 wx.login 登录流程获取用户session_key，并自行维护与应用自身登录态的对应关系。
2、通过调用接口（如 wx.getUserInfo）获取数据时，接口会同时返回 rawData、signature，其中 signature = sha1( rawData + session_key )
3、开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ，比对 signature 与 signature2 即可校验数据的完整性。

如wx.getUserInfo的数据校验：

接口返回的rawData：

{
  "nickName": "Band",
  "gender": 1,
  "language": "zh_CN",
  "city": "Guangzhou",
  "province": "Guangdong",
  "country": "CN",
  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"
}

用户的 session-key：
HyVFkGl5F5OQWJZZaNzBBg==

所以，用于签名的字符串为：

{
  "nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

使用sha1得到的结果为
75e81ceda165f4ffa64f4068af58c64b8f54b88c

加密数据解密算法

接口如果涉及敏感数据（如wx.getUserInfo当中的 openId 和unionId ），接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据，需要对接口返回的加密数据( encryptedData )进行对称解密。解密算法如下：

1、对称解密使用的算法为 AES-128-CBC，数据采用PKCS#7填充。
2、对称解密的目标密文为 Base64_Decode(encryptedData)。
3、对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。
4、对称解密算法初始向量为Base64_Decode(iv)，其中iv由数据接口返回。

微信官方提供了多种编程语言的示例代码（点击下载）。每种语言类型的接口名字均一致。调用方式可以参照示例。

另外，为了应用能校验数据的有效性，会在敏感数据加上数据水印( watermark )

如接口wx.getUserInfo敏感数据当中的watermark：

{
    "openId": "OPENID",
    "nickName": "NICKNAME",
    "gender": GENDER,
    "city": "CITY",
    "province": "PROVINCE",
    "country": "COUNTRY",
    "avatarUrl": "AVATARURL",
    "unionId": "UNIONID",
    "watermark"://数据水印
    {
        "appid":"APPID",//敏感数据归属appid，开发者可校验此参数与自身appid是否一致
        "timestamp":TIMESTAMP//敏感数据获取的时间戳, 开发者可以用于数据时效性校验
    }
}

注：
1、此前提供的加密数据（encryptData）以及对应的加密算法将被弃用，请开发者不要再依赖旧逻辑。
2、解密后得到的json数据根据需求可能会增加新的字段，旧字段不会改变和删减，开发者需要预留足够的空间

授权

部分接口需要获得用户授权同意后才能调用。此类接口调用时：

如果用户未接受或拒绝过此权限，会弹窗询问用户，用户点击同意后方可调用接口；
如果用户已授权，可以直接调用接口；
如果用户已拒绝授权，则短期内不会出现弹窗，而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

获取授权信息 wx.getSetting(OBJECT)

获取用户的当前设置
注：返回值中只会出现小程序已经向用户请求过的权限

wx.getSetting({
  success: (res) => {
    /*
     * res.authSetting = {用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: (res) => {//接口调用失败/结束的回调函数
  }
})

打开设置界面 wx.openSetting(OBJECT)

用户可以在小程序设置界面（右上角 - 关于 - 右上角 - 设置）中控制对该小程序的授权状态。

开发者可以调用 wx.openSetting 打开设置界面，引导用户开启授权。

wx.openSetting({
  success: (res) => {
    /*
     * res.authSetting = {用户授权结果，其中 key 为 scope 值，value 为 Bool 值，表示用户是否允许授权，详见 scope 列表
     *   "scope.userInfo": true,
     *   "scope.userLocation": true
     * }
     */
  },
  fail/complete: (res) => {//接口调用失败/结束的回调函数
  }
})

提前发起授权请求 wx.authorize(OBJECT)

提前向用户发起授权请求。调用后会立刻弹窗询问用户是否同意授权小程序使用某项功能或获取用户的某些数据，但不会实际调用对应接口。如果用户之前已经同意授权，则不会出现弹窗，直接返回成功。

// 可以通过 wx.getSetting 先查询一下用户是否授权了 "scope.record" 这个 scope
wx.getSetting({
    success(res) {
        if (!res.authSetting['scope.record']) {
            wx.authorize({
  //提前向用户发起授权请求
                scope: 'scope.record',//(必填)需要获取权限的scope
                success() {
                    errMsg//调用结果
                    // 用户已经同意小程序使用录音功能，后续调用 wx.startRecord 接口不会弹窗询问
                    wx.startRecord()
                },
                fail/complete(){
  //接口调用失败/结束的回调函数
                }
            })
        }
    }
})

scope 列表

scope	对应接口	描述
scope.userInfo	wx.getUserInfo	用户信息
scope.userLocation	wx.getLocation, wx.chooseLocation	地理位置
scope.address	wx.chooseAddress	通讯地址
scope.invoiceTitle	wx.chooseInvoiceTitle	发票抬头
scope.werun	wx.getWeRunData	微信运动步数
scope.record	wx.startRecord	录音功能

| scope.writePhotosAlbum| wx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum | 保存到相册 |

用户信息

获取用户信息，withCredentials 为 true 时需要先调用 wx.login 接口。
需要用户授权 scope.userInfo

wx.getUserInfo({
  withCredentials//是否带上登录态信息
  lang//指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。默认为en。
  success: function(res) {
   //接口调用成功的回调函数
    var userInfo = res.userInfo//用户信息对象，不包含 openid 等敏感信息
    var userInfo = res.userInfo
    var nickName = userInfo.nickName
    var avatarUrl = userInfo.avatarUrl
    var gender = userInfo.gender //性别 0：未知、1：男、2：女
    var province = userInfo.province
    var city = userInfo.city
    var country = userInfo.country
    res.rawData//不包括敏感信息的原始数据字符串，用于计算签名
    res.signature//使用 sha1( rawData + sessionkey ) 得到字符串，用于校验用户信息
    res.encryptedData//包括敏感数据在内的完整用户信息的加密数据，详细见加密数据解密算法
    res.iv//加密算法的初始向量，详细见加密数据解密算法
  },
  fail/complete: function(){
   //接口调用失败/结束的回调函数
  }
})

encryptedData 解密后为以下 json 结构，详见加密数据解密算法
{
    "openId": "OPENID",
    "nickName": "NICKNAME",
    "gender": GENDER,
    "city": "CITY",
    "province": "PROVINCE",
    "country": "COUNTRY",
    "avatarUrl": "AVATARURL",
    "unionId": "UNIONID",
    "watermark":
    {
        "appid":"APPID",
    "timestamp":TIMESTAMP
    }
}

注：当 withCredentials 为 true 时，要求此前有调用过 wx.login 且登录态尚未过期，此时返回的数据会包含 encryptedData, iv 等敏感信息；当 withCredentials 为 false 时，不要求有登录态，返回的数据不包含 encryptedData, iv 等敏感信息。

getPhoneNumber(OBJECT)

获取微信用户绑定的手机号，需先调用login接口。

说明

因为需要用户主动触发才能发起获取手机号接口，所以该功能不由 API 来调用，需用组件的点击来触发。

注意：目前该接口针对非个人开发者，且完成了认证的小程序开放。需谨慎使用，若用户举报较多或被发现在不必要场景下使用，微信有权永久回收该小程序的该接口权限。

最低0.47元/天解锁文章

bobobocai

关注

11
点赞
踩
61

收藏

觉得还不错? 一键收藏
2
评论
小程序文档整理之 -- API（开放接口）

登录wx.login(OBJECT)调用接口获取登录凭证（code）进而换取用户登录态信息，包括用户的唯一标识（openid）及本次登录的会话密钥（session_key）等。用户数据的加解密通讯需要依赖会话密钥完成。注：调用 login 会引起登录态的刷新，之前的 sessionKey 可能会失效。 wx.login({ success: function(res) {
复制链接

扫一扫