uni-open-bridge.md 34.2 KB
Newer Older
d-u-a's avatar
d-u-a 已提交
1 2
# uni-open-bridge

W
wanganxp 已提交
3
开发者对接微信等三方开放平台时,这些开放平台有众多的凭据需要管理,比如`access_token``session_key``encrypt_key``ticket`等。
d-u-a's avatar
d-u-a 已提交
4

W
wanganxp 已提交
5
`uni-open-bridge` 是一个统一管理微信等三方平台认证凭据的开源工具。
d-u-a's avatar
d-u-a 已提交
6

W
wanganxp 已提交
7
## 背景
d-u-a's avatar
d-u-a 已提交
8

W
wanganxp 已提交
9
调用微信等三方开放平台时,涉及众多凭据。
d-u-a's avatar
d-u-a 已提交
10

W
wanganxp 已提交
11 12 13 14 15
- 微信公众号h5、小程序、app、web各自都有若干凭据
- 有的是应用级凭据、有的是用户级凭据、有的是一次性凭据
- 有的从微信后台web界面复制,有的向微信服务器请求获得,有的需要先在客户端发起然后服务器再请求
- 有的凭据没有有效期,有的是临时凭据,会在一定时间或一定操作后失效,不同凭据的失效时间还不一样
- 有的凭据不能一直向微信服务器请求,有次数限制,需要自己缓存下来
d-u-a's avatar
d-u-a 已提交
16

W
wanganxp 已提交
17
这里面容易搞混和出错的地方非常多。假使在不同的业务逻辑中都向微信服务器请求凭据,必然会冲突。
d-u-a's avatar
d-u-a 已提交
18

W
wanganxp 已提交
19 20 21 22
比如,
1. `ticket` 的有效期为7200秒,需要定时请求,避免过期。并且由于获取 `ticket` 的 api 调用次数非常有限,频繁刷新 `ticket` 会导致 api 调用受限,影响自身业务,开发者必须在自己的服务全局缓存 `ticket `
2. 在客户端任意地方调用 `wx.login()` 后,会让上一个 `session_key` 立即过期
3. 关于`access_token`,微信官方文档直接建议公众号开发者使用中控服务器统一获取和刷新 `access_token`,其他业务逻辑服务器所使用的 `access_token` 均来自于该中控服务器,不应该各自去微信服务器刷新,否则容易造成冲突。
d-u-a's avatar
d-u-a 已提交
23

W
wanganxp 已提交
24
所以需要在一个中央系统来统一管理这些凭据,需要定时请求的凭据则由中央系统定时统一请求微信服务器,保存到数据库。
d-u-a's avatar
d-u-a 已提交
25

W
wanganxp 已提交
26
然后各个业务需要这些凭据时,从这个中央系统的接口中获取,而不是自己向微信服务器请求。
d-u-a's avatar
d-u-a 已提交
27

W
wanganxp 已提交
28
这个中央系统就是`uni-open-bridge`
d-u-a's avatar
d-u-a 已提交
29

W
wanganxp 已提交
30
## 系统组成
d-u-a's avatar
d-u-a 已提交
31

