建议词 API

获取建议词列表

请求

HTTP 方法 GET
端点 /api/v2/suggest-words

向 Fess 发送 http://<Server Name>/api/v2/suggest-words?q=fes 等形式的请求，可以获取与输入前缀匹配的建议词列表（JSON 格式）。

建议词有以下三个来源：

  • 文档 — 由已抓取的文档生成。要获取此类建议词，需在管理界面的系统 > 常规中启用”按文档建议”。

  • 搜索词（搜索日志） — 由用户的搜索日志生成。要获取此类建议词，需在管理界面的系统 > 常规中启用”按搜索词建议”。

  • 用户词典 — 由管理员注册的建议词。无论以上设置如何，始终返回。

即使”按文档建议”和”按搜索词建议”均未启用，API 也不会报错，仅是相应的建议词不会出现在结果中。 此外，建议词会根据请求用户的角色自动进行过滤。

有关公共响应信封及错误模型，请参阅 API 概述。

请求参数

可用的请求参数如下。

请求参数
q 用于建议的搜索词（前缀）。如果省略，则不进行前缀过滤，直接返回建议词。（例）q=fes
num 建议词的数量（0 以上的整数）。默认值 10。如果指定了非数值，则使用默认值。（例）num=20
fn 限定建议范围的字段名。可重复指定，以数组形式处理。（例）fn=content&fn=title
lang 搜索语言。可重复指定，以数组形式处理。（例）lang=en
label 过滤的标签（标签名）。可重复指定，以数组形式处理。指定的值将与各建议词的 types 进行匹配。（例）label=java

Note

在 v2 中，指定字段名的参数为 fn（而非 v1 的 fields）。 fn 不使用逗号分隔，而是通过重复指定参数来传递多个值。

响应

成功时，返回如下公共信封格式的响应。

{
  "response": {
    "status": 0,
    "q": "fes",
    "page_size": 10,
    "record_count": 355,
    "query_time": 18,
    "suggest_words": [
      {
        "text": "fess",
        "types": [
          "label1"
        ]
      }
    ]
  }
}

response 各元素说明如下。

响应信息
q 请求的搜索词（字符串）。省略 q 时返回空字符串。
page_size 请求的建议词数量（num 的值，整数）。
record_count 建议词的匹配总数（64 位整数）。
query_time 查询处理时间，单位毫秒（64 位整数）。
suggest_words 建议词的数组。每个元素包含 text 和 types。
text 建议词（字符串）。
types 与建议词关联的标签数组（字符串数组）。各标签来源于文档的 label 或 virtual_host 字段的值，或从搜索日志中提取的过滤条件。没有标签时返回空数组。

Note

types 中存储的是标签值，而非建议词的种别（如 document 或 query 等种别值）。该数组对应 v1 建议词条目中的 labels 字段。 label 请求参数会对这些 types 值进行过滤。

使用示例

使用 curl 命令的请求示例：

curl "http://localhost:8080/api/v2/suggest-words?q=fes"

错误响应

建议词 API 失败时，将返回公共错误信封。错误模型详情请参阅 API 概述。

错误响应
状态码 说明
405 Method Not Allowed 指定了不支持的 HTTP 方法时。Allow 头中会指示 GET。
500 Internal Server Error 发生服务器内部错误时。