# storage.setUserStorage

本接口应在服务器端调用,详细说明参见服务端API

本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载),wx-server-sdk >= 0.4.0

上报用户数据后台接口。小游戏可以通过本接口上报 key-value 数据到用户的CloudStorage。

调用方式:

# HTTPS 调用

# 请求地址

POST https://api.weixin.qq.com/wxa/set_user_storage?access_token=ACCESS_TOKEN&signature=SIGNATURE&openid=OPENID&sig_method=SIG_METHOD

# 请求参数

属性 类型 默认值 必填 说明
access_token / cloudbase_access_token string 接口调用凭证
openid string 用户唯一标识符
signature string 用户登录态签名,签名算法请参考用户登录态签名算法
sig_method string 用户登录态签名的哈希方法,如hmac_sha256等,请参考用户登录态签名算法
kv_list Object 要上报的数据

kv_list 的结构

属性 类型 默认值 必填 说明
key string 数据的key
value string 数据的value

# 返回值

# Object

返回的 JSON 数据包

属性 类型 说明
errcode number 错误码
errmsg number 错误信息

errcode 的合法值

说明 最低版本
0 请求成功
-1 系统繁忙,此时请开发者稍候再试
87016 由于某个 key-value 长度超过限制而上报失败。
87017 由于用户存储的数据量超过限制而上报失败。
87018 由于用户存储的 key-value 对数量超过限制而上报失败。
87019 由于某个 key 长度超过限制而上报失败。

# 示例代码

curl -d '{"kv_list":[{"key":"score","value":"{\"wxgame\":{\"score\":16,\"update_time\":1513080573}}"},{"key":"gold","value":"3000"}]}' 'https://api.weixin.qq.com/wxa/set_user_storage?access_token=ACCESS_TOKEN&signature=SIGNATURE&openid=OPENID&sig_method=SIG_METHOD'

# 托管数据的限制

如果在上报数据时触发这些限制,设置数据会失败并且会收到带错误码的返回包。

  1. 每个 openid 所标识的微信用户,在游戏当中的托管的数据不能超过128个 key-value 对。
  2. 上报的 key-value 列表当中每一项的key+value长度都不能超过1K(1024)字节。
  3. 上报的 key-value 列表当中每一个 key 长度都不能超过128字节。

# 将排行榜显示在小游戏中心

若开发者希望把游戏的排行榜显示于小游戏中心,则需要把排行榜数据存储到对应的key/value中,一个排行榜数据对应一个key,多个排行榜则多个key。同时在 mp.weixin.qq.com 的小游戏管理后台“设置 - 游戏 - 排行榜设置”下配置对应的 key 以及相关排行榜属性。且 value 的内容必须是JSON Object格式序列化的字符串,该JSON Object顶层必须包含 wxgame 字段,定义如下:

属性名 类型 必填 说明
score Int32 该榜单对应分数值
update_time Int64 该分数最后更新时间,Unix时间戳

注意: wxgame下开发者不可自定义其他字段, wxgame同级开发者可自由定义,比如定义一个detail 字段,用于存储取得该分数的中间状态。

# 举例

比如某小游戏有一个分数排行榜,分数排行榜需要记录分数以及获得分数的耗时(游戏内的排行榜需要展示耗时),可以在wxgame同级别定义一个cost_ms字段,存储耗时的毫秒数。 分配一个不和已定义的托管数据的 key 相冲突的 key 作为分数排行榜的key,如 "score"。

在玩家耗时36500ms后,获得本周最高分16分,则需要更新分数,假设当前时间戳为1513080573, 则完整 value在序列化之前的内容如下:

{
  "wxgame": {
        "score":16,
        "update_time": 1513080573
  },
  "cost_ms":36500
}

最终序列化为 string 后,value为{\"wxgame\":{\"score\":16,\"update_time\": 1513080573},\"cost_ms\":36500}

# 云调用

云调用是微信云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

# 接口方法

openapi.storage.setUserStorage

需在 config.json 中配置 storage.setUserStorage API 的权限,详情

# 请求参数

属性 类型 默认值 必填 说明
openid string 用户唯一标识符
kvList Object 要上报的数据

kvList 的结构

属性 类型 默认值 必填 说明
key string 数据的key
value string 数据的value

# 返回值

# Object

返回的 JSON 数据包

属性 类型 说明
errCode number 错误码
errMsg number 错误信息

errCode 的合法值

说明 最低版本
0 成功

# 异常

# Object

抛出的异常

属性 类型 说明
errCode number 错误码
errMsg number 错误信息

errCode 的合法值

说明 最低版本
-1 系统繁忙,此时请开发者稍候再试
87016 由于某个 key-value 长度超过限制而上报失败。
87017 由于用户存储的数据量超过限制而上报失败。
87018 由于用户存储的 key-value 对数量超过限制而上报失败。
87019 由于某个 key 长度超过限制而上报失败。

# SDK 调用示例

// cloud = require('wx-server-sdk')
// ...
// 方法返回 Promise
cloud.openapi.storage.setUserStorage({
  openid: 'xxx',
  kvList: [{
    key: 'a',
    value: 1,
  }, {
    key: 'b',
    value: 2,
  }]
})