68 lines
No EOL
3.8 KiB
Markdown
68 lines
No EOL
3.8 KiB
Markdown
### 设备间消息发送（Send-to-Device messaging）
|
||
|
||
本模块为客户端提供了一种交换信令消息的方式，这些消息不会作为共享通信历史的一部分被永久存储。每条消息将精确地送达每个客户端设备一次。
|
||
|
||
该 API 的主要动机是用于交换在房间有向无环图（DAG）中无意义或不希望持久保存的数据——例如，一次性身份验证令牌或密钥数据。它并不适用于会话内容，会话内容应使用常规的 [`/rooms/<room_id>/send`](/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) API 发送，以保持 Matrix 协议的一致性。
|
||
|
||
#### 客户端行为
|
||
|
||
要向其他设备发送消息，客户端应调用 [`/sendToDevice`](/client-server-api/#put_matrixclientv3sendtodeviceeventtypetxnid)。每个事务中，每台设备只能发送一条消息，且所有消息的事件类型必须一致。请求体中的设备ID可以设置为 `*`，以请求将消息发送到所有已知设备。
|
||
|
||
如果有等待客户端接收的设备间消息，这些消息将通过 [`/sync`](/client-server-api/#get_matrixclientv3sync) 返回，详见[对 /sync 的扩展](/client-server-api/#extensions-to-sync)。客户端应检查每个返回事件的 `type` 字段，并忽略其无法识别的事件。
|
||
|
||
#### 服务器行为
|
||
|
||
服务器应为本地用户存储待发送消息，直到它们成功送达目标设备。当客户端使用与有待发送消息的设备相关联的访问令牌调用 [`/sync`](/client-server-api/#get_matrixclientv3sync) 时，服务器应按到达顺序在响应体中列出这些待发送消息。
|
||
|
||
当客户端再次使用第一次响应中的 `next_batch` 令牌调用 `/sync` 时，服务器应推断该响应中的所有设备间消息已成功送达，并从存储中删除它们。
|
||
|
||
如果有大量待发送的设备间消息，服务器应限制在每次 `/sync` 响应中发送的消息数量。建议合理的上限为 100 条消息。
|
||
|
||
如果客户端向远程域的用户发送消息，这些消息应通过[联邦协议（federation）](/server-server-api#send-to-device-messaging)发送至远程服务器。
|
||
|
||
#### 协议定义
|
||
|
||
{{% http-api spec="client-server" api="to_device" %}}
|
||
|
||
##### 对 /sync 的扩展
|
||
|
||
本模块在 [`/sync`](/client-server-api/#get_matrixclientv3sync) 响应中增加了以下属性：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------------|-------------|--------------------------------------------------------------------|
|
||
| to_device | ToDevice | 可选。关于本客户端设备的设备间消息（send-to-device）信息。 |
|
||
|
||
`ToDevice`
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------------|-------------|----------------------------------------|
|
||
| events | [Event] | 设备间消息列表。 |
|
||
|
||
`Event`
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|-----------|----------------|------------------------------------------------------------------------------------------|
|
||
| content | EventContent | 本事件的内容。此对象中的字段将根据事件类型有所不同。 |
|
||
| sender | string | 发送本事件的 Matrix 用户ID。 |
|
||
| type | string | 事件类型。 |
|
||
|
||
示例响应：
|
||
|
||
```json
|
||
{
|
||
"next_batch": "s72595_4483_1934",
|
||
"rooms": {"leave": {}, "join": {}, "invite": {}},
|
||
"to_device": {
|
||
"events": [
|
||
{
|
||
"sender": "@alice:example.com",
|
||
"type": "m.new_device",
|
||
"content": {
|
||
"device_id": "XYZABCDE",
|
||
"rooms": ["!726s6s6q:example.com"]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
``` |