catalyst-datastreams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

How It Works

工作原理

Channels and access control are console-only. Create the channel and choose its access control in Console → Cloud Scale → Data Streams; no SDK, REST, or MCP tool creates channels. Ask the user for the channel ID and its access control type, or list channels with
```
getAllChannels()
```
(
```
control_type
```
0 = User Roles, 1 = Custom Logic). Load
```
references/datastreams-basics.md
```
for concepts, the token rules, subscribe types, acknowledgement, and the REST API.
Pick the token identifier from the access control — it is not interchangeable.
- User Roles →
```
userId
```
  = an app user's ID from Catalyst Authentication. A console admin's user ID is rejected;
```
connectionName
```
  fails with "Mandatory parameter app_user_id is missing."
- Custom Logic →
```
connectionName
```
  , and the token must be generated inside the Advanced I/O function selected as the channel's access control. That function is the token endpoint: it runs your check, then calls
```
getTokenPair
```
  . Catalyst never calls it on its own. From any other function or REST: "Invalid access control source!". User-ID tokens on these channels are issued but the WebSocket rejects them (
```
3000
```
  ).
Server code (publish, token pair, channel reads) — load the runtime reference.
- Node.js / JavaScript →
```
references/datastreams-javascript-basics.md
```
  . Initialize with the app:
```
new DataStreams(await zcAuth.init(req))
```
  . Advanced I/O handlers get Node's raw
```
req
```
  /
```
res
```
  : no
```
req.body
```
  ,
```
res.status()
```
  , or
```
res.json()
```
  .
- Python →
```
references/datastreams-python-basics.md
```
  . Requires
```
zcatalyst-sdk
```
  1.5.0+ (Python 3.10+).
```
app = zcatalyst_sdk.initialize(req=request)
```
  , then
```
app.datastreams()
```
  (plural). Pass
```
get_token_pair
```
  a string channel ID and a keyword
```
user_id=
```
  /
```
connection_name=
```
  ; the result's keys are hyphenated (
```
token["wss-id"]
```
  ). The subscriber does nothing until
```
connect()
```
  .
- Java →
```
references/datastreams-java-basics.md
```
  . Dependency is
```
com.zoho.catalyst:java-sdk
```
  (2.5.0+) from
```
https://maven.zohodl.com
```
  ; no
```
datastreams
```
  artifact exists.
- ```
publishData
```
  ,
```
getAllChannels
```
  ,
```
getChannelDetails
```
  and
```
getLiveCount
```
  are admin methods: server only, never in browser or mobile code.
```
getTokenPair
```
  also exists in the browser SDK, but a Custom Logic token must come from the configured function.
Subscriber code — read the token correctly and always acknowledge. The token pair's keys are hyphenated: pass
```
token['wss-id']
```
as
```
zuid
```
, plus
```
token.url
```
and
```
token.key
```
. Subscribe only after the
```
open
```
event. Call
```
sendAck()
```
after every message, or the next message is never delivered. Messages carry
```
data
```
(always a string) and
```
streamingId
```
(plus
```
url
```
/
```
method
```
on API-operation messages). To reconnect, release the old session (old token →
```
unsubscribe()
```
), take a fresh token,
```
subscribe('0')
```
, and reload state from your own store; resuming a dropped session with
```
'-2'
```
redelivers missed messages twice and replays the 48-hour retention. Unsubscribe before every deliberate close; the
```
error
```
event with code
```
1000
```
that follows your own
```
unsubscribe()
```
is expected. In Node,
```
getLiveCount()
```
returns
```
{ status, data: { connections } }
```
. Java:
```
subscribe()
```
throws the checked
```
ZCDataStreamException
```
, and outside a Catalyst function create the client with
```
new ZCDataStreamsWebSocket(config)
```
, not
```
ZCDatastream.getInstance()
```
.
Verify end to end before reporting success. Open a subscriber, check
```
getLiveCount()
```
shows it, publish a test message, and confirm the subscriber received it. For anything the references do not cover, fetch the page under https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/ as Markdown (
```
<page-url>/index.md
```
), and prefer the references where they disagree.

