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