用途
Catalyst Data Streams 提供基于 WebSocket 的实时发布/订阅通道,用于向订阅方推送实时数据,例如把实时更新推送到浏览器。
主要能力
- 频道与访问控制只能在控制台的 Cloud Scale → Data Streams 创建;没有 SDK、REST 或 MCP 工具可以创建频道。可用 getAllChannels() 列出频道(control_type 0 = User Roles,1 = Custom Logic)。
- 服务端发布:在函数中使用 publishData / publish_data。
- 令牌对:通过 getTokenPair 生成令牌对,令牌键名为连字符形式,如 token["wss-id"]。
- 订阅:在 open 事件之后才可订阅,订阅参数包括 token['wss-id'](作为 zuid)、token.url 和 token.key。
- 确认机制:每条消息后必须调用 sendAck(),否则下一条消息不会送达。
- 管理方法:publishData、getAllChannels、getChannelDetails、getLiveCount 为管理员方法,仅限服务端使用,不可出现在浏览器或移动端代码中。
- 重连:需先释放旧会话(用旧令牌 unsubscribe()),获取新令牌,subscribe('0'),并从自有存储重新加载状态;用 '-2' 恢复断开的会话会重复投递消息,并重放 48 小时保留期的消息。主动关闭前应先 unsubscribe,随后出现的 code 1000 错误事件属预期。
使用方式
访问控制与令牌标识
令牌标识符取决于频道的访问控制类型,二者不可互换:
- User Roles:userId 为 Catalyst Authentication 中的应用用户 ID;控制台管理员的用户 ID 会被拒绝,连接会以 "Mandatory parameter app_user_id is missing." 失败。
- Custom Logic:使用 connectionName,且令牌必须在被选为该频道访问控制的 Advanced I/O 函数内生成,该函数即令牌端点,需先执行校验再调用 getTokenPair;Catalyst 不会自行调用它。从其他函数或 REST 调用会返回 "Invalid access control source!"。此类频道上签发的用户 ID 令牌会被 WebSocket 以 3000 拒绝。
运行时
- Node.js / JavaScript:用 new DataStreams(await zcAuth.init(req)) 初始化,Advanced I/O 处理器获得的是 Node 原始 req/res,没有 req.body、res.status() 或 res.json()。
- Python:需 zcatalyst-sdk 1.5.0+(Python 3.10+);app = zcatalyst_sdk.initialize(req=request),然后 app.datastreams()(复数形式);get_token_pair 需传入字符串频道 ID,并使用关键字参数 user_id= / connection_name=,结果键名为连字符形式(token["wss-id"]);订阅方在 connect() 之前不会做任何事。
- Java:依赖 com.zoho.catalyst:java-sdk(2.5.0+),来源 https://maven.zohodl.com;不存在 datastreams 构件。subscribe() 抛出受检异常 ZCDataStreamException;在 Catalyst 函数之外需用 new ZCDataStreamsWebSocket(config) 创建客户端,而非 ZCDatastream.getInstance()。
端到端验证
报告成功前应做完整验证:打开一个订阅方,用 getLiveCount() 确认其存在,发布一条测试消息,确认订阅方收到。Node 中 getLiveCount() 返回 { status, data: { connections } }。参考资料未覆盖的内容,可获取 https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/ 下的页面 Markdown(<page-url>/index.md),两者冲突时以参考资料为准。
安全要点
- publishData 和频道读取方法为管理员操作,只能在 Catalyst 函数中运行,绝不可放入浏览器或移动应用。
- 保护令牌端点:能调用它的人就能订阅频道,因此签发令牌前必须对调用方进行身份验证。
- Custom Logic 频道上,配置的函数是唯一守门人,应在调用 getTokenPair 前加入真正的校验。
- 除向请求令牌的客户端返回外,不得在任何地方记录或返回令牌密钥。
适用场景
实时频道、实时更新、向浏览器推送更新、发布/订阅、发布数据、WebSocket 订阅方、订阅类型、从最后一条消息恢复、实时连接数、频道访问控制、重连及断线重连后的重复消息处理等。
限制
- 频道与访问控制无法通过 SDK、REST 或 MCP 工具创建,只能在控制台创建。
- 管理员方法仅限服务端。
- 令牌标识符必须与访问控制类型匹配。
- 令牌端点必须做好鉴权。
- 消息需逐条确认,否则后续消息无法送达。
- 用 '-2' 恢复会话会重复投递并重放 48 小时保留期内的消息。