抖音开放平台Logo
开发者文档
控制台
  • API 概览
  • 开放能力
  • 登录
  • 社交转发裂变
  • 用户信息及授权
  • 小游戏收藏
  • 群聊
  • 关注
  • 游戏互推组件
  • 添加到桌面
  • 游戏排行榜
  • 数据分析
  • 视频拍摄器
  • 订阅消息
  • 关系链
  • 开放数据域
  • 开放数据
  • tt.getCloudStorageByRelation
  • tt.setUserCloudStorage
  • tt.getUserCloudStorage
  • tt.removeUserCloudStorage
  • tt.getSharedCanvas
  • KVData
  • 开放数据分组
  • 客服能力
  • 侧边栏能力
  • 推荐流直出游戏能力
  • 基础
  • 渲染
  • 设备
  • 文件
  • 位置
  • 媒体
  • 网络
  • 游戏转发分享
  • 实时语音
  • 数据缓存
  • 系统
  • 广告
  • 界面
  • 支付
  • Worker
  • tt.getCloudStorageByRelation
    收藏
    我的收藏

    基础库 1.11.0 开始支持本方法,这是一个异步方法。

    根据关系类型获取与当前用户相关的其他用户托管数据。

    前提条件

    在主域下使用 tt.login 确认当前用户登录后才能使用

    业务背景
    使用限制

    目前关系数据接口仅在抖音 APP 下可用,在头条中使用暂时无法获取有效数据,只能获取用户自身数据。

    注意事项
    • types 属性中的各类型关系均需要宿主 APP 支持后,开发者才可调用接口获取到有效数据。
    • 该接口一次最多返回 100 个同玩好友的托管数据。
    • 如果你希望获取有序的排行榜数据,请使用 type = 'group'
    • 该方法数据源来自 tt.setUserCloudStorage。但与 tt.getUserCloudStorage 不同,通过该接口获取的数据会经过服务器处理,额外返回好友在同个小游戏中,储存在具有相同 keylist 的数据。
    • Tip:当type == 'group'时,传入参数 extra 中的 sortKey 和 groupId 两个字段必传。
    相关教程

    语法

    tt.getCloudStorageByRelation(options)

    参数说明

    options 为 object 类型,属性如下:

    属性名类型默认值必填说明最低支持版本
    typeenum
    关系类型
    1.11.0
    keyListArray<string>
    要获取的 key 列表
    1.11.0
    extraobject
    获取挑战排行榜数据时需要传的配置​
    1.11.0
    successfunction
    接口调用成功的回调函数
    1.11.0
    failfunction
    接口调用失败的回调函数
    1.11.0
    completefunction
    接口调用结束的回调函数(调用成功、失败都会执行)
    1.11.0

    type 的合法值

    说明最低支持版本
    friend
    好友关系​
    1.11.0
    recommend
    平台推荐部分用户
    1.11.0
    group
    群,当 type == 'group'时,传入参数extra中的 sortKey 和 groupId 两个字段必传
    1.11.0

    extra 类型说明

    object 类型,属性如下:

    属性名类型默认值必填说明最低支持版本
    sortKeystring
    后台配置的排行榜 key
    1.11.0
    groupIdstring
    用户分组 id
    1.11.0

    回调成功

    object 类型,属性如下:

    属性名类型说明最低支持版本
    avatarUrlstring
    用户头像 url
    1.11.0
    nicknamestring
    用户昵称
    1.11.0
    openidstring
    用户的 openid
    1.11.0
    KVDataListarray

    用户的托管 KV 数据列表。数据类型为 KVData

    1.11.0

    回调失败

    object 类型,属性如下:

    属性名类型说明最低支持版本
    errMsgstring

    "getCloudStorageByRelation:fail" + 详细错误信息

    1.11.0

    错误码

    errorCodeerrMsgerrorType说明最低支持版本
    999991get session id failed.F
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    999987feature is not supported in appD
    1.11.0
    999999type is nullD
    1.11.0
    106102网络错误F
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    106101respoF
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    106106platform auth denyF
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    106103invalid scopeF
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    106104system auth denyU
    好友关系授权校验
    1.11.0
    999990auth denyU
    好友关系授权校验
    1.11.0
    999991internal error/网络请求非200F
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    999985network unavailableU
    1.11.0
    999990auth denyU
    1.11.0
    999992native exceptionF
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    999993internal errorF
    小游戏框架内部错误,有需要请创建工单咨询
    1.11.0
    106105auth denyD
    1.11.0
    106107auth denyD
    1.11.0

    扫码体验

    请使用字节宿主APP扫码

    代码示例

    开发者工具中预览

    // 获取关系类型为friend的用户托管数据(非排行榜) tt.getCloudStorageByRelation({ type: "friend", keyList: ["score"], success: (res) => { console.log("调用成功"); console.log(res.data); }, fail: (res) => { console.log("调用失败"); }, complete: (res) => { console.log("调用完成"); }, }); // 获取关系类型为group的挑战排行榜数据 tt.getCloudStorageByRelation({ type: "group", keyList: ["ranlList"], extra: { sortKey: "ranlList", // 指定的key需要在后台配置过 groupId: "test_group", // 指定要获取的用户所属分组 }, success: (res) => { console.log("调用成功"); console.log(res.data); }, fail: (res) => { console.log("调用失败"); }, complete: (res) => { console.log("调用完成"); }, });