通道和访问控制仅支持在 Console 中操作。 在 Console → Cloud Scale → Data Streams 中创建通道并选择其访问控制；任何 SDK、REST 或 MCP 工具都无法创建通道。向用户询问通道 ID 及其访问控制类型，或使用
```
getAllChannels()
```
列出通道（
```
control_type
```
0 = User Roles，1 = Custom Logic）。加载
```
references/datastreams-basics.md
```
，以了解相关概念、token 规则、订阅类型、确认机制和 REST API。
根据访问控制方式选择 token 标识符，两者不可互换。
- User Roles →
```
userId
```
  = Catalyst Authentication 中应用用户的 ID。控制台管理员的用户 ID 会被拒绝；使用
```
connectionName
```
  时会报错 "Mandatory parameter app_user_id is missing."
- Custom Logic → 使用
```
connectionName
```
  ，并且 token 必须在被选为该通道访问控制的 Advanced I/O 函数内部生成。该函数就是 token 端点：它先执行检查，再调用
```
getTokenPair
```
  。Catalyst 不会自行调用该函数。从其他函数或 REST 调用时会报错 "Invalid access control source!"。在这类通道上可以签发基于 User ID 的 token，但 WebSocket 会拒绝它们（
```
3000
```
  ）。
服务端代码（发布、token 对、通道读取）——加载运行时参考文档。
- Node.js / JavaScript →
```
references/datastreams-javascript-basics.md
```
  。使用应用进行初始化：
```
new DataStreams(await zcAuth.init(req))
```
  。Advanced I/O 处理器会收到 Node 的原始
```
req
```
  /
```
res
```
  ：不能使用
```
req.body
```
  、
```
res.status()
```
  或
```
res.json()
```
  。
- Python →
```
references/datastreams-python-basics.md
```
  。需要
