文档-迷你世界创作者学院-迷你教程

云服数据存储接口：CloudSever

迷你世界更新时间: 2024-04-28 19:09:10

具体函数名及描述如下：

序号	函数名	函数描述
1	setOrderDataBykey(...)	设置排行榜中指定键的数值
2	removeOrderDataByKey(...)	删除排行榜中指定键的数值
3	getOrderDataByKeyEx(...)	获取排行榜中指定键的数值
4	getOrderDataIndexValueEx(...)	获取排行榜中指定排名的数值
5	ClearOrderData(...)	清理排行榜
6	automaticByKey(...)	变量自运算
7	getOrderDataIndexAreaEx(...)	获取排行榜中多条数据 (一次最多100条数据)
8	getOrderDataValueAreaEx(...)	获取排行榜中指定值区域的前多少名数据 (一次最多100条数据)
9	setDataListBykey(...)	设置表中指定键的值
10	removeDataListByKey(...)	删除表中指定键的值
11	getDataListByKeyEx(...)	获取表中指定键的值
12	ClearDataList(...)	清空表数据
13	getlistCache(...)	获取表或排行榜当前缓存数据
14	UpdateDataListByKey(...)	安全更新数据
15	SendSeverMsg(...)	发送服务通知消息
16	TransmitToMap(...)	传送玩家到指定地图
17	TransmitToRoom(...)	传送玩家到指定房间
18	TransmitOtherRoom(...)	传送玩家其他房间
19	GetRoomID(...)	获取当前云服房间ID
20	TransmitToCategoryRoom(...)	传送玩家到指定分类房间
21	SetForbidJoin(...)	当前房间停止进入玩家（仅云服生效）
22	CloseCurRoom(...)	关闭当前房间（仅云服生效）
23	GetRoomCategory(...)	获取当前房间的分类信息（仅云服生效）

setOrderDataBykey

参数及类型：
- libvarname:string排行榜变量设计名
- key:string获取的键值
- value:number设置的数值
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：设置排行榜中指定键的数值
具体使用案例如下：

local libvarname = 'rank_1'
local ret = CloudSever:setOrderDataBykey(libvarname,"key1",1)
if ret == ErrorCode.OK then
    print('设置排行榜值成功 k = key1 ,v = 1')
else
    print('设置排行榜值失败')
end

removeOrderDataByKey

参数及类型：
- libvarname:string排行榜变量设计名
- key:string获取的键值
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：删除排行榜中指定键的数值
具体使用案例如下：

local libvarname = 'rank_1'
local ret = CloudSever:removeOrderDataByKey(libvarname,"key1")
if ret == ErrorCode.OK then
    print('删除排行榜数据成功')
else
    print("删除排行榜数据失败")
end

getOrderDataByKeyEx

参数及类型：
- libvarname:string排行榜变量设计名
- key:string获取的键值
- callback:function更新回调(function(code/错误码 ...)0成功1失败2数据不存在)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：获取排行榜中指定键的数值
具体使用案例如下：

local callback = function (ret,k,v,ix) -- 返回结果不一定有排名
    if ret == ErrorCode.OK then
        if ix then
            print('返回数据成功 键= '..k..' 值='..v..' 排名='..ix )
        else
            print('返回数据成功 键= '..k..' 值='..v)
        end
    else
        if ret == 2 then --=不存在数据
            print('数据不存在')
        else
            print('获取失败')
        end
    end
end
local libvarname = 'rank_1'
local ret = CloudSever:getOrderDataByKeyEx(libvarname,"key1",callback)
if ret == ErrorCode.OK then
    print('请求排行榜数据成功')
else
    print("请求排行榜数据失败")
end

getOrderDataIndexValueEx

参数及类型：
- libvarname:string排行榜变量设计名
- index:number获取数据的名次
- callback:function更新回调(function(code/错误码 ...)0成功1失败2数据不存在)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：获取排行榜中指定排名的数值
具体使用案例如下：

local callback = function (ret,k,v,ix)
    if ret == ErrorCode.OK then
        print('返回数据成功 键= '..k..' 值='..v..' 排名='..ix )
    else
        if ret == 2 then --=不存在数据
            print('数据不存在')
        else
            print('获取失败')
        end
    end
end
local libvarname = 'rank_1'---4
local ret = CloudSever:getOrderDataIndexValueEx(libvarname,1,callback) -- 请求第1名的数据
if ret == ErrorCode.OK then
    print('请求排行榜数据成功')
else
    print("请求排行榜数据失败")
