coco/concept-search-api

Concept Search API

用于在Amazon Elasticsearch集群中搜索概念的API服务。

注意：AWS SDK for Go目前https://github.com/aws/aws-sdk-go/issues/710%EF%BC%8C%E4%BD%86%E8%87%AAv1.2.0%E7%89%88%E6%9C%AC%E8%B5%B7%E5%B7%B2%E6%9A%B4%E9%9C%B2%E7%AD%BE%E5%90%8D%E5%99%A8%EF%BC%88Signer%EF%BC%89%E3%80%82

访问AES（Amazon Elasticsearch Service）的实现方式：

• 基于https://github.com/smartystreets/go-aws-auth%E5%88%9B%E5%BB%BA%E4%BC%A0%E8%BE%93%E5%B1%82%EF%BC%8C%E4%BD%BF%E7%94%A8v4%E7%AD%BE%E5%90%8D%E5%99%A8%E3%80%82
• 通过上述创建的客户端，使用https://github.com/olivere/elastic%E5%BA%93%E5%A4%84%E7%90%86%E6%89%80%E6%9C%89ES%E8%AF%B7%E6%B1%82%E3%80%82

核心功能与特性

• 支持Amazon Elasticsearch Service的安全访问（v4签名认证）
• 提供灵活的搜索参数配置（端点、区域、端口、索引名等）
• 实现概念搜索与类型提前查询两种数据端点
• 内置健康检查机制，支持服务状态监控
• 可配置搜索结果限制数量及是否包含评分

使用场景

适用于需要从Amazon Elasticsearch集群中检索概念数据的应用场景，如内容管理系统、知识图谱查询、自动补全功能等。

使用方法

环境准备

确保本地已安装dep工具，如未安装，执行以下命令：

bash
curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh

构建与运行

bash
mkdir $GOPATH/src/github.com/Financial-Times/concept-search-api
cd $GOPATH/src/github.com/concept-search-api
git clone https://github.com/Financial-Times/concept-search-api.git
cd concept-search-api && dep ensure -vendor-only
go build
./concept-search-api --aws-access-key="{access key}" --aws-secret-access-key="{secret key}"

配置参数

可通过命令行参数配置服务，支持以下参数（未指定时使用默认值）：

• aws-access-key：AWS访问密钥（必填）
• aws-secret-access-key：AWS密钥（必填）
• elasticsearch-endpoint：Elasticsearch端点
• elasticsearch-region：Elasticsearch区域
• port：服务运行端口（默认：8080）
• index-name：搜索索引名（默认：concept）
• elasticsearch-index：Elasticsearch索引（默认：concept）
• search-result-limit：最大返回结果数（默认：50）
• elasticsearch-trace：是否启用ES跟踪（默认：false）

测试方法

运行完整测试套件

需本地运行Elasticsearch实例，并设置环境变量：

bash
export ELASTICSEARCH_TEST_URL=http://localhost:9200

执行测试命令：

bash
go test -race ./...

跳过集成测试

使用-short选项跳过集成测试：

bash
go test -race -short ./...

数据端点

POST /concept/search

用于搜索概念，请求体为包含term字段的JSON，term值为搜索条件。

请求示例

搜索"FOO"：

bash
curl -XPOST {concept-search-api-url}/concept/search -d '{"term":"FOO"}'

可选查询参数

• include_score=true：返回结果中包含匹配分数

  bash
  curl -XPOST {concept-search-api-url}/concept/search?include_score=true -d '{"term":"FOO"}'
  

• searchAllAuthorities=true：扩展搜索域至所有权威来源（TME、Smartlogic、Factset等）

  bash
  curl -XPOST {concept-search-api-url}/concept/search?searchAllAuthorities=true -d '{"term":"FOO"}'
  

• include_deprecated=true：包含已弃用的概念

  bash
  curl -XPOST {concept-search-api-url}/concept/search?include_deprecated=true -d '{"term":"FOO"}'
  

响应示例

json
[
  {
    "id": "http://api.ft.com/things/d79f6383-9271-3a03-aacd-5ce8e57d6f5e",
    "apiUrl": "http://api.ft.com/organisations/d79f6383-9271-3a03-aacd-5ce8e57d6f5e",
    "prefLabel": "FOO LLC",
    "types": [
      "http://www.ft.com/ontology/core/Thing",
      "http://www.ft.com/ontology/concept/Concept",
      "http://www.ft.com/ontology/organisation/Organisation"
    ],
    "directType": "http://www.ft.com/ontology/organisation/Organisation",
    "aliases": ["FOO LLC", "FOO"],
    "score": 10.117536,
    "isDeprecated": true
  },
  {
    "id": "http://api.ft.com/things/87c69c2c-ad53-3888-9958-835098db4dae",
    "apiUrl": "http://api.ft.com/organisations/87c69c2c-ad53-3888-9958-835098db4dae",
    "prefLabel": "FOO International",
    "types": [
      "http://www.ft.com/ontology/core/Thing",
      "http://www.ft.com/ontology/concept/Concept",
      "http://www.ft.com/ontology/organisation/Organisation"
    ],
    "directType": "http://www.ft.com/ontology/organisation/Organisation",
    "aliases": ["FOO International", "FOO INTERNATIONAL"],
    "score": 2.8585405
  }
]

响应状态码

• 404：未找到结果
• 400：请求体格式错误
• 500：搜索服务内部错误

GET /concepts

用于类型提前（typeahead）风格的概念查询，type参数为必填项。

基础请求示例（查询Genre类型）

bash
curl {concept-search-api-url}/concepts?type=http://www.ft.com/ontology/Genre

可选查询参数

• mode=search：激活搜索模式，需配合q参数指定搜索词

  bash
  curl {concept-search-api-url}/concepts?type=http://www.ft.com/ontology/organisation/Organisation&mode=search&q=FOO
  

• boost=authors：在搜索模式下提升作者相关结果（仅支持作者类型）

  bash
  curl {concept-search-api-url}/concepts?type=http://www.ft.com/ontology/person/Person&mode=search&q=FOO&boost=authors
  

• searchAllAuthorities=true：扩展搜索域至所有权威来源
• include_deprecated=true：包含已弃用的概念

健康检查端点

GET /__health

返回标准FT格式的服务连通性和集群健康状态。

GET /__health-details

返回ES集群的详细健康状态，格式与{elasticsearch-endpoint}/_cluster/health一致。服务不可用时返回503。

GET /__gtg

服务健康时返回200，不健康时返回503（服务不可用）。

更多详情请参见Swagger YML。