W
wanganxp 已提交
32
`uni-open-bridge` 包括:
W
wanganxp 已提交
33 34 35
1. 一个同名云对象 `uni-open-bridge`,插件下载地址:[https://ext.dcloud.net.cn/plugin?id=9002](https://ext.dcloud.net.cn/plugin?id=9002)。(其依赖了下面的公共模块,但不是一个插件)
2. 一个公共模块 `uni-open-bridge-common` ,插件下载地址:[https://ext.dcloud.net.cn/plugin?id=9177](https://ext.dcloud.net.cn/plugin?id=9177)。它独立为单独插件,是为了方便其他业务模块引用。事实上uni-id就引用了这个common插件。
3. 配套的数据库,保存这些凭据,表名为 [opendb-open-data](https://gitee.com/dcloud/opendb/tree/master/collection)。在redis中的key格式为 `uni-id:[dcloudAppid]:[platform]:[openid]:[access-token|user-access-token|session-key|encrypt-key-version|ticket]`
d-u-a's avatar
d-u-a 已提交
36

W
wanganxp 已提交
37
云对象`uni-open-bridge`默认是定时运行的,在package.json中配置了每小时定时运行一次(部署到线上服务空间后生效)。
d-u-a's avatar
d-u-a 已提交
38

39
该云对象根据在 `uni-config-center`[配置](#uni-id-config)固定凭据,从而有权定时向微信服务器发请求,将获取到的 `access_token``ticket` 保存到数据库 `opendb-open-data` 表中。
d-u-a's avatar
d-u-a 已提交
40

41
当所在服务空间开通redis时,还会缓存在redis的key。这会让系统性能更好。
d-u-a's avatar
d-u-a 已提交
42

W
wanganxp 已提交
43
云对象`uni-open-bridge`还提供了URL化能力,以方便外部系统读写这些凭据。
d-u-a's avatar
d-u-a 已提交
44

W
wanganxp 已提交
45
[uni-open-bridge-common](#uni-open-bridge-common) 提供了操作微信等三方平台凭据的底层接口,包括访问微信服务器和多层读写Redis、数据库的能力。
d-u-a's avatar
d-u-a 已提交
46

W
wanganxp 已提交
47 48 49
云对象`uni-open-bridge`访问微信服务器和读写凭据时其实也是依赖 [uni-open-bridge-common](#uni-open-bridge-common)公共模块。安装 `uni-open-bridge` 云对象插件时会自动安装依赖插件 [uni-open-bridge-common](#uni-open-bridge-common)

从微信获取到各种凭据后,当各个业务代码需要这些凭据时,通过如下方式获取。
d-u-a's avatar
d-u-a 已提交
50

W
wanganxp 已提交
51 52
- 云函数/云对象获取这些临时凭据,可引用公共模块 `uni-open-bridge-common` ,通过该模块的API获取,比如getAccessToken。[见下](#uni-open-bridge-common)
- 非uniCloud系统,比如传统云,获取这些凭据,需要将云对象`uni-open-bridge`进行URL化,通过Http方式请求凭据。[见下](#http)
d-u-a's avatar
d-u-a 已提交
53

d-u-a's avatar
d-u-a 已提交
54

W
wanganxp 已提交
55
流程图如下:
d-u-a's avatar
d-u-a 已提交
56

57
![](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-a90b5f95-90ba-4d30-a6a7-cd4d057327db/b80cec3b-e106-489d-9075-90b5ecb02963.png)
d-u-a's avatar
d-u-a 已提交
58

W
wanganxp 已提交
59
## 凭据介绍
60

W
wanganxp 已提交
61
### 凭据汇总
62

W
wanganxp 已提交
63
微信有公众号h5、小程序、App、web等4种平台,每个平台都有若干凭据。
64

W
wanganxp 已提交
65 66 67
微信提供了2个体系,公众平台和开放平台。
- 公众平台,[https://mp.weixin.qq.com/](https://mp.weixin.qq.com/),负责微信内的能力开放,即微信公众号H5和小程序,这2个都运行在微信内部。
- 开放平台,[https://open.weixin.qq.com/](https://open.weixin.qq.com/),负责微信外的系统来使用微信能力,即外部App和外部web站,这些外部应用来调用微信登录、微信支付等能力。
68

W
wanganxp 已提交
69 70 71 72 73 74 75
|凭据									|微信小程序				|微信公众号H5	|微信外的web站	|非微信的App|
|:-:									|:-:					|:-:			|:-:			|:-:		|
|[access_token](#access_token)			|定时刷新				|定时刷新		|开发者操作		|开发者操作	|
|[user_access_token](#user_access_token)|						|开发者操作		|-				|-			|
|[session_key](#session_key)			|uni-id维护或开发者操作	|-				|-				|-			|
|[encrypt_key](#encrypt_key)			|开发者操作				|-				|-				|-			|
|[ticket](#ticket)						|-						|定时刷新		|-				|-			|
76

W
wanganxp 已提交
77 78
- `定时刷新`:指由云对象 `uni-open-bridge` 的定时任务触发,自动从微信服务器获取凭据,通过调用 `uni-open-bridge-common` 写入到Redis或数据库
- `开发者操作`:指由开发者引入公共模块 `uni-open-bridge-common`,调用相关读写[方法](#uni-open-bridge-common)
79

W
wanganxp 已提交
80 81 82
- `session_key`: 如果使用了uni-id,则uni-id用户登陆时会自动读写该凭据。一般无需开发者维护。
- `encrypt_key` 依赖 `access_token``session_key`,如果依赖的值已存在,可直接读取 `encrypt_key`,如果不存在自动向微信服务器获取、开发者应该仅读取该值,如果有外部系统依赖时可写入
- `ticket` 依赖 `access_token`,直接获取 `ticket` 会检查 `access_token`,如果不存在默认先请求微信服务器获取并保存,继续请求 `ticket`
83

W
wanganxp 已提交
84
还有一些不常用的凭据暂不列出,例如:非微信的App平台的 access_token。
85

W
wanganxp 已提交
86
### 平台标记Platform@platform
d-u-a's avatar
d-u-a 已提交
87

W
wanganxp 已提交
88
`uni-open-bridge`中将不同平台命名如下表,在API和存储数据时都使用下表标记。注意不同于前端条件编译使用的uniPlatform。
d-u-a's avatar
d-u-a 已提交
89 90 91 92

|值					|描述				|
|:-:				|:-:				|
|weixin-mp	|微信小程序	|
W
wanganxp 已提交
93 94 95 96 97
|weixin-h5	|微信公众号H5	|
|weixin-web	|微信外的Web站	|
|weixin-app	|非微信的App		|
|qq-mp			|QQ小程序	|
|qq-app			|QQ外的App			|
d-u-a's avatar
d-u-a 已提交
98 99 100

提示:自动刷新固定应用级凭据目前仅支持 `weixin-mp``weixin-h5`。 后续补充其他平台

W
wanganxp 已提交
101
### 常见凭据用途
102

W
wanganxp 已提交
103 104 105 106 107 108 109 110 111 112 113
- 微信小程序

1. 客户端登陆需要保存 [session_key](#session_key)
2. 解密用户敏感数据需要 [access_token](#access_token)[session_key](#session_key),例如获取用户授权的手机号、用户敏感资料
3. 解密[uni云端一体安全网络]()通道使用的加密数据需要 [access_token](#access_token)、[session_key](#session_key)[encrypt_key](#encrypt_key)

- 微信公众号

1. 微信内公众号H5页面用户登陆需要用到 [user_access_token](#user_access_token)[ticket](#ticket)

微信凭据分应用级、用户级、一次性等凭据,如果你之前未接触过微信这些凭据,请务必阅读下面的**每个凭据的详细介绍**
114 115 116 117 118

### access_token(应用级)@access_token

- 微信小程序 `access_token` 是微信小程序全局唯一后台接口调用凭据,调用绝大多数后台接口时都需使用。[详情](https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/backend-api.html#access_token)

W
wanganxp 已提交
119
- 微信公众号H5 `access_token` 是公众号的全局唯一接口调用凭据,公众号调用各接口时都需使用 `access_token`。开发者需要进行妥善保存。`access_token` 的存储至少要保留512个字符空间。`access_token` 的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的 `access_token` 失效。
120 121 122

公众平台的 API 调用所需的 `access_token` 的使用及生成方式说明:

W
wanganxp 已提交
123
1、建议公众号开发者使用中控服务器统一获取和刷新 `access_token`,其他业务逻辑服务器所使用的 `access_token` 均来自于该中控服务器,不应该各自去微信服务器刷新,否则容易造成冲突,导致 `access_token` 覆盖而影响业务;
124 125 126 127 128 129 130 131 132 133 134 135 136

2、目前`access_token` 的有效期通过返回的expires_in来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新 `access_token`。在刷新过程中,中控服务器可对外继续输出的老 `access_token`,此时公众平台后台会保证在5分钟内,新老 `access_token` 都可用,这保证了第三方业务的平滑过渡;

3、`access_token` 的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新 `access_token` 的接口,这样便于业务服务器在 API 调用获知 `access_token` 已超时的情况下,可以触发 `access_token` 的刷新流程。

4、对于可能存在风险的调用,在开发者进行获取 `access_token` 调用时进入风险调用确认流程,需要用户管理员确认后才可以成功获取。具体流程为:

开发者通过某 IP 发起调用->平台返回错误码[89503]并同时下发模板消息给公众号管理员->公众号管理员确认该 IP 可以调用->开发者使用该 IP 再次发起调用->调用成功。

如公众号管理员第一次拒绝该 IP 调用,用户在1个小时内将无法使用该 IP 再次发起调用,如公众号管理员多次拒绝该 IP 调用,该 IP 将可能长期无法发起调用。平台建议开发者在发起调用前主动与管理员沟通确认调用需求,或请求管理员开启 IP 白名单功能并将该 IP 加入 IP 白名单列表。

### user_access_token(用户级)@user_access_token

W
wanganxp 已提交
137
微信公众号H5平台有两个相同名字 `access_token`,分别用于
138

W
wanganxp 已提交
139 140
1、应用级:公众号的全局唯一接口调用凭据,公众号调用各接口时都需使用 `access_token`
2、用户级:网页授权接口调用凭证,用户授权的作用域 `access_token`
141

W
wanganxp 已提交
142
众多凭据命名都叫`access_token`,无法有效区分。对于用户级的`access_token`**在 uni-open-bridge 中改名为** `user_access_token` 。它对应微信公众平台网页用户授权 `access_token`
143

W
wanganxp 已提交
144 145 146
|平台							|值						|描述																																																													|
|:-:							|:-:					|:-:																																																													|
|微信公众号H5	|access_token	|微信公众号H5用户会话密钥。[详情](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html)	|
147 148 149 150 151 152 153 154


### code(临时凭据)@code

微信小程序用户登录凭证校验

在客户端通过调用 `uni.login()` 获得临时登录凭证 `code` 后传到开发者服务器在请求微信服务器获得 `session_key``openid``unionid`

W
wanganxp 已提交
155 156 157
`code` 仅可在服务器使用一次,客户端调用频率限制每个用户每分钟100次。

所以`uni-open-bridge`中并没有持续化存储code。
158 159 160 161 162 163 164

### openid(用户级)@openid

微信小程序用户唯一标识

需要在开发者服务器请求微信服务器获得,依赖参数 code,[详情](#code)

W
wanganxp 已提交
165 166
`uni-open-bridge`中并没有持续化存储openid,相关读写和保存是交由另一个插件`uni-id`来负责的。

167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
可通过 `uni-id-co` 获取,[详情](https://uniapp.dcloud.net.cn/uniCloud/uni-id-summary.html#save-user-token)

### session_key(用户级)@session_key

平台对应的值

|平台				|值					|描述																																																								|
|:-:				|:-:				|:-:																																																								|
|微信小程序	|session_key|微信小程序会话密钥。[详情](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/user-login/code2Session.html)	|

会话密钥 `session_key` 有效性

开发者如果遇到因为 `session_key` 不正确而校验签名失败或解密失败,请关注下面几个与 `session_key` 有关的注意事项。

`uni.login` 调用时,用户的 `session_key` 可能会被更新而致使旧 `session_key` 失效(刷新机制存在最短周期,如果同一个用户短时间内多次调用 `uni.login`,并非每次调用都导致 `session_key` 刷新)。

开发者应该在明确需要重新登录时才调用 `uni.login`,及时通过 `code2Session` 接口更新服务器存储的 `session_key`

W
wanganxp 已提交
185
微信不会把 `session_key` 的有效期告知开发者,会根据用户使用小程序的行为对 `session_key` 进行续期。用户越频繁使用小程序,`session_key` 有效期越长。
186 187 188 189 190 191 192

开发者在 `session_key` 失效时,可以通过重新执行登录流程获取有效的 `session_key`。使用接口 `uni.checkSession` 可以校验 `session_key` 是否有效,从而避免小程序反复执行登录流程。

当开发者在实现自定义登录态时,可以考虑以 `session_key` 有效期作为自身登录态有效期,也可以实现自定义的时效性策略。

### encrypt_key(用户级)@encrypt_key

W
wanganxp 已提交
193
为了避免微信小程序与开发者后台通信时数据被截取和篡改,微信侧维护了一个用户维度的可靠key,用于小程序和后台通信时进行加密和签名。[详情](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/user-encryptkey.html)
194 195 196 197 198

开发者可以分别通过小程序前端和微信后台提供的接口,获取用户的加密 key。

### ticket(用户级)@ticket

W
wanganxp 已提交
199
`ticket` 是微信公众号用于调用微信 JS 接口的临时票据。正常情况下,`ticket` 的有效期为7200秒,通过 `access_token` 来获取。
200 201 202

由于获取 `ticket` 的 api 调用次数非常有限,频繁刷新 `ticket` 会导致 api 调用受限,影响自身业务,开发者必须在自己的服务全局缓存 `ticket `[详情](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html#62)

W
wanganxp 已提交
203
而在`uni-open-bridge`已经缓存了该凭据。
204

W
wanganxp 已提交
205
## uni-open-bridge的使用流程
d-u-a's avatar
d-u-a 已提交
206

W
wanganxp 已提交
207 208
### 1. **下载插件[uni-open-bridge](https://ext.dcloud.net.cn/plugin?id=9002)到项目中。

W
wanganxp 已提交
209
### 2. `uni-config-center`的 `uni-id` 下配置固定凭据
W
wanganxp 已提交
210

W
wanganxp 已提交
211 212 213
如果你没有`appid``secret` ,需要先向微信申请
- 微信小程序或微信公众号,向微信的[公众平台](https://mp.weixin.qq.com/)申请 `appid``secret` 固定凭据。
- 微信App或PC网页,向微信的[开放平台](https://open.weixin.qq.com/)申请 `appid``secret` 固定凭据。
214 215

然后在项目的 uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json 文件中配置
d-u-a's avatar
d-u-a 已提交
216

d-u-a's avatar
d-u-a 已提交
217 218
如果不需要定时刷新 `access_token``ticket`、也不需要通过外部系统访问凭据时可单独引入 [uni-open-bridge-common](#uni-open-bridge-common),然后在云函数或云对象中直接调用相关方法

W
wanganxp 已提交
219
**uni-id-config中uni-id示例代码**
220

221
```json
d-u-a's avatar
d-u-a 已提交
222
// uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json
223 224
{
  "dcloudAppid": "__UNI__xxxxxx", // 在项目的 manifest.json 
W
wanganxp 已提交
225
  "mp-weixin": { // 微信小程序
226 227 228 229 230 231 232 233 234 235
    "tokenExpiresIn": 259200,
    "oauth": {
      "weixin": {
        "appid": "", // 微信公众平台申请的小程序 appid
        "appsecret": "" // 微信公众平台申请的小程序 secret
      }
    }
  },
  "web": {
    "oauth": {
W
wanganxp 已提交
236
      "weixin-h5": { //微信公众号h5
d-u-a's avatar
d-u-a 已提交
237 238
        "appid": "", // 微信公众平台申请的网页授权 appid
        "appsecret": "" // 微信公众平台申请的网页授权 secret
239 240 241 242 243
      }
    }
  }
}
```
d-u-a's avatar
d-u-a 已提交
244

W
wanganxp 已提交
245
注意:拷贝此文件内容时需要移除 `注释`。标准json不支持注释。在HBuilderX中可用多选//来批量移除注释。
246

W
wanganxp 已提交
247
### 3. `uni-config-center`下配置`uni-open-bridge`@uniopenbridgeconfig
248

W
wanganxp 已提交
249
`uni-config-center`目录下新建子目录`uni-open-bridge`, 新增 `config.json`,配置 dcloudAppid ,详情见下面的示例代码
d-u-a's avatar
d-u-a 已提交
250

W
wanganxp 已提交
251
**uni-id-config中uni-open-bridge示例代码**
252 253

```json
d-u-a's avatar
d-u-a 已提交
254
// uniCloud/cloudfunctions/common/uni-config-center/uni-open-bridge/config.json
255 256 257 258
{
  "schedule": {
    "__UNI__xxxxxx": { // dcloudAppid, 需要和 `uni-config-center` uni-id中的配置一致
      "enable": true, // 任务全局开关,优先级最高
259
      "weixin-mp": { // 平台,目前仅支持 微信小程序、微信 H5,详情参见 https://uniapp.dcloud.net.cn/uniCloud/uni-open-bridge#platform
260 261 262
        "enable": true, // 当前平台任务开关
        "tasks": ["accessToken"] // 要执行的任务,微信小程序支持 accessToken
      },
263
      "weixin-h5": {
264 265 266 267 268
        "enable": false,
        "tasks": ["ticket"] // 支持微信 H5 ticket,因 ticker 依赖微信 H5 accessToken,内部自动先获取 accessToken。此处的 accessToken 和微信小程序的 accessToken 不是一个值
      }
    }
  },
W
wanganxp 已提交
269
  "ipWhiteList": ["0.0.0.0"] // 用于 URL化后 http 调用的服务器IP白名单,即指定ip的服务器才可以访问URL化后的`uni-open-bridge云对象
270 271 272
}
```

W
wanganxp 已提交
273
注意:拷贝此文件内容时需要移除 `注释`。标准json不支持注释。在HBuilderX中可用多选//来批量移除注释。
d-u-a's avatar
d-u-a 已提交
274

W
wanganxp 已提交
275 276
### 4. 将插件上传到服务空间

W
wanganxp 已提交
277
云对象`uni-open-bridge`上传到服务空间后,会每隔一个小时自动运行一次,从微信服务器获取相关凭据并保存到数据库。
W
wanganxp 已提交
278 279

在数据库`opendb-open-data`中会看到数据。如开通redis则在redis的`uni-id`分组中查看(推荐开通redis以获取更好的性能)。
d-u-a's avatar
d-u-a 已提交
280

281
如果异常,请在 [uniCloud Web控制台](https://unicloud.dcloud.net.cn/),找到云函数/云对象 `uni-open-bridge` 检查运行日志。很可能是第一步或第二步的配置出错了。
282

W
wanganxp 已提交
283 284
当然如果不需要定时任务,可以修改云对象package.json里的定时任务配置并重新上传。或在uniCloud web控制台修改定时任务。一般不推荐修改定时任务设置。

W
wanganxp 已提交
285
## 业务系统获取相关凭据的方法
286

W
wanganxp 已提交
287
`uni-open-bridge`云对象获取到相关凭据后,当业务系统(比如登录支付或其他业务)需要使用这些凭据时,通过以下方式获取。
288

W
wanganxp 已提交
289
### 云函数公共模块方式@uni-open-bridge-common
290

W
wanganxp 已提交
291
当你的业务在uniCloud上时,在你的业务云函数/云对象中引用公共模块`uni-open-bridge-common`,然后调用下面的API。
292 293 294

> `云函数公共模块`是不同云函数共享代码的一种方式。如果你不了解什么是`云函数公共模块`,请另读文档[公共模块](https://uniapp.dcloud.io/uniCloud/cf-common)

W
wanganxp 已提交
295
`uni-open-bridge-common` 公共模块,提供了 [access_token](#access_token)[user_access_token](#user_access_token)[session_key](#session_key)[encrypt_key](#encrypt_key)[ticket](#ticket) 的读取、写入、删除操作。
296 297 298

`uni-open-bridge-common` 支持多层 读取 / 写入 机制,`redis -> database -> fallback`,优先级如下:

299
如果用户没有开通 `redis` 或者操作失败,透传到 `database``database` 失败后,如果用户配置了 `fallback`,继续调用 `fallback` 方法,否则抛出 `Error``database` 对应的表为: `opendb-open-data`
300

W
wanganxp 已提交
301
在常见的情况下,在你的云函数/云对象中调用`uni-open-bridge-common`的几个get方法即可。
302

W
wanganxp 已提交
303
```js
304
let uobc = require('uni-open-bridge-common')
W
wanganxp 已提交
305

306
// 应用级凭据
W
wanganxp 已提交
307 308
const key = {
  dcloudAppid: '__UNI__xxx', // DCloud Appid
W
wanganxp 已提交
309
  platform: 'weixin-mp' // 指定凭据所属平台,解释见上
310
}
W
wanganxp 已提交
311 312 313
uobc.getAccessToken(key)
uobc.getTicket(key)

314

315
// 用户级凭据,需要同时传入 openid 才能获得
316 317
const userKey = {
  dcloudAppid: '__UNI__xxx', // DCloud Appid
W
wanganxp 已提交
318 319
  platform: 'weixin-mp', // 指定凭据所属平台,解释见上
  openid: '' // 用户唯一标识,解释见上
320 321 322 323 324
}
uobc.getUserAccessToken(userKey)
uobc.getSessionKey(userKey)
uobc.getEncryptKey(userKey)

W
wanganxp 已提交
325 326
```

W
wanganxp 已提交
327 328
除了上述常见方法,下文列出了所有凭据的get、set、remove方法。

329 330 331 332
#### getAccessToken(key: Object, fallback: Function)

读取 access_token

333 334
#### setAccessToken(key: Object, value: Object, expiresIn: Number)

W
wanganxp 已提交
335
写入 access_token。开发者一般只需使用get类方法,用不到set、remove类方法。下同
336 337 338

#### removeAccessToken(key: Object)

W
wanganxp 已提交
339
删除 access_token。开发者一般只需使用get类方法,用不到set、remove类方法。下同
340 341


W
wanganxp 已提交
342
**key 属性**
343 344 345 346 347 348

|参数				|类型			|必填	|描述																															|
|:-:				|:-:			|:-:	|:-:																															|
|dcloudAppid|String		|是		|DCloud应用appid。[详情](https://ask.dcloud.net.cn/article/35907)	|
|platform		|String		|是		|[详情](#platform)																								|

W
wanganxp 已提交
349
**value 属性**
350

d-u-a's avatar
d-u-a 已提交
351 352 353
|参数					|类型		|描述									|
|:-:					|:-:		|:-:									|
|access_token	|String	|[详情](#access_token)|
354

W
wanganxp 已提交
355
**expiresIn**
356 357 358 359

有效时间(秒)


W
wanganxp 已提交
360
**示例代码**
361 362 363 364 365 366

```js
'use strict';

const {
  getAccessToken,
367 368
  setAccessToken,
  removeAccessToken
369 370 371 372
} = require('uni-open-bridge-common')

exports.main = async (event, context) => {
  const key = {
d-u-a's avatar
d-u-a 已提交
373
    dcloudAppid: '__UNI__xxx',
374
    platform: 'weixin-mp'
375 376 377 378 379 380 381 382 383 384 385 386
  }
  const value = {
    access_token: ''
  }
  const expiresIn = 7200

  // 写入 (redis / 数据库)
  await setAccessToken(key, value, expiresIn)

  // 读取 (redis / 数据库)
  let result1 = await getAccessToken(key)

387 388 389 390 391 392 393
  // 删除
  await removeAccessToken(key)

  // 删除后读取, 返回 null
  let result2 = await getAccessToken(key)
  console.log(result2) // null

394 395 396 397
  return null
};
```

398 399
#### getUserAccessToken(key: Object, fallback: Function)

W
wanganxp 已提交
400
读取 `user_access_token`
401

402 403
#### setUserAccessToken(key: Object, value: Object, expiresIn: Number)

W
wanganxp 已提交
404
写入 `user_access_token`
405 406 407

#### removeUserAccessToken(key: Object)

W
wanganxp 已提交
408
删除 `user_access_token`
409 410 411 412 413 414 415


对应微信公众平台网页用户授权 `access_token`,详情见下文说明


**key 属性**

416 417 418 419 420
|参数				|类型		|必填	|描述																															|
|:-:				|:-:		|:-:	|:-:																															|
|dcloudAppid|String	|是		|DCloud应用appid。[详情](https://ask.dcloud.net.cn/article/35907)	|
|platform		|String	|是		|[详情](#platform)																								|
|openid			|String	|是		|[详情](#openid)																									|
421 422 423

**value 属性**

d-u-a's avatar
d-u-a 已提交
424 425 426
|参数					|类型		|描述																									|
|:-:					|:-:		|:-:																									|
|access_token	|String	|微信公众平台用户会话密钥,[详情](#user_access_token)	|
427 428 429 430 431 432 433 434 435 436 437 438

**expiresIn**

有效时间(秒)

**示例代码**

```js
'use strict';

const {
  getUserAccessToken,
d-u-a's avatar
d-u-a 已提交
439 440
  setUserAccessToken,
  removeUserAccessToken
441 442 443 444
} = require('uni-open-bridge-common')

exports.main = async (event, context) => {
  const key = {
d-u-a's avatar
d-u-a 已提交
445
    dcloudAppid: '__UNI__xxx',
446
    platform: 'weixin-h5',
447 448 449 450 451 452 453 454 455 456 457 458 459
    openid: ''
  }
  const value = {
    'access_token': ''
  }
  const expiresIn = 7200

  // 写入 (redis / 数据库)
  await setUserAccessToken(key, value, expiresIn)

  // 读取 (redis / 数据库)
  let result1 = await getUserAccessToken(key)

d-u-a's avatar
d-u-a 已提交
460 461 462 463 464 465 466 467
  // 删除
  await removeUserAccessToken(key)


  // 删除后读取, 返回 null
  let result2 = await getUserAccessToken(key)
  console.log(result2) // null

468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
  return null
};
```


#### getSessionKey(key: Object, fallback: Function)

读取 session_key

#### setSessionKey(key: Object, value: Object, expiresIn: Number)

写入 session_key

#### removeSessionKey(key: Object)

删除 session_key
484 485


W
wanganxp 已提交
486
**key 属性**
487

488 489 490 491 492
|参数				|类型		|必填	|描述																															|
|:-:				|:-:		|:-:	|:-:																															|
|dcloudAppid|String	|是		|DCloud应用appid。[详情](https://ask.dcloud.net.cn/article/35907)	|
|platform		|String	|是		|[详情](#platform)																								|
|openid			|String	|是		|[详情](#openid)																									|
493

W
wanganxp 已提交
494
**value 属性**
495

d-u-a's avatar
d-u-a 已提交
496 497 498
|参数				|类型		|描述																			|
|:-:				|:-:		|:-:																			|
|session_key|String	|微信小程序会话密钥,[详情](#session_key)	|
499

W
wanganxp 已提交
500
**expiresIn**
501 502 503 504

有效时间(秒)


W
wanganxp 已提交
505
**示例代码**
506 507 508 509 510

```js
'use strict';

const {
511 512 513
  getSessionKey,
  setSessionKey,
  removeSessionKey
514 515 516 517
} = require('uni-open-bridge-common')

exports.main = async (event, context) => {
  const key = {
d-u-a's avatar
d-u-a 已提交
518
    dcloudAppid: '__UNI__xxx',
519
    platform: 'weixin-mp',
520 521 522 523 524 525 526 527
    openid: ''
  }
  const value = {
    'session_key': ''
  }
  const expiresIn = 7200

  // 写入 (redis / 数据库)
528
  await setSessionKey(key, value, expiresIn)
529 530

  // 读取 (redis / 数据库)
531 532 533 534 535 536 537 538 539
  let result1 = await getSessionKey(key)

  // 删除
  await removeSessionKey(key)


  // 删除后读取, 返回 null
  let result2 = await getSessionKey(key)
  console.log(result2) // null
540 541 542 543 544 545 546 547 548 549

  return null
};
```


#### getEncryptKey(key: Object, fallback: Function)

读取 encrypt_key

550 551 552 553 554 555 556 557 558
#### setEncryptKey(key: Object, value: Object, expiresIn: Number)

写入 encrypt_key

#### removeEncryptKey(key: Object)

删除 encrypt_key


W
wanganxp 已提交
559
**key 属性**
560

561 562 563 564 565 566
|参数				|类型		|必填	|描述																															|
|:-:				|:-:		|:-:	|:-:																															|
|dcloudAppid|String	|是		|DCloud应用appid。[详情](https://ask.dcloud.net.cn/article/35907)	|
|platform		|String	|是		|[详情](#platform)																								|
|openid			|String	|是		|[详情](#openid)																									|
|version		|Number	|是		|版本																															|
567 568


W
wanganxp 已提交
569
**value 属性**
570

d-u-a's avatar
d-u-a 已提交
571 572 573 574
|参数				|类型		|描述														|
|:-:				|:-:		|:-:														|
|encrypt_key|String	|加密 key,[详情](#encrypt_key)	|
|iv					|String	|加密 iv												|
575

W
wanganxp 已提交
576
**expiresIn**
577 578 579 580

有效时间(秒)


W
wanganxp 已提交
581
**示例代码**
582 583 584 585 586 587

```js
'use strict';

const {
  getEncryptKey,
588 589
  setEncryptKey,
  removeEncryptKey
590 591 592 593
} = require('uni-open-bridge-common')

exports.main = async (event, context) => {
  const key = {
d-u-a's avatar
d-u-a 已提交
594
    dcloudAppid: '__UNI__xxx',
595
    platform: 'weixin-mp',
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610
    openid: '',
    version: 1
  }
  const value = {
    encrypt_key: '',
    iv: ''
  }
  const expiresIn = 7200

  // 写入 (redis / 数据库)
  await setEncryptKey(key, value, expiresIn)

  // 读取 (redis / 数据库)
  let result1 = await getEncryptKey(key)

611 612 613 614 615 616 617
  // 删除
  await removeEncryptKey(key)

  // 删除后读取, 返回 null
  let result2 = await getEncryptKey(key)
  console.log(result2) // null

618 619 620 621 622 623 624 625 626
  return null
};
```


#### getTicket(key: Object, fallback: Function)

读取 ticket

d-u-a's avatar
d-u-a 已提交
627
#### setTicket(key: Object, value: Object, expiresIn: Number)
628 629 630

写入 ticket

d-u-a's avatar
d-u-a 已提交
631
#### removeTicket(key: Object)
632 633 634 635

删除 ticket


W
wanganxp 已提交
636
**key 属性**
637 638 639 640 641 642

|参数				|类型			|必填	|描述																															|
|:-:				|:-:			|:-:	|:-:																															|
|dcloudAppid|String		|是		|DCloud应用appid。[详情](https://ask.dcloud.net.cn/article/35907)	|
|platform		|String		|是		|[详情](#platform)																								|

W
wanganxp 已提交
643
**value 属性**
644 645 646

|参数				|类型		|描述			|
|:-:				|:-:		|:-:			|
d-u-a's avatar
d-u-a 已提交
647
|ticket			|String	|[详情](#ticket)					|
648

W
wanganxp 已提交
649
**expiresIn**
650 651 652 653

有效时间(秒)


W
wanganxp 已提交
654
**示例代码**
655 656 657 658 659 660

```js
'use strict';

const {
  getTicket,
661 662
  setTicket,
  removeTicket
663 664 665 666
} = require('uni-open-bridge-common')

exports.main = async (event, context) => {
  const key = {
d-u-a's avatar
d-u-a 已提交
667
    dcloudAppid: '__UNI__xxx',
668
    platform: 'weixin-h5'
669 670 671 672 673 674 675 676 677 678 679 680
  }
  const value = {
    ticket: ''
  }
  const expiresIn = 7200

  // 写入 (redis / 数据库)
  await setTicket(key, value, expiresIn)

  // 读取 (redis / 数据库)
  let result1 = await getTicket(key)

681 682 683 684 685 686 687 688
  // 删除
  await removeTicket(key)


  // 删除后读取, 返回 null
  let result2 = await getTicket(key)
  console.log(result2) // null

689 690 691 692 693 694
  return null
};
```



W
wanganxp 已提交
695
#### fallback
696 697 698 699 700 701 702 703 704 705

可选 `async function fallback()`,当 `reids -> database` 都找不到对应 `key` 时,调用此方法,需要返回数据格式如下

```json
{
  value: null,
  duration: 1
}
```

706
为了简化调用 `getAccessToken()``getTicket()` 已内置 `fallback` 到微信的服务器,需要在 `config-center` 中配置 `appid` `appsecret`[详情](#uni-id-config)
707

W
wanganxp 已提交
708
#### 注意事项
709 710

- 所有方法类型为 `async`,需要使用 `await`
711
- 所有方法校验 `key` 属性是否有效,无效则 `throw new Error()`,对 `value` 仅校验是否为 `Object`
W
wanganxp 已提交
712 713


d-u-a's avatar
d-u-a 已提交
714
### 云对象URL化方式@cloudurl
W
wanganxp 已提交
715

W
wanganxp 已提交
716
云对象 `uni-open-bridge` URL化后,非uniCloud系统可通过 http 方式访问凭据。
W
wanganxp 已提交
717 718 719 720 721

[URL化](http.md),是一种让云函数或云对象暴露为Http接口的方式,[详见](http.md)。可以在 [uniCloud Web控制台](https://unicloud.dcloud.net.cn/) 操作。

请求类型 `POST`, 可以配置IP白名单字段 `ipWhiteList`,参见 `config.json`

W
wanganxp 已提交
722
配置URL化后,其他系统可以通过下面的http接口,读写删各种开放平台凭据。
W
wanganxp 已提交
723 724 725 726 727 728 729 730 731 732 733 734 735 736

#### getAccessToken

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/getAccessToken
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
737
  "platform": "weixin-mp"
W
wanganxp 已提交
738 739 740
}
```

W
wanganxp 已提交
741 742
其中参数platform值域[详见](#platform)。下同,不再复述。

743 744
#### setAccessToken

W
wanganxp 已提交
745 746
如果各种开放平台凭据由`uni-open-bridge`托管,那么只需要调用各种get方法,是用不到set等方法的。但在某些情况下,相关凭据没有由`uni-open-bridge`从微信服务器获取,就需要这些set方法了。[详见](#nouseuniopenbridge)

747 748 749 750 751 752
Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/setAccessToken
```

753 754
参数

W
wanganxp 已提交
755
由外部系统从微信获取到相关凭据,然后写入。[详见](#nouseuniopenbridge)
756

757 758 759
```json
{
  "dcloudAppid": "__UNI__xxx",
760
  "platform": "weixin-mp",
761 762 763 764 765 766 767
  "value": {
    "access_token": ""
  },
  "expiresIn": 7200
}
```

768

769 770 771 772 773 774 775 776 777 778 779 780 781
#### removeAccessToken

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/removeAccessToken
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
782
  "platform": "weixin-mp"
783 784 785
}
```

W
wanganxp 已提交
786

787 788 789 790 791 792 793 794 795 796 797 798 799
#### getUserAccessToken

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/getUserAccessToken
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
800
  "platform": "weixin-h5",
801 802 803 804
  "openid": ""
}
```

805 806
其中参数openid值域[详见](#openid)。下同,不再复述。

807
#### setUserAccessToken
W
wanganxp 已提交
808 809 810 811

Url

```
812 813 814 815 816
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/setUserAccessToken
```

参数

W
wanganxp 已提交
817
由外部系统从微信获取到相关凭据,然后写入。[详见](#nouseuniopenbridge)
818

819 820 821
```json
{
  "dcloudAppid": "__UNI__xxx",
822
  "platform": "weixin-h5",
823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843
  "openid": "",
  "value": {
    "access_token": ""
  },
  "expiresIn": 7200
}
```

#### removeUserAccessToken

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/removeUserAccessToken
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
844
  "platform": "weixin-h5",
845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861
  "openid": ""
}
```

#### getSessionKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/getSessionKey
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
862
  "platform": "weixin-mp",
863 864 865 866 867 868 869 870 871 872 873 874 875 876
  "openid": ""
}
```

#### setSessionKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/setSessionKey
```

参数

W
wanganxp 已提交
877
由外部系统从微信获取到相关凭据,然后写入。[详见](#nouseuniopenbridge)
878

879 880 881
```json
{
  "dcloudAppid": "__UNI__xxx",
882
  "platform": "weixin-mp",
883 884 885 886 887 888 889 890 891 892 893 894 895 896
  "openid": "",
  "value": {
    "session_key": ""
  },
  "expiresIn": 7200
}
```

#### removeSessionKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/removeSessionKey
W
wanganxp 已提交
897 898 899 900 901 902 903
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
904
  "platform": "weixin-mp",
W
wanganxp 已提交
905 906 907 908
  "openid": ""
}
```

909 910 911 912 913 914 915 916 917 918 919 920 921
#### getEncryptKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/getEncryptKey
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
922
  "platform": "weixin-mp",
923 924 925 926 927
  "openid": "",
  "version": 1 // 此版本号应根据客户端传递的版本号
}
```

928 929 930 931 932 933 934 935 936 937
#### setEncryptKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/setEncryptKey
```

参数

W
wanganxp 已提交
938
由外部系统从微信获取到相关凭据,然后写入。[详见](#nouseuniopenbridge)
939

940 941 942
```json
{
  "dcloudAppid": "__UNI__xxx",
943
  "platform": "weixin-mp",
944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965
  "openid": "",
  "version": 1,
  "value": {
    "encrypt_key": "",
    "iv": ""
  }
}
```

#### removeEncryptKey

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/removeEncryptKey
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
966
  "platform": "weixin-mp",
967 968 969 970 971
  "openid": "",
  "version": 1
}
```

W
wanganxp 已提交
972 973 974 975 976 977 978 979 980 981 982 983 984 985

#### getTicket

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/getTicket
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
986
  "platform": "weixin-h5"
987 988 989 990 991 992 993 994 995 996 997 998 999
}
```

#### setTicket

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/setTicket
```

参数

W
wanganxp 已提交
1000
由外部系统从微信获取到相关凭据,然后写入。[详见](#nouseuniopenbridge)
1001

1002 1003 1004
```json
{
  "dcloudAppid": "__UNI__xxx",
1005
  "platform": "weixin-h5",
1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024
  "value": {
    "ticket": ""
  }
}
```

#### removeTicket

Url

```
https://xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.bspapp.com/uni-open-bridge/removeTicket
```

参数

```json
{
  "dcloudAppid": "__UNI__xxx",
1025
  "platform": "weixin-h5"
W
wanganxp 已提交
1026 1027 1028 1029
}
```


d-u-a's avatar
d-u-a 已提交
1030 1031
## 不使用 `uni-open-bridge` 托管的情况@nouseuniopenbridge

W
wanganxp 已提交
1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046
如开发者的老业务里已经获取了微信的access_token等凭据,难以迁移到由`uni-open-bridge`来托管微信相关凭据。

那么`uni-open-bridge`也暴露了允许三方系统给`uni-open-bridge`写入微信相关凭据的接口。

因为其他插件会依赖`uni-open-bridge`,比如:
1. `uni-ad`微信小程序激励视频广告服务器回调
2. uni云端一体安全网络

如果`uni-open-bridge`里没有相关凭据,上述插件或功能就无法使用。

因此,开发者即不想改成由`uni-open-bridge`托管微信凭据,又需要使用上述依赖`uni-open-bridge`的功能或插件,就只能将老系统获取到的相关凭据写入到`uni-open-bridge`中。

此时,开发者需通过以下方式处理:

1. 取消`uni-open-bridge`云对象的定时任务,不再定时向微信服务器请求凭据
d-u-a's avatar
d-u-a 已提交
1047

W
wanganxp 已提交
1048
`uni-open-bridge`云对象的package.json中找到定时器节点`triggers`,删除该节点。本地修改package.json后需重新上传到服务空间方生效。
d-u-a's avatar
d-u-a 已提交
1049

W
wanganxp 已提交
1050
参考[定时任务配置](cf-functions.md#packagejson))。
d-u-a's avatar
d-u-a 已提交
1051

W
wanganxp 已提交
1052
2. 老系统从微信服务器获取到相关凭据后调用`uni-open-bridge`的set方法写入凭据
d-u-a's avatar
d-u-a 已提交
1053

W
wanganxp 已提交
1054
先将云对象`uni-open-bridge`进行URL化,暴露出http接口。然后老系统调用setAccessToken、setUserAccessToken、setSessionKey、setEncryptKey、setTicket等接口。[参考](#cloudurl)