end

ClearOrderData

参数及类型：
- libvarname:string排行榜变量设计名
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：清理排行榜
具体使用案例如下：

local libvarname = 'rank_1'
local ret = CloudSever:ClearOrderData(libvarname) -- 清空排行榜
if ret == ErrorCode.OK then
    print('清空排行榜值成功')
else
    print('清空排行榜值失败')
end

automaticByKey

参数及类型：
- libvarname:string排行榜变量设计名
- key:string获取的键值
- value:number每次加的值
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：变量自运算
具体使用案例如下：

local libvarname = 'rank_1'
local value = 10
local ret = CloudSever:automaticByKey(libvarname,"key1",value) -- 设置自运算值加10
if ret == ErrorCode.OK then
    print('设置排行榜值成功 k = key1 ,v = 1')
else
    print('设置排行榜值失败')
end

getOrderDataIndexAreaEx

参数及类型：
- libvarname:string排行榜变量设计名
- icount:number获取数据的条数
- callback:function更新回调(function(code/错误码 ...)0成功1失败2数据不存在)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
callback返回数据格式示例：

本地：

{
    {
        -- 玩家1迷你号，string类型
        k = [[1000]],
        -- 玩家1排行榜数值，number类型
        v = 1
    },
    {
        -- 玩家2迷你号，string类型
        k = [[1001]],
        -- 玩家2排行榜数值，number类型
        v = 3
    }
    -- 更多玩家数据依次类推
}
-- 本地返回的数据格式示例

云服：

{
    {
        -- 玩家1迷你号，string类型
        k = [[1000]],
        -- 玩家1排行榜数值，number类型
        v = 1,
        -- 玩家1昵称，string类型
        nick = [[迷你队长]]
    },
    {
        -- 玩家2迷你号，string类型
        k = [[1001]],
        -- 玩家2排行榜数值，数值类型
        v = 3,
        -- 玩家2昵称，string类型
        nick = [[迷你策划 Max]]
    }
    -- 更多玩家数据依次类推
}
-- 云服返回的数据格式示例

该方法的主要作用：获取排行榜中多条数据(一次最多100条数据)
具体使用案例如下：

--百人排行榜展示例子
local libvarname = 'rank_1'--排行榜名称
local reqcount = 100 --榜单上线
local refreshdt = 10 --首次请求间隔
local updatetime = 0 --当前更新时间
local RankInfos = {}
local function func_runtime(param)
    local curtime = os.time()
    if curtime - updatetime > refreshdt then
        updatetime = curtime
        local tmfos = {}
        local callback = function (ret,value) -- 返回结果不一定有排名
            if ret == ErrorCode.OK and value then
                refreshdt = 1200 --刷新时间修改
                for ix,  v in pairs(value) do
                    table.insert(tmfos,v)
                end
                if #tmfos == reqcount or #tmfos > #RankInfos then
                    RankInfos = tmfos
                end
            end
        end
        local ret = CloudSever:getOrderDataIndexAreaEx(libvarname,reqcount,callback)
        if ret == ErrorCode.OK then
            print('请求排行榜数据成功')
        else
            print("请求排行榜数据失败")
        end
    end
end
ScriptSupportEvent:registerEvent('Game.RunTime', func_runtime)
local RankUI  = "7275576434651487802" -- 填入UIID
local RefishTxt =
{
    -- {"名次",'昵称','分数'}的元件ID,
    {"7275576434651487802_1",'7275576434651487802_2','7275576434651487802_3'},
}
local PageItemCount = #RefishTxt
local AllUserinfo = {}
local function RankRefish(uin)
    if not AllUserinfo[uin] then AllUserinfo[uin] = 0 end
    print(AllUserinfo[uin])
    local istr = AllUserinfo[uin]*PageItemCount + 1
    if istr > #RankInfos  then return end
    for i = 1, PageItemCount, 1 do
        if RefishTxt[i] then
            if istr <= #RankInfos  then
                Customui:setText(uin,RankUI,RefishTxt[i][1],tostring(istr))
                Customui:setText(uin,RankUI,RefishTxt[i][2],tostring(RankInfos[istr].nick or RankInfos[istr].k))
                Customui:setText(uin,RankUI,RefishTxt[i][3],tostring(RankInfos[istr].v))
                istr = istr + 1
            else
                Customui:setText(uin,RankUI,RefishTxt[i][1],"")
                Customui:setText(uin,RankUI,RefishTxt[i][2],"")
                Customui:setText(uin,RankUI,RefishTxt[i][3],"")
            end
        end
    end