```
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 →
```
references/datastreams-java-basics.md
```
  。依赖项为
```
com.zoho.catalyst:java-sdk
```
  （2.5.0+），来源于
```
https://maven.zohodl.com
```
  ；不存在名为
```
datastreams
```
  的 artifact。
- ```
publishData
```
  、
```
getAllChannels
```
  、
```
getChannelDetails
```
  和
```
getLiveCount
```
  都是管理员方法：仅限在服务端使用，绝不能用于浏览器或移动端代码。浏览器 SDK 中也提供了
```
getTokenPair
```
  ，但 Custom Logic token 必须来自配置的函数。
订阅者代码——正确读取 token，并始终进行确认。 token 对的键使用连字符：将
```
token['wss-id']
```
作为
```
zuid
```
传入，同时传入
```
token.url
```
和
```
token.key
```
。仅在
```
open
```
事件触发后进行订阅。每次收到消息后都要调用
```
sendAck()
```
，否则下一条消息将不会被投递。消息包含
```
data
```
（始终为字符串）和
```
streamingId
```
（API 操作消息还会包含
```
url
```
/
```
method
```
）。要重新连接，应释放旧会话（旧 token →
```
unsubscribe()
```
），获取新的 token，调用
```
subscribe('0')
```
，并从自己的存储中重新加载状态；使用
```
'-2'
```
恢复已断开的会话会将错过的消息重复投递两次，并重放 48 小时保留期内的消息。每次主动关闭前都要先取消订阅；执行自己的
```
unsubscribe()
```
后出现的
```
error
```
事件（代码
```
1000
```
）属于预期行为。在 Node 中，
```
getLiveCount()
```
返回
```
{ status, data: { connections } }
```
。Java 中，
```
subscribe()
```
会抛出受检异常
```
ZCDataStreamException
```
；在 Catalyst 函数之外创建客户端时，使用
```
new ZCDataStreamsWebSocket(config)
```
，不要使用
```
ZCDatastream.getInstance()
```
。
在报告成功之前进行端到端验证。 打开一个订阅者，确认
```
getLiveCount()
```
显示了该连接，发布一条测试消息，并确认订阅者已收到消息。对于参考资料未涵盖的内容，将 https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/ 下的页面以 Markdown 格式获取（
```
<page-url>/index.md
```
）；当参考资料与页面内容不一致时，优先采用参考资料。

Security Checklist

安全检查清单

```
publishData
```
and the channel-read methods are admin operations: run them only in a Catalyst function, never in a browser or mobile app.
Protect the token endpoint. Anyone who can call it can subscribe to the channel, so authenticate the caller before issuing a token.
On Custom Logic channels, the configured function is the only gatekeeper: put the real validation there before calling
```
getTokenPair
```
.
Do not log or return the token
```
key
```
anywhere except to the client that asked for it.

```
publishData
```
和通道读取方法属于管理员操作：仅在 Catalyst 函数中运行，绝不能用于浏览器或移动端应用。
保护 token 端点。任何能够调用它的人都可以订阅通道，因此必须在签发 token 前验证调用方身份。
在 Custom Logic 通道上，配置的函数是唯一的守门人：在调用
```
getTokenPair
```
前，必须在其中执行真正的验证逻辑。
除返回给发起请求的客户端外，不得在任何位置记录或返回 token
```
key
```
。

Triggers

触发条件

Use this skill for: "Data Streams", "Catalyst Data Streams", "datastreams", "real-time channel", "live updates", "push updates to the browser", "pub/sub", "publish data",

publishData

getTokenPair

, "token pair", "wss-id",

DataStreamsWebSocket

ZCDataStreamsWebSocket

ZCDatastream

, "WebSocket subscriber",

sendAck

, "subscribe type", "resume from last message", "live count",

getLiveCount

, "channel access control", "User Roles channel", "Custom Logic channel", "app_user_id is missing", "Invalid access control source", "Authentication failed 3000", "reconnect", "duplicate messages after reconnect", "DUPLICATE_VALUE",

@zcatalyst/datastreams

zcatalyst_sdk

get_token_pair

publish_data

send_ack

, or "Data Streams Python".

在以下场景使用此 skill："Data Streams"、"Catalyst Data Streams"、"datastreams"、"real-time channel"、"live updates"、"push updates to the browser"、"pub/sub"、"publish data"、

publishData

、

getTokenPair

、"token pair"、"wss-id"、

DataStreamsWebSocket

、

ZCDataStreamsWebSocket

、

ZCDatastream

、"WebSocket subscriber"、

sendAck

、"subscribe type"、"resume from last message"、"live count"、

getLiveCount

、"channel access control"、"User Roles channel"、"Custom Logic channel"、"app_user_id is missing"、"Invalid access control source"、"Authentication failed 3000"、"reconnect"、"duplicate messages after reconnect"、"DUPLICATE_VALUE"、

@zcatalyst/datastreams

、

zcatalyst_sdk

、

get_token_pair

、

publish_data

、

send_ack

或 "Data Streams Python"。

References

参考资料

Reference	Load when the query is about…
`references/datastreams-basics.md`	Concepts, channels, access control (User Roles vs Custom Logic), which token identifier to use, token pair shape, subscribe types, acknowledgement, retention, message fields, REST API endpoints and scopes
`references/datastreams-javascript-basics.md`	Node.js functions (init, publish, token endpoint, Custom Logic function, channel reads), Node and browser subscribers, package versions
`references/datastreams-python-basics.md`	Python functions and subscribers: `zcatalyst-sdk` 1.5.0+, `app.datastreams()` , `get_token_pair` argument rules, `DataStreamsWebSocket` with `connect()` and `set_on_*` callbacks, deploying Python functions
`references/datastreams-java-basics.md`	Java functions and subscribers: Maven setup, `ZCDatastream` , `ZCDataStreamsWebSocket` , checked exceptions, running outside Catalyst

参考资料	何时加载
`references/datastreams-basics.md`	概念、通道、访问控制（User Roles 与 Custom Logic）、应使用的 token 标识符、token 对结构、订阅类型、确认机制、保留期、消息字段、REST API 端点和 scope
`references/datastreams-javascript-basics.md`	Node.js 函数（初始化、发布、token 端点、Custom Logic 函数、通道读取）、Node 和浏览器订阅者、包版本
`references/datastreams-python-basics.md`	Python 函数和订阅者： `zcatalyst-sdk` 1.5.0+、 `app.datastreams()` 、 `get_token_pair` 参数规则、带有 `connect()` 和 `set_on_*` 回调的 `DataStreamsWebSocket` 、部署 Python 函数
`references/datastreams-java-basics.md`	Java 函数和订阅者：Maven 配置、 `ZCDatastream` 、 `ZCDataStreamsWebSocket` 、受检异常、在 Catalyst 之外运行