云变量API文档
通用存储、列表、货币、名字:这些功能统称为云变量(在部分老文档里,也把这部分功能统称为积分)
所有云变量接口都运行在协程内, 所以调用者必须确保自己处于协程中, 每个和远程服务(RPC)交互的操作调用后都会等待直到处理结果返回.
几乎所有接口的参数都有且只有一个table
(少数接口没有任何参数)
返回结果通常有三个值, 分别是error_code
, data
, err_msg
error_code
: 为0时, 代表操作成功. 否则将被视为有某种错误data
: 当error_code == 0
时, data是本次操作的结果. 否则, data可能是服务器方面的某种错误原 因, 也可能为nil. 所以使用data前, 一定要先判断error_code
是否为0err_msg
: 当error_code == 0
时, err_msg为nil, 否则err_msg为一个字符串, 描述错误信息
-- coroutine.async可以创建一个协程. 以下假设所有调用都处于协程之内, 不再使用coroutine.async包裹
coroutine.async(function()
local error_code, data, err_msg = score.get({
user_id = '123456',
key = 'bar',
})
if error_code == 0 then
log.info(fmt("数据: %s, json.encode(data"))
else
log.error(fmt("错误码: %s, 错误数据: %s, 错误信息: %s", ec, json.encode(data), err_msg))
end
end)
注意:
- 每个游戏局在现实时间每分钟(从第一次提交开始计时,并非严格意义上的分钟)内,最多执行300次读操作和300次写操作。
- 云变量单次读写不得超过32M,每分钟写入操作总大小不得超过48M。
- 写操作次数=commit的次数+message_send的次数+message_modify_read的次数+message_delete的次数。
通用接口
get_commit (非RPC)
获得一个提交对象。除了统计,所有的修改操作都必须在提交对象上进行。可以把有关联的,必须同时成功的修改操作放在同一个提交对象里。
local c = score.get_commit()
commit
结束之前获得的提交对象,真正提交所有修改。在commit函数返回之前,所有相关修改未必真正的写入了数据库。
-- 示例
local c = score.get_commit()
-- 设置apple的初值为5
c.set {user_id = 55555555, key = 'apple', i_value = 5}
-- 添加2个apple
c.addi {user_id = 55555555, key = 'apple', value = 2},
-- 设置apple的属性
c.set {user_id = 55555555, key = 'apple', value = {color = 'red', price = 100}
-- 设置hp初值为100, 且设置'魔障'属性
c.set {user_id = 55555555, key = 'hp', value = {['魔障'] = 10}, i_value = 100}
-- 增加1000 HP
c.addi {user_id = 55555555, key = 'hp', value = 1000},
-- 扣除'星辰之力' 2点.
-- 注意, 如果value = 2改为 value = 4, 那么本次commit会失败, 因为'星辰之力'不足, 整个committer里的所有操作都无效化
c.money_cost {user_id = 55555555, key = '星辰之力', value = 2}
c.world_list_add({user_id = 55555555, key = '砖', value = {a = 1}, world_id = 777})
c.world_data_set({user_id = 55555555, key = '种子', value = {b = 1}, world_id = 777})
local error_code, data, err_msg = c.commit()
if error_code == 0 then
log.info('写入数据成功')
else
log.error(fmt('写入失败, 错误码: %s, 错误信息: %s, 额外错误信息: %s', error_code, err_msg, json.encode(data)))
end
user_id
是number类型, 比如55555555
, 不过通常你也可以传入字符串形式的"55555555"
, 但是要保证该字符串可以被合法的转为number- response里的
user_id
总是number key
是一个字符串, 代表二级分类. 比如:
{user_id = 45646546, key = '装备', value = {'手榴弹' = 3, '子弹' = 1053, 'AK47' = 1}}
- 参数
- 无
- 返回的data格式
data = {} -- 空table
test_cloud_value
检测该值是否可以存进云变量,并返回序列化后的字节数。如果待检测的值合法,则打印序列化后的长度;否则报错提示非法原因。
-- 示例
local map = __TS__New(
Map,
{
__TS__Keyword("number"),
__TS__TypeReference(Unit, {})
},
__TS__New(Array, {{kind = "TupleType"}})
)
map.set(1, base.player(1):get_hero())
-- error_code返回0表示可以存储,其他值为不可存储
-- length为云变量序列化后的长度
-- err_msg为错误信息
-- 运行这句会报错:参数含有Map或Set等无法上传的对象
local error_code, length, err_msg = score.test_cloud_value { value = map }