67 lines
No EOL
4.4 KiB
Markdown
67 lines
No EOL
4.4 KiB
Markdown
### 客户端访客访问
|
||
|
||
有时，客户端无需在主服务器上完整注册账户或加入房间即可与房间进行交互是更为理想的。本模块规定了此类客户端应如何与服务器交互，以便以访客身份参与房间。
|
||
|
||
访客用户通过使用普通的[注册接口](#post_matrixclientv3register)从主服务器获取访问令牌，将 `kind` 参数指定为 `guest`。随后，他们可以像其他用户一样与客户端-服务器 API 进行交互，但如客户端行为子章节所述，仅能访问 API 的子集。主服务器可以选择是否允许本地用户的访客访问，但并不了解其他主服务器上的用户是否为访客。
|
||
|
||
访客用户也可以通过正常的 `register` 流程升级其账户，需额外指定一个 POST 参数 `guest_access_token`，其值为访客令牌。同时，他们还需指定 `username` 参数（即用户名本地部分），该参数在其他情况下为可选项。
|
||
|
||
本模块并未完全考虑联合互通（Federation）；它依赖于单个主服务器正确遵守本模块设定的规则，而不是允许所有主服务器相互强制执行这些规则。
|
||
|
||
#### 事件
|
||
|
||
{{% event event="m.room.guest_access" %}}
|
||
|
||
#### 客户端行为
|
||
|
||
访客账户允许通过以下 API 端点获取事件及相关媒体资源：
|
||
|
||
* [GET /rooms/{roomId}/state](#get_matrixclientv3roomsroomidstate)
|
||
* [GET /rooms/{roomId}/context/{eventId}](#get_matrixclientv3roomsroomidcontexteventid)
|
||
* [GET /rooms/{roomId}/event/{eventId}](#get_matrixclientv3roomsroomideventeventid)
|
||
* [GET /rooms/{roomId}/state/{eventType}/{stateKey}](#get_matrixclientv3roomsroomidstateeventtypestatekey)
|
||
* [GET /rooms/{roomId}/messages](#get_matrixclientv3roomsroomidmessages)
|
||
* {{% added-in v="1.1" %}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
|
||
* [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync)
|
||
* [GET /sync](#get_matrixclientv3sync)
|
||
* [GET /events](#get_matrixclientv3events) 用于房间预览。
|
||
* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
|
||
* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
|
||
* {{% added-in v="1.12" %}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
|
||
|
||
访客账户允许通过以下 API 端点发送事件：
|
||
|
||
* [POST /rooms/{roomId}/join](#post_matrixclientv3roomsroomidjoin)
|
||
* [POST /rooms/{roomId}/leave](#post_matrixclientv3roomsroomidleave)
|
||
* [PUT /rooms/{roomId}/send/{eventType}/{txnId}](#put_matrixclientv3roomsroomidsendeventtypetxnid)
|
||
|
||
* {{% changed-in v="1.2" %}} 访客现在可以发送*任何*类型的事件，而不仅限于 `m.room.message` 事件。
|
||
|
||
* {{% added-in v="1.2" %}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
|
||
* [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientv3sendtodeviceeventtypetxnid)
|
||
|
||
访客账户允许通过以下 API 端点维护其自身账户：
|
||
|
||
* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
|
||
* [GET /devices](#get_matrixclientv3devices)
|
||
* [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
|
||
* [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
|
||
* {{% added-in v="1.2" %}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
|
||
|
||
访客账户允许通过以下 API 端点进行端到端加密操作：
|
||
|
||
* [POST /keys/upload](#post_matrixclientv3keysupload)
|
||
* [POST /keys/query](#post_matrixclientv3keysquery)
|
||
* [POST /keys/claim](#post_matrixclientv3keysclaim)
|
||
|
||
#### 服务器行为
|
||
|
||
服务器**必须**仅在房间内存在 `m.room.guest_access` 状态事件且其 `guest_access` 值为 `can_join` 时允许访客用户加入房间。如果 `m.room.guest_access` 事件被修改为不再允许访客加入，服务器**必须**将这些访客用户的 `m.room.member` 状态设置为 `leave`。
|
||
|
||
#### 安全性考量
|
||
|
||
每个主服务器自行管理其访客账户，身份是否为访客账户的信息不会在服务器之间传递。因此，参与房间的任何服务器都被信任能够正确执行本节列出的权限规定。
|
||
|
||
主服务器可以考虑在访客注册时启用如验证码等保护措施，以防止垃圾信息、拒绝服务（DoS）等攻击。
|
||
|
||
主服务器可能会对访客账户采取更严格的速率限制，尤其是针对发送状态事件的操作。 |