通过自定义域名使用抖音云websocket能力
收藏介绍
在很多业务场景下，开发者无法通过抖音端内或者抖音云提供的SDK来使用抖音云websocket能力；针对这种场景，抖音云提供了自定义域名的能力，开发者可以使用自行持有的域名在抖音云控制台上完成绑定，绑定完成后就基于该域名来向抖音云发起websocket请求。
使用限制
操作指南
绑定自定义域名
- 1.开发者首先在抖音云控制台上绑定自定义域名，具体可以参考：绑定自定义域名；
- 2.若开发者没有自己的域名，可以通过抖音云提供的默认公网域名来进行接入测试，在抖音云控制台点击【服务】-【访问控制】，打开域名访问开关可以得到默认公网域名：
- 3.如果想通过自定义域名的方式访问到后端服务，还需要添加对应的path授权外网访问，具体可以参考：添加访问路径；
获取websocket连接ID
关于websocket连接ID的说明：
- •抖音云网关在websocket建连时会基于该连接ID进行身份验证，单个连接ID仅允许 建立一次websocket连接，无法复用；客户端在建立新的websocket连接时需要获取新的连接ID。
websocket建连
开发者可以通过如下websocket地址请求抖音云网关进行建连：
ws(s)://{host}/__dycloud__/ws/connect/
其中：
- •
ws(s)表示若开发者绑定自定义域名时勾选了HTTPS协议，则可以通过WSS协议进行websocket建连；- •
{host}表示开发者持有的域名，或者对应服务默认公网域名；- •
/__dycloud__/ws/connect/代表抖音云网关的websocket建连path，注意这里是两个短下横线_；除此之外，开发者还需要在websocket建连时携带如下请求头信息：
key | value(string) | 作用 |
X-TT-WS-CONN-ID | 4392960514 | 必传，websocket单次连接ID，用于权限校验 |
X-TT-SERVICE-PATH | /web_scoket/on_connect | 必传，抖音云网关将根据此路径通过HTTP回调的方式通知开发者服务，具体参考：websocket建连回调通知 |
客户端示例（Golang）：
package main import ( "fmt" "github.com/gorilla/websocket" "io" "log" "net/http" "net/url" ) func main() { host := "${your_addr}" // 这里替换成自定义域名/默认公网域名的host u := url.URL{Scheme: "wss", Host: addr, Path: "/__dycloud__/ws/connect/"} header := http.Header{} header.Set("X-TT-WS-CONN-ID", "") // 这里输入对应的连接id header.Set("X-TT-SERVICE-PATH", "") // 这里输入对应的后端回调地址 // 发起websocket建连 c, resp, err := websocket.DefaultDialer.Dial(u.String(), header) if err != nil { log.Fatal("websocket connect fail, err: ", err) } // 业务逻辑处理... }
websocket进组/换组
组推是一种比较常见的场景，比如将一条消息推送给直播间内的所有在线观众；开发者的客户端同样可以基于自定义域名，通过HTTP协议访问抖音云网关，来实现组推的能力：
进组：http(s)://{host}/__dycloud__/ws/join_group/ 退组：http(s)://{host}/__dycloud__/ws/exit_group/
其中：
- •
http(s)表示若开发者绑定自定义域名时勾选了HTTPS协议，则可以通过https访问。- •
{host}表示开发者自己的域名，或者对应服务默认公网域名；- •
/__dycloud__/ws/join_group/或者__dycloud__/ws/exit_group表示进组以及退组的path；注意这里是两个短下横线_；除此之外，开发者还需要在websocket建连时携带如下请求头信息：
key | value(string) | 作用 |
X-TT-WS-CONN-ID | 4392960514 | 必传，websocket单次连接ID，用于权限校验 |
X-TT-WS-GROUPNAME | live-room | 必传，表示组名 |
X-TT-WS-GROUPVALUE | live-room-id-1 | 必传，表示组名对应的阻值 |
请求示例：
curl --location --request POST 'https://host/__dycloud__/ws/join_group/' \ --header 'Content-Type: application/json' \ --header 'X-TT-WS-CONN_ID: 4392960514' \ --header 'X-TT-WS-GROUPNAME: live-room' \ --header 'X-TT-WS-GROUPVALUE: live-room-id-1'
常见问题
建连请求失败，如何排查？
websocket协议是基于HTTP协议的一种全双工通信，websocket建连失败时，可以根据HTTP响应的请求头来判断请求失败的原因，具体如下：
HTTP响应请求头 | 含义 |
StatusCode | HTTP协议的通用状态返回码 |
X-Status-Code | websocket建连的状态码，配合StatusCode判断失败的原因：
StatusCode = 401，X-Status-Code = 10030：请求携带的X-TT-WS-CONN-ID不合法，请检查该参数是否正确传递；
StatusCode = 500，X-Status-Code = 11020：连接注册失败，请重试；
StatusCode = 500，X-Status-Code = 11030：通知开发者服务失败，请检查对应的后端服务是否正确监听在对应的X-TT-SERVICE-PATH上；
StatusCode = 500，X-Status-Code = 11040：协议升级失败，请检查客户端的请求是否符合websocket协议； |
X-Tt-LogId | 请求的全局LogId，若未能排查出对应问题，可以通过该参数提交工单或者在对应技术支持群中询问对应技术人员。 |
