抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 服务端 API 介绍
  • 接口调用凭证
  • 登录
  • 直播间能力
  • 查询观众阵营数据(开发者提供)

    收藏
    我的收藏

    接口说明

    观众进入直播间打开小摇杆互动面板时,平台服务器请求该接口获取用户在指定直播间最新的阵营数据。

    接口要求

      性能要求:qps 至少要满足 200/s。
      时延要求:P99 <= 100ms。

    基本信息

    名称
    描述
    HTTP URL
    开发者在开发者控制台的「开发配置」中配置
    HTTP Method
    POST
    签名要求
    详见3.3.5签名方式部分介绍。
    开发者请务必校验数据签名,验证数据来源的合法性,否则存在被伪造数据攻击的危险,需自行担责

    请求头

    名称
    字段类型
    是否必填
    描述
    x-nonce-str
    string
    签名用的随机字符串
    x-timestamp
    int64
    发送消息的毫秒级时间戳
    x-roomid
    string
    房间Id
    x-msg-type
    string
    消息类型
    user_group:用户阵营数据
    x-signature
    string
    请求签名,业务方接收后需要计算和校验签名,防伪造和篡改
    content-type
    string
    固定值:application/json

    签名方式

      开发者请务必校验数据签名,验证数据来源的合法性,否则存在被伪造数据攻击的危险,需自行担责
      对表格中header参数(x-signature,content-type除外),按key字典序从小到大排序, 排序后,将key-value按顺序连接起来。如:key1=value1&key2=value2。
      再直接拼接(无需连接符)上body字符串和secret(开发配置中配置的字段)。注意,字符串需要使用utf-8编码。
      把拼接好的字符串进行md5计算(16bytes),并对md5计算结果进行base64编码,编码结果便是x-signature
    go示例:
    /** 比如: header := map[string]string{ "x-nonce-str": "123456", "x-timestamp": "456789", "x-roomid": "268", "x-msg-type": "user_group", } bodyStr := "abc123你好" secret := "123abc" rawData为:x-msg-type=user_group&x-nonce-str=123456&x-roomid=268&x-timestamp=456789abc123你好123abc signature为:GAkalGmhzqlUGQO/TgvMug== */ func signature(header map[string]string, bodyStr, secret string) string { keyList := make([]string, 0, 4) for key, _ := range header { keyList = append(keyList, key) } sort.Slice(keyList, func(i, j int) bool { return keyList[i] < keyList[j] }) kvList := make([]string, 0, 4) for _, key := range keyList { kvList = append(kvList, key+"="+header[key]) } urlParams := strings.Join(kvList, "&") rawData := urlParams + bodyStr + secret md5Result := md5.Sum([]byte(rawData)) return base64.StdEncoding.EncodeToString(md5Result[:]) }
    java示例:
    import java.security.MessageDigest; import java.util.*; /** * @jdk >= 1.8 * @param header = { "x-nonce-str": "123456", "x-timestamp": "456789", "x-roomid": "268", "x-msg-type": "user_group", * } * @param bodyStr = "abc123你好" * @param secret = "123abc" * @return GAkalGmhzqlUGQO/TgvMug== */ public static String signature(Map<String, String> header, String bodyStr, String secret) throws Exception { List<String> keyList = new ArrayList<>(4); header.forEach((key, val) -> keyList.add(key)); Collections.sort(keyList, String::compareTo); List<String> kvList = new ArrayList<>(4); for (String key : keyList) { kvList.add(key + "=" + header.get(key)); } String urlParams = String.join("&", kvList); String rawData = urlParams + bodyStr + secret; MessageDigest md = MessageDigest.getInstance("MD5"); md.update(rawData.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(md.digest()); }

    请求参数

      Body
    名称
    字段类型
    是否必填
    描述
    app_id
    String
    小玩法app_id
    open_id
    String
    用户open_id
    room_id
    String
    房间Id

    响应参数

    请求响应都以http 200的形式返回,具体错误由响应字段中的错误码字段来标记。
    名称
    字段类型
    是否必填
    描述
    errcode
    Int64
    错误码,0代表成功
    errmsg
    String
    错误描述,成功为 success
    data
    struct
    errcode为0时,该字段必传
    round_id
    Int64
    当前直播间,当前的对局id。如果一个对局已经结束,但是还没有开始新的对局,则返回已经结束的对局信息。如果从来没有开始过对局,则传 0。
    round_status
    Int
    当前直播间的对局状态。(1=已开始、2=已结束)
    user_group_status
    Int
    用户是否加入阵营
    - 如用户未加入阵营,则传0;
    - 如用户已加入阵营,则传1
    group_id
    String
    阵营id,取值来源来自开发者平台「礼物进阶配置」的group_id。
    - 如用户未加入阵营,则传空字符串;
    - 如用户加入阵营,则传对应的group_id

    响应示例

      正常响应
    { "errcode": 0, "errmsg": "success", "data": { "round_id": 12, "round_status": 1, "group_id": "test01", "user_group_status ": 1 } }
      异常响应
    { "errmsg": "参数不合法", "errcode": 1 }

    错误码

    HTTP 状态码
    错误码
    描述
    排查建议
    200
    40001
    参数错误
    房间id、小玩法app_id等入参解析失败,检查参数解析逻辑
    200
    4014034
    请求过于频繁
    提高接口的处理能力(必要时可联系平台进行熔断)
    200
    40004
    签名错误
    检查签名生成代码