文档目录
从这里开始
REST API参考
索引和搜索API鉴权创建索引添加文档搜索文档API错误码

REST API


本文主要面向直接用RESTful API请求卡拉搜索的用户,或SDK开发者,对绝大多数用户,请直接使用卡拉搜索提供的SDK

为了保证速度,卡拉搜索的引擎和所有服务构建在一个HTTP服务器上,所有的外部通讯均由REST API承担。因此,所有用SDK可以完成的操作用REST API均可以完成。事实上,卡拉搜索的所有SDK都是在REST API上进行的封装。

如果我们暂时没有支持你所常用的语言或框架,不用着急,你可以考虑直接集成REST API来接入卡拉搜索。在本文中,我们介绍所有可用REST API的端点、参数,并给出例子方便调试。

API鉴权


为了保护你的数据,每次API请求我们都需要你在请求的Header中提供X-Kalasearch-Id (下文简称AppId)和X-Kalasearch-Key (下文简称apiKey)

X-Kalasearch-Id代表你请求的对应App的Id。在卡拉搜索后台,你可以看到你所创建的所有App,每个App都有自己的一个唯一id

X-Kalasearch-Key 代表你请求的App对应的key,可以简单把它想象成密码,只有密码正确,卡拉搜索才会让这个请求通过

X-Kalasearch-IdX-Kalasearch-Key这两者可以在卡拉搜索后台界面很容易找到,在请求时请将这二者置于HTTP请求的header中,如下文例子中所示

创建索引


一个索引(index)是你的数据的一个有机集合,通常来说我们建议将一个业务的所有数据放在一个索引中。关于索引概念的详细介绍,请参考:搜索概念-索引。

API端点

POST
https://api.kalasearch.cn/indexes

参数

参数描述说明
indexName索引名(必填)至少3个字符,不可重复

请求示例

curl -X POST \
--header 'X-Kalasearch-Id: 359fe1a0-5111-483f-974a-f4cb8dd0187b' \
--header 'X-Kalasearch-Key: 706ad941-cd28-46df-b25b-62da93e24ea9' \
--header 'Content-Type: application/json' \
-d '{
"indexName": "movies"
}' "https://api.kalasearch.cn/indexes"

返回示例 200

{
"rankers": [],
"id": "5e3ed59c-393b-43f4-a4ec-36bff7d5d8cc",
"indexName": "movies",
"highlightFields": [],
"searchableFields": [],
"appId": "359fe1a0-5111-483f-974a-f4cb8dd0187b",
"createdAt": "2020-06-27T17:51:58.200116Z",
"updatedAt": "2020-06-27T17:51:58.200126Z",
"numericFields": []
}

添加文档


在建立索引之后,你可以立即开始尝试添加文档至索引中。

请注意,这里的文档是泛指你可能用于搜索的任何数据。比如,如果你的业务是电商,那么对于你而言一个文档更有可能是一件商品的信息;而如果你的业务是游戏,那么对你而言,一个文档可能是一位玩家或装备的数据。请参考:搜索概念-文档

API端点

POST
https://api.kalasearch.cn/indexes/:indexId/docs

请注意,本端点中的indexId是你希望添加文档至的索引id,由创建索引端点返回,或在卡拉搜索后台界面可以查看所有索引的信息,包括indexId

参数

参数描述说明
JSON文档JSON格式的文档请注意格式并置于请求的body中,较易出错

请求示例

curl -X POST \
--header 'X-Kalasearch-Id: 359fe1a0-5111-483f-974a-f4cb8dd0187b' \
--header 'X-Kalasearch-Key: 706ad941-cd28-46df-b25b-62da93e24ea9' \
--header 'Content-Type: application/json' \
-d '{
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}' "https://api.kalasearch.cn/indexes/5e3ed59c-393b-43f4-a4ec-36bff7d5d8cc/docs"

返回示例 200

{
"_id": "K06aHnIBzLP-GFv2jrmY"
}

搜索文档


在你向索引添加了一些文档之后,即可开始进行搜索。对于绝大多数应用来说,搜索操作远多于索引操作和添加文档操作。

API端点

POST
https://api.kalasearch.cn/indexes/:indexId/query

请注意,这里的indexId是你希望查询的索引的id,可以通过卡拉后台获得。

参数

参数描述说明
query搜索词用于搜索的搜索词,如 大话

示例

curl -X POST \
--header 'X-Kalasearch-Id: 359fe1a0-5111-483f-974a-f4cb8dd0187b' \
--header 'X-Kalasearch-Key: 706ad941-cd28-46df-b25b-62da93e24ea9' \
--header 'Content-Type: application/json' \-d '{
"query": "大话"
}' "https://api.kalasearch.cn/indexes/5e3ed59c-393b-43f4-a4ec-36bff7d5d8cc/query"

返回

{
"totalHits": 1,
"hits": [
{
"_id": "kEzXC3IBzLP-GFv2-m-T",
"_source": {
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}
}
],
"queryTimeUsed": 1
}
返回项描述说明
totalHits匹配的搜索结果总数
hits匹配的所有文档(array)文档中的_source为你添加文档时的JSON数据
queryTimeUsed匹配所用时间(毫秒)用于显示搜索速度

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用json检查器检查格式
© 2020, 卡拉搜索, Built with ❤️ in San Francisco + Beijing

京ICP备15049164号-3