2.5 KiB
服务器端搜索
搜索 API 允许客户端对用户所加入过的所有房间中的事件进行全文搜索，包括用户已经离开的房间。仅搜索用户有权限查看的事件，例如，用户离开房间后发生的事件将不会被包含。
客户端行为
服务器端搜索有一个统一的 HTTP API，具体文档如下。
{{% http-api spec="client-server" api="search" %}}
搜索类别
搜索 API 允许客户端按不同类别进行搜索。目前唯一被明确定义的类别是 room_events。
room_events
该类别包含所有用户有权限查看的事件，包括用户已经离开的房间中的事件。搜索会在特定事件类型的特定键值上进行。
支持检索的字段包括：
m.room.message事件的content.bodym.room.name事件的content.namem.room.topic事件的content.topic
加密的房间（端对端加密）不会被包含在搜索范围内。
搜索结果包含一个 rank 键，可用于按相关度排序结果。rank 值越高，结果越相关。
count 字段用于大致表示总结果数。Homeserver 可能会返回一个估计值，而非精确值。
排序方式
客户端可以指定服务器返回结果的排序方式。允许的两种排序方式为：
rank：首先返回最相关的结果。recent：首先返回最新的结果。
默认排序方式为 rank。
分组
客户端可以请求返回带有分组信息的结果，例如按 room_id 分组。在这种情况下，响应中会包含每个不同 room_id 的分组条目。每个分组条目至少包含该分组内的 event_id 列表，也可能包含关于该分组的其他元数据。
当前要求支持的分组方式有：
room_idsender
分页
服务器响应中各处可能会返回一个 next_batch 键。它用于对结果进行分页。若需获取更多结果，客户端应使用相同的请求，并将 next_batch 查询参数设置为该标记。
分页的范围取决于 next_batch 标记返回的位置。例如，在分组内使用该标记将返回该分组中的更多结果。
目前支持的 next_batch 标记位置有：
search_categories.<category>.next_batchsearch_categories.<category>.groups.<group_key>.<group_id>.next_batch
即使存在更多匹配结果，服务器也可以选择不支持分页。在这种情况下，响应中不得返回 next_batch 标记。
安全性注意事项
服务器只能返回用户有权限查看的结果。