小程序小游戏云存档服务-阿里云帮助中心

小游戏可通过云存档 API 保存和读取进度，数据严格按用户与游戏维度隔离。

调用方式

使用 my.call 调用：

my.call(apiName, params, callback)

公共入参

属性	类型	必填	说明
`authToken`	string	是	当前用户的认证信息
`openUid`	string	是	当前用户的唯一标识
`platformId`	string	是	宿主平台分配的平台标识

说明

小游戏 ID 由容器自动获取，无需手动传入。
authToken / openUid：请调用小程序小游戏（广告&账号）客户端 API 的 my.getAuthCode 接口动态获取。
platformId：渠道唯一标识。示例（闲鱼）：9d4865ba1e5dd62ca54e143371ed3dcc

setCloudStorage

保存单条存档数据。

入参

除公共参数外，还需传入以下参数：

属性	类型	必填	说明
`key`	string	是	存档键，长度不超过 128 个字符
`value`	any	是	存档值，不能为 `null`

说明

value 支持 object、array、string、number 和 boolean 类型。

返回值

属性	类型	说明
`success`	boolean	调用是否成功
`resultCode`	string	结果码，成功时为 `200`
`resultMsg`	string	结果说明
`revision`	number	存档版本号
`usedBytes`	number	已使用容量，单位为字节
`limitBytes`	number	容量上限，单位为字节

示例代码

my.call('setCloudStorage', {
  authToken: authToken,
  openUid: openUid,
  platformId: platformId,
  key: 'player_progress',
  value: {
    level: 12,
    score: 9800
  }
}, function (result) {
  console.log(result)
})

getCloudStorageValue

读取指定 key 的存档数据。

入参

除公共参数外，还需传入以下参数：

属性	类型	必填	说明
`key`	string	是	存档键，长度不超过 128 个字符

返回值

属性	类型	说明
`success`	boolean	调用是否成功
`resultCode`	string	结果码，成功时为 `200`
`resultMsg`	string	结果说明
`exists`	boolean	指定 key 是否存在
`value`	any	存档值
`revision`	number	存档版本号

示例代码

my.call('getCloudStorageValue', {
  authToken: authToken,
  openUid: openUid,
  platformId: platformId,
  key: 'player_progress'
}, function (result) {
  if (result.success === true && result.resultCode === '200' && result.exists) {
    console.log(result.value)
  }
})

getAllCloudStorage

获取当前小游戏的全部存档。

入参

仅需公共参数。

返回值

属性	类型	说明
`success`	boolean	调用是否成功
`resultCode`	string	结果码，成功时为 `200`
`resultMsg`	string	结果说明
`storage`	object	全部存档数据
`revision`	number	当前存档版本号
`usedBytes`	number	已使用容量，单位为字节
`limitBytes`	number	容量上限，单位为字节

示例代码

my.call('getAllCloudStorage', {
  authToken: authToken,
  openUid: openUid,
  platformId: platformId
}, function (result) {
  if (result.success === true && result.resultCode === '200') {
    console.log(result.storage)
    console.log(result.revision)
  }
})

setAllCloudStorage

覆盖当前小游戏全部存档。

入参

除公共参数外，还需传入以下参数：

属性	类型	必填	说明
`storage`	object	是	要写入的全部存档数据
`expectedRevision`	number	是	预期版本（非负整数，首次传 0）

返回值

属性	类型	说明
`success`	boolean	调用是否成功
`resultCode`	string	结果码，成功时为 `200`
`resultMsg`	string	结果说明
`revision`	number	写入后的存档版本号
`usedBytes`	number	已使用容量，单位为字节
`limitBytes`	number	容量上限，单位为字节
`currentRevision`	number	版本冲突时的服务端当前版本号

示例代码

my.call('getAllCloudStorage', {
  authToken: authToken,
  openUid: openUid,
  platformId: platformId
}, function (result) {
  if (result.success !== true || result.resultCode !== '200') {
    return
  }

  my.call('setAllCloudStorage', {
    authToken: authToken,
    openUid: openUid,
    platformId: platformId,
    storage: {
      player_progress: {
        level: 13,
        score: 10500
      }
    },
    expectedRevision: result.revision
  }, function (setResult) {
    console.log(setResult)
  })
})

错误码

错误码	说明
`CLOUD_STORAGE_INVALID_PARAMETER`	入参不符合要求
`CLOUD_STORAGE_QUOTA_EXCEEDED`	存档容量超过上限
`CLOUD_STORAGE_REVISION_CONFLICT`	`expectedRevision` 与服务端当前版本不一致
`9999`	网络异常、响应为空或响应无法解析

说明

当 setAllCloudStorage 返回 CLOUD_STORAGE_REVISION_CONFLICT 时，请先调用 getAllCloudStorage 获取最新数据和 revision，合并后再次写入。

注意事项

存档容量上限以接口返回的 limitBytes 为准。
存档容量大小按 JSON 数据的 UTF-8 字节数进行计算。
切换用户后必须重新读取存档，严禁复用上一用户的存档数据及 revision。
出于安全合规要求，日志中禁止输出 authToken 或完整存档内容。