end
local function func_openui(e)
    if #RankInfos > 0 and e.CustomUI == RankUI then
        local uin = e.eventobjid
        AllUserinfo[uin] = 0
        RankRefish(uin)
    end
end
ScriptSupportEvent:registerEvent('UI.Show', func_openui)
--[[
--翻页功能
local pageupele = "7275576434651487802_7" -- 填入向上翻页按钮节点
local pagedownele = "7275576434651487802_8"-- 填入向下翻页按钮节点
local function func_page(e)
    local uin = e.eventobjid
    if  uin and  e.btnelenemt then
        if e.btnelenemt ==  pageupele then
            if not AllUserinfo[uin] then AllUserinfo[uin] = 0 end
            AllUserinfo[uin] =  AllUserinfo[uin] + 1
            if AllUserinfo[uin] > math.ceil(#RankInfos / PageItemCount )  then AllUserinfo[uin] = math.ceil(#RankInfos / PageItemCount) return end
            RankRefish(uin)
        elseif e.btnelenemt ==  pagedownele then
            if not AllUserinfo[uin] then AllUserinfo[uin] = 0 end
            AllUserinfo[uin] =  AllUserinfo[uin] -  1
            if AllUserinfo[uin] < 0  then AllUserinfo[uin] = 0 return end
            RankRefish(uin)
        end
    end
end
ScriptSupportEvent:registerEvent('UI.Button.Click', func_page)
]]--

getOrderDataValueAreaEx

参数及类型：
- libvarname:string排行榜变量设计名
- icount:number获取数据的条数
- minvalue:number最小值
- maxvalue:number最大值
- callback:function更新回调(function(code/错误码...)0成功1失败)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：获取排行榜中指定值区域的前多少名数据(一次最多100条数据)
具体使用案例如下：

local callback = function (ret,value)
    if ret == ErrorCode.OK and value then
        for ix,  v in pairs(value) do
            local txt = '第'.. ix..'名'..'键 = ' ..v.k..'值 = '..v.v
            print(txt)
        end
    end
end
local libvarname = 'rank_1'
local ret  = CloudSever:getOrderDataValueAreaEx(libvarname,-2,50,200,callback) -- 请求值是50 - 200的从大到小排序的前2名的数据
if ret == ErrorCode.OK then
    print('请求排行榜数据成功')
else
    print("请求排行榜数据失败")
end

setDataListBykey

参数及类型：
- libvarname:string表变量设计名
- key:string获取的键值
- value:Any任意值(number,string,table)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：设置表中指定键的值
具体使用案例如下：

local libvarname = 'list_1'
local ret = CloudSever:setDataListBykey(libvarname,"key1.score",1)
if ret == ErrorCode.OK then
    print('设置排行榜值成功 k = key1 ,v = 1')
else
    print('设置排行榜值失败')
end

removeDataListByKey

参数及类型：
- libvarname:string表变量设计名
- key:string获取的键值
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：删除表中指定键的值
具体使用案例如下：

local libvarname = 'list_1'
local ret = CloudSever:removeDataListByKey(libvarname,"key1.score") --获取key1的分数
if ret == ErrorCode.OK then
    print('请求删除排行榜数据成功')
else
    print("请求删除排行榜数据失败")
end

getDataListByKeyEx

参数及类型：
- libvarname:string表变量设计名
- key:string获取的键值
- callback:function更新回调(function(code/错误码...)0成功1失败2数据不存在)
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：获取表中指定键的值
具体使用案例如下：

local callback = function (ret,k,v)
    if ret == ErrorCode.OK then
        print('获取数据成功 键= '..k..' 值='..v)
    else
        if ret == 2 then --=不存在数据
            print('数据不存在')
        else
            print('获取失败')
        end
    end
end
local libvarname = 'list_1'
local ret = CloudSever:getDataListByKeyEx(libvarname,"key1.score",callback) --获取key1的分数
if ret == ErrorCode.OK then
    print('请求排行榜数据成功')
else
    print("请求排行榜数据失败")
end

ClearDataList

参数及类型：
- libvarname:string表变量设计名
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：清空表数据
具体使用案例如下：

local libvarname = 'list_1'
local ret = CloudSever:ClearDataList(libvarname)
if ret == ErrorCode.OK then
    print('清空表成功')
else
    print('清空表失败')
end

getlistCache

参数及类型：
- libvarname:string表变量设计名
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：获取表或排行榜当前缓存数据
具体使用案例如下：

local libvarname = 'list_1'
local ret,values = CloudSever:getlistCache(libvarname)
if ret == ErrorCode.OK then
    print('获取数据成功')
else
    print('获取数据失败')
end

UpdateDataListByKey

参数及类型：
- libvarname:string表变量设计名
- key:string更新的键值
- callback:function更新回调(function(code/错误码...))
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：安全更新数据
具体使用案例如下：

local callback = function (ret,key,value)
    -- ret 0 很遗憾，数据冲突了，
    -- 需要根据带回来的最新value进行逻辑处理后返回给底层重试
    if ret == 0 then
        print("有冲突，这是数据库里最新的值" , value)
        --逻辑处理
        value = value + 1
        --返回给底层重试
        return value
    -- ret 2 修改成功啦
    elseif ret == 2 then
        print("成功，更新后的值 " , value)
    end
  end
  local ret = CloudSever:UpdateDataListByKey('list','score',callback)
  if ret == ErrorCode.OK then
  end

SendSeverMsg

参数及类型：
- msg:string消息名称
- customdata:any消息附带参数
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：发送服务通知消息
具体使用案例如下：

--派发自定义事件
local function func_event(param)
    local data = {id = 123,ops = "aaa"} --自定义事件带入的参数
    local ok, json = pcall(JSON.encode, JSON, data) --转换成json格式
    CloudSever:SendSeverMsg("customevent",{customdata = json}) -- 发送云服消息广播
end
ScriptSupportEvent:registerEvent('Player.PlayAction', func_event)
--云服消息广播监听
local function func_event(param)
    print(param) --打印自定义事件参数
end
ScriptSupportEvent:registerEvent('customevent', func_event)

TransmitToMap

参数及类型：
- playerid:uin玩家UIN或玩家uin的数组
- mapid:number地图ID
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：传送玩家到指定地图
具体使用案例如下：

local ret  = CloudSever:TransmitToMap(playerid, mapid)
if ret == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

TransmitToRoom

参数及类型：
- playerid:uin玩家UIN或玩家uin的数组
- roomid:string房间ID
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：传送玩家到指定房间
具体使用案例如下：

local ret  = CloudSever:TransmitToRoom(playerid, roomid)
if ret == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

TransmitOtherRoom

参数及类型：
- playerid:玩家UIN或玩家uin的数组
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：传送玩家到其他房间
具体使用案例如下：

local ret  = CloudSever:TransmitOtherRoom(playerid)
if ret == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

GetRoomID

参数及类型：无
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
- roomid:string房间ID
该方法的主要作用：获取当前云服房间ID
具体使用案例如下：

local ret ,roomid = CloudSever:GetRoomID()
if ret == ErrorCode.OK then
    print('执行成功' ,roomid )
else
    print('执行失败')
end

TransmitToCategoryRoom

参数及类型：
- playerid:uin玩家UIN或玩家uin的数组
- roomtype:string分类ID(数值和字符串组合)
- mapid:string地图ID
返回值及类型：
- ret:number成功(ErrorCode.OK)ErrorCode
该方法的主要作用：传送玩家到指定分类房间
具体使用案例如下：

local ret  = CloudSever:TransmitToCategoryRoom(playerid, roomtype, mapid)
if ret == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

SetForbidJoin

参数及类型：
- seconds:number倒计时事件（小于等于零立即生效，默认0）
返回值及类型：
- code:number成功(ErrorCode.OKErrorCode
该方法的主要作用：当前房间停止进入玩家（仅云服生效）
具体使用案例如下：

local code  = CloudSever:SetForbidJoin(seconds)
if code == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

CloseCurRoom

参数及类型：
- countdown:number倒计时事件（小于等于零立即生效，默认0）
- msg:string提示语
返回值及类型：
- code:number成功(ErrorCode.OKErrorCode
该方法的主要作用：关闭当前房间（仅云服生效）
具体使用案例如下：

local code  = CloudSever:CloseCurRoom(countdown, msg)
if code == ErrorCode.OK then
    print('执行成功'  )
else
    print('执行失败')
end

GetRoomCategory

参数及类型：无
返回值及类型：
- code:number成功(ErrorCode.OK)ErrorCode
- msg:string分类信息
该方法的主要作用：获取当前房间的分类信息（仅云服生效，和传送到指定分类房间接口配合使用）
具体使用案例如下：

local code ,msg = CloudSever:GetRoomCategory()
if code == ErrorCode.OK then
    print('执行成功' ,msg )
else
    print('执行失败')
end