docs-matrix-spec/locales/zh-Hans/client-server-api/modules/guest_access.md

客户端访客访问

有时，客户端无需在主服务器上完整注册账户或加入房间即可与房间进行交互是更为理想的。本模块规定了此类客户端应如何与服务器交互，以便以访客身份参与房间。

访客用户通过使用普通的注册接口从主服务器获取访问令牌，将 kind 参数指定为 guest。随后，他们可以像其他用户一样与客户端-服务器 API 进行交互，但如客户端行为子章节所述，仅能访问 API 的子集。主服务器可以选择是否允许本地用户的访客访问，但并不了解其他主服务器上的用户是否为访客。

访客用户也可以通过正常的 register 流程升级其账户，需额外指定一个 POST 参数 guest_access_token，其值为访客令牌。同时，他们还需指定 username 参数（即用户名本地部分），该参数在其他情况下为可选项。

本模块并未完全考虑联合互通（Federation）；它依赖于单个主服务器正确遵守本模块设定的规则，而不是允许所有主服务器相互强制执行这些规则。

事件

{{% event event="m.room.guest_access" %}}

客户端行为

访客账户允许通过以下 API 端点获取事件及相关媒体资源：

• GET /rooms/{roomId}/state
• GET /rooms/{roomId}/context/{eventId}
• GET /rooms/{roomId}/event/{eventId}
• GET /rooms/{roomId}/state/{eventType}/{stateKey}
• GET /rooms/{roomId}/messages
• {{% added-in v="1.1" %}} GET /rooms/{roomId}/members
• GET /rooms/{roomId}/initialSync
• GET /sync
• GET /events 用于房间预览。
• {{% added-in v="1.12" %}} GET /media/download/{serverName}/{mediaId}
• {{% added-in v="1.12" %}} GET /media/download/{serverName}/{mediaId}/{fileName}
• {{% added-in v="1.12" %}} GET /media/thumbnail/{serverName}/{mediaId}

访客账户允许通过以下 API 端点发送事件：

• POST /rooms/{roomId}/join

• POST /rooms/{roomId}/leave

• PUT /rooms/{roomId}/send/{eventType}/{txnId}

  • {{% changed-in v="1.2" %}} 访客现在可以发送任何类型的事件，而不仅限于 m.room.message 事件。

• {{% added-in v="1.2" %}} PUT /rooms/{roomId}/state/{eventType}/{stateKey}

• PUT /sendToDevice/{eventType}/{txnId}

访客账户允许通过以下 API 端点维护其自身账户：

• PUT /profile/{userId}/displayname
• GET /devices
• GET /devices/{deviceId}
• PUT /devices/{deviceId}
• {{% added-in v="1.2" %}} GET /account/whoami

访客账户允许通过以下 API 端点进行端到端加密操作：

• POST /keys/upload
• POST /keys/query
• POST /keys/claim

服务器行为

服务器必须仅在房间内存在 m.room.guest_access 状态事件且其 guest_access 值为 can_join 时允许访客用户加入房间。如果 m.room.guest_access 事件被修改为不再允许访客加入，服务器必须将这些访客用户的 m.room.member 状态设置为 leave。

安全性考量

每个主服务器自行管理其访客账户，身份是否为访客账户的信息不会在服务器之间传递。因此，参与房间的任何服务器都被信任能够正确执行本节列出的权限规定。

主服务器可以考虑在访客注册时启用如验证码等保护措施，以防止垃圾信息、拒绝服务（DoS）等攻击。

主服务器可能会对访客账户采取更严格的速率限制，尤其是针对发送状态事件的操作。