感谢您的反馈！
API
一、能力说明
功能介绍
如小游戏没有服务器，那么可以通过开放平台提供的云存档功能对游戏进度、资产数据进行存档，解决无服务器游戏换手机后无存档的问题，保障用户体验。由于原先的云存档能力不支持高性能容器，目前淘宝平台对云存档能力进行了升级，新能力支持普通容器与高性能容器。
有服务器的游戏，优先建议自己实现存档能力，将存档数据保存在自己的服务器上。请确保支持玩家换手机后仍然有存档，且不允许将用户的存档数据存放在本地。
注意：
1）接入旧版云存档能力的游戏无需强制升级，旧版能力在普通容器仍然能够使用。
2）本文档为未接入过旧版云存档能力的新游戏提供接入指引，不涉及到能力升级、数据迁移；如已经接入旧版云存档，希望进行存档能力升级，请参考云存档（存量游戏）?。
云存档大小限制
每个openid所标识的微信用户在每个游戏上托管的数据不能超过128个key-value对。
上报的key-value列表当中每一项的key+value长度都不能超过1K(1024)字节。
上报的key-value列表当中每一个key长度都不能超过128字节。
二、存档能力
接入前准备
接入云存档前，请在控制台-小游戏开发-小游戏开发权限中，申请小游戏云存档能力（新）权限包。
?
确认获得权限包后，可以在小游戏开发-小游戏云存档中，查看存储下来的数据。
?
类型定义
TBaseParams<T = void>
基础回调参数类型，用于定义接口请求的回调函数。
export type TBaseParams<T = void> = {
complete (): void; // 请求完成后的回调，无论成功或失败
success(data: T): void; // 请求成功时的回调
fail (err: any): void; // 请求失败时的回调 {errorCode: string;errorMessage: string;extra?: any;}
};
KVData
表示键值对数据的类型。
export type KVData = {
key: string; // 键名
value: string | number ; // 对应的值
};
TKVDataList
KVData 类型的数组。
export type TKVDataList = KVData[];
TKeyList
键名的字符串数组。
export type TKeyList = string[];
接口
1）初始化
async init(params: TInitParams)
参数
export type TInitParams = { env: 'online' | 'test'; };
env：online代表正式环境，test代表测试环境。
2）获取用户云存储中所有的键名。
async getUserCloudStorageKeys(params: TGetStorageKeys): Promise<void>;
参数:
export type TGetStorageKeys = TBaseParams<{ keys: TKeyList }>;
错误码：
错误码 |
说明 |
SDK_PARAMS_ERROR |
params未设置 |
3）获取用户云存储中的键值对列表
async getUserCloudStorage(params: TGetStorageParams): Promise<void>;
参数:
请求参数包括一个键列表和基础回调参数。
export type TGetStorageParams = { keyList: TKeyList } & TBaseParams<{ KVDataList: TKVDataList}>;
错误码：
错误码 |
说明 |
SDK_PARAMS_ERROR |
params未设置 |
4）设置用户云存储中的键值对列表。
async setUserCloudStorage(params: TSetStorageParams): Promise<void>;
参数:
请求参数包括键值对列表和基础回调参数。
export type TSetStorageParams = { KVDataList: TKVDataList } & TBaseParams;
错误码：
错误码 |
说明 |
SDK_PARAMS_ERROR |
params未设置 |
注意：
同一个用户同一个游戏中，同时进行set操作会抛出抢锁失败异常，一般重试即可解决。对于抢锁失败异常，游戏必须进行异常处理，避免出现丢档情况。
建议：
1）当同一个用户对同一个游戏发起多个set接口请求时，在上一次接口返回之后再发起新请求。
2）为保证系统性能、优化用户体验并节约服务器资源，所有客户端状态上报（set请求）请遵循“关键状态驱动”原则。不建议基于固定时间间隔（Polling）或无差别事件触发的冗余上报。
5）从用户云存储中移除指定的键
async removeUserCloudStorage(params: TRemoveStorageParams): Promise<void>;
参数:
请求参数包括一个键列表和基础回调参数。
export type TRemoveStorageParams = { keyList: TKeyList } & TBaseParams;
错误码：
错误码 |
说明 |
SDK_PARAMS_ERROR |
params未设置 |
keyList为空或者长度为0 |
通用错误码
错误码 |
说明 |
SDK_REQUEST_RESULT_FAILED_ERROR |
xxx请求失败。 |
示例代码
const sdk = my.tb.getInteractiveSDK();
const newCloud = sdk.getCloudStorageController();
// 初始化
try {
newCloud.init({ env: 'online' });
} catch (error) {
console.error(error);
}
if (newCloud) {
newCloud.setUserCloudStorage({
KVDataList: [
{
key: 'cnTime',
value: 'test',
}
],
success: (res) => {
console.log('云存档 设置数据成功', res);
},
fail: (err) => {
console.log('云存档 设置数据失败', err);
},
complete: (res) => {
console.log('云存档 设置数据完成', res);
}
});
newCloud.getUserCloudStorageKeys({
success: (res) => {
console.log('云存档 获取全部key成功', res);
},
fail: (err) => {
console.log('云存档 获取全部key失败', err);
},
complete: (res) => {
console.log('云存档 获取全部key完成', res);
}
});
newCloud.getUserCloudStorage({
keyList: ['cnTime'],
success: (res) => {
console.log('云存档 获取数据成功', res);
},
fail: (err) => {
console.log('云存档 获取数据失败', err);
},
complete: (res) => {
console.log('云存档 获取数据完成', res);
}
});
newCloud.removeUserCloudStorage({
keyList: ['cnTime'],
success: (res) => {
console.log('云存档 删除数据成功', res);
},
fail: (err) => {
console.log('云存档 删除数据失败', err);
},
complete: (res) => {
console.log('云存档 删除数据完成', res);
}
});
// setUserCloudStorage 接口重试参考代码
const MAX_RETRIES = 3; // 最大重试次数
const INITIAL_DELAY = 1000; // 初始重试延迟(毫秒)
const setCloudStorageWithRetry = (retryCount = 0) => {
newCloud.setUserCloudStorage({
KVDataList: [{ key: 'cnTime', value: 'test' }],
success: (res) => {
console.log('云存档 设置数据成功', res);
},
fail: (err) => {
if (retryCount < MAX_RETRIES) {
const delay = INITIAL_DELAY * Math.pow(2, retryCount);
console.warn(`云存档 设置失败，${delay}ms后第${retryCount + 1}次重试...`, err);
setTimeout(() => {
setCloudStorageWithRetry(retryCount + 1);
}, delay);
} else {
console.error('云存档 设置数据失败，已达最大重试次数', err);
}
},
complete: (res) => {
console.log('云存档 设置数据完成', res);
}
});
};
setCloudStorageWithRetry();
}
FAQ
多个key-value示例
有时开发者需要提供传入多个key-value，相关传入以及返回的情况如下示例
KVDataList: [
{
key: 'account',
value: 'account01'
},
{
key: 'time',
value:Date.now()
}
]
{"account":"account01","time":1751523186658}