文档目录
从这里开始
REST API参考
索引和搜索文档注解API 鉴权创建对象更新对象搜索批量添加或更新对象查询任务状态删除对象API错误码

注:卡拉搜索目前正在封闭内测,如果你感兴趣在你的项目中使用卡拉搜索,请邮件我们,邮件地址是 kalasearch@gmail.com

REST API


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

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

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

文档注解

请注意,下文中所有用花括号的地方,如 v1/indexes/{indexId}/objects/batch 里的 {indexId} 均代表一个可替代的变量。

比如这里的 {indexId} 代表你应该将 {indexId} 替换为你的索引的具体 id。

API 鉴权


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

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

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

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

请注意,每个 API 密钥都有其对应的读写权限。如果在前端使用(如网页、APP 内等)请使用只读密钥。对于详细的数据安全建议,请参考: 数据安全

创建对象


在卡拉搜索后台建立好索引之后,你可以立即开始尝试添加对象至索引中。

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

API端点

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/objects

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

参数

参数描述说明
JSON 对象JSON 格式的对象请注意格式并置于请求的 body 中(容易出错)

注:目前 JSON 对象中的值类型暂时不支持数组和嵌套 JSON。以下几种为目前支持的域

  • string: 字符串类型
  • number: 数字类型
  • boolean: 布尔类型

请求示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/2bd1fe90-4bc6-41ec-b04d-7f52a757d14a/objects' \
--header 'X-Kalasearch-Id: 981b9401-82fb-4efb-b5e4-c123ceac38da' \
--header 'X-Kalasearch-Key: 6a3125c5-67d6-4e28-8e28-7324f40a6acc' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
}'

返回示例 200

{
"processedAt": "2020-08-08T23:34:09.673198Z",
"id": "x65s0HMBqHxfM3zkrJ8H",
"operation": "ADD_OBJECT"
}

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用 json检查器 检查格式
400Type conflict域类型冲突:如果你之前索引的对象中出现过不同类型的数据,则会报错。详见错误代码

更新对象


如果你需要更新已经创建的对象,可以用更新对象端点来进行更新。更新对象端点也可以用于添加对象,详见下文。

API端点

PUT
https://api.kalasearch.cn/v1/indexes/{indexId}/objects/{objectId}

这里的 indexId 是你希望更新对象所在的索引 id,objectId 是你希望更新的对象的 id。

如果在这个索引中 objectId 对应的对象存在,那么这个对象将被更新。

请注意如果在这个索引中,如果对应的 objectId 不存在,那么服务器会自动创建一个新的对象,效果等同于添加一个对象。

用更新对象端点来创建一个对象,与直接使用添加对象端点唯一的区别是:这个被添加的对象会使用你指定的 objectId

因此,如果你需要保持数据库与索引同步,那么可以用数据库的 id 作为 objectId,定时运行更新来确保数据库中的数据与索引中的数据一致。

举个例子,在你的数据库中可能有以下三条数据

id用户名用户活跃度密码上次上线时间
001张飞887&39kjd1天前
002王小虎43&j2kucj3天前
003李天王99Hsuejck12天前

那么如果你需要同步数据库与搜索引擎,且使用数据库的 id 作为卡拉引擎中的对象 id 的话,请发送以下请求来将第一行用户 张飞 的对象添加到搜索引擎中。

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/ca7269b4-9c6e-4b33-9cfc-54376987a15d/objects/001' \
--header 'X-Kalasearch-Id: 355f7ac7-5449-4ade-b4a6-1d5aeaed4143' \
--header 'X-Kalasearch-Key: 5aeac200-4270-429a-b0b8-ef3a823f78ab' \
--header 'Content-Type: application/json' \
--data-raw '
{
"id": "001",
"userName": "张飞",
"activeLevel": 88,
"lastLogin": "1天前"
}'

请注意,这里 URL 中的 001 是必须的,而 JSON 数据中的 id: 001 是可选的,是否添加取决于你是否希望搜索出来的结果中含有 id 方便下一步操作(比如用于查询数据库)

参数

参数描述说明
JSON 对象JSON 格式的对象请注意格式并置于请求的 body 中(容易出错)

注:目前 JSON 对象中的值类型暂时不支持数组和嵌套 JSON。以下几种为目前支持的域

  • string: 字符串类型
  • number: 数字类型
  • boolean: 布尔类型

请求示例

curl --location --request PUT 'https://api.kalasearch.cn/v1/indexes/2bd1fe90-4bc6-41ec-b04d-7f52a757d14a/objects/x65s0HMBqHxfM3zkrJ8H' \
--header 'X-Kalasearch-Id: 981b9401-82fb-4efb-b5e4-c123ceac38da' \
--header 'X-Kalasearch-Key: 6a3125c5-67d6-4e28-8e28-7324f40a6acc' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "无间道",
"actors": "刘德华",
"year": 2000
}'

返回示例 200

{
"processedAt": "2020-08-08T23:54:24.000985Z",
"id": "x65s0HMBqHxfM3zkrJ8H",
"operation": "UPDATE_OBJECT"
}

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
400Unable to process JSONbody格式不正确,请用 json检查器 检查格式
400Type conflict域类型冲突:如果你之前索引的对象中出现过不同类型的数据,则会报错。详见错误代码

搜索


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

API端点

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/query

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

参数

参数描述说明
query搜索词用于搜索的搜索词,如 大话
filters过滤器用于过滤搜索结果,如 isMale: true 关于卡拉支持的过滤语法请见搜索结果过滤

示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/2bd1fe90-4bc6-41ec-b04d-7f52a757d14a/query' \
--header 'X-Kalasearch-Id: 981b9401-82fb-4efb-b5e4-c123ceac38da' \
--header 'X-Kalasearch-Key: 6a3125c5-67d6-4e28-8e28-7324f40a6acc' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "大话",
"filters": "isFunny:true"
}'

返回

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

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数

批量添加或更新对象


如果你需要一次性添加较多的对象,可以采用批量添加的端点。建议每次更新不多于 5000 个对象以免请求超时

API端点

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/objects/batch

这里的 indexId 是你希望更新对象所在的索引 id。

如果你在对象的 JSON 中加入了 id,那么批量添加时服务器会更新这些对象。比如说,如果你的批量添加对象如下

[
{
"id": "1000001",
"name": "周杰伦"
},
{
"name": "陈冠希"
}
]

那么第一个对象将会使用 id = 1000001,而服务器会为第二个对象创建一个 id。如果你希望保持 id 与你的数据库中的对象一致,那么可以考虑使用数据库中的 id 作为对象的 id 值。

参数

参数描述说明
JSON 对象数组JSON 格式的对象组成的数组请注意格式并置于请求的 body 中(容易出错)

注:目前 JSON 对象中的值类型暂时不支持数组和嵌套 JSON。以下几种为目前支持的域

  • string: 字符串类型
  • number: 数字类型
  • boolean: 布尔类型

请求示例

curl --location --request POST 'https://api.kalasearch.cn/v1/indexes/ca7269b4-9c6e-4b33-9cfc-54376987a15d/objects/batch' \
--header 'X-Kalasearch-Id: 355f7ac7-5449-4ade-b4a6-1d5aeaed4143' \
--header 'X-Kalasearch-Key: 5aeac200-4270-429a-b0b8-ef3a823f78ab' \
--header 'Content-Type: application/json' \
--data-raw '
[{
"name": "大话西游",
"actors": "周星驰/吴孟达",
"year": 1998
},
{
"name": "无间道",
"actors": "刘德华",
"year": 2000
}]'

返回示例 200

{
"id": "429ddbc3-76ee-41c3-9110-4747a55497ee",
"status": "STARTING"
}
返回项描述说明
id提交的任务 id,如需查询任务状态需要用这个 id
status任务运行状态,刚提交的任务为 STARTING

请注意,这里返回的是成功提交了一个添加对象的后台任务。具体的任务完成需要一定的时间,请耐心等待。如果需要查询提交的任务完成状态,请用查询任务状态端点。

查询任务状态


如果你提交了一个批量添加对象的任务,可以调用以下端点查询任务状态

API端点

POST
https://api.kalasearch.cn/v1/indexes/{indexId}/jobs/{jobId}

这里的 indexId 是你希望更新对象所在的索引 id,jobId 是提交任务时返回给你的 id

请求示例

curl --location --request GET 'https://api.kalasearch.cn/v1/indexes/ca7269b4-9c6e-4b33-9cfc-54376987a15d/jobs/429ddbc3-76ee-41c3-9110-4747a55497ee' \
--header 'X-Kalasearch-Id: 355f7ac7-5449-4ade-b4a6-1d5aeaed4143' \
--header 'X-Kalasearch-Key: 5aeac200-4270-429a-b0b8-ef3a823f78ab'

返回示例 200

{
"id": "e5ca80fd-6c85-4165-94a5-bbef6d423867",
"status": "COMPLETED",
"hasErrors": true,
"results": [
{
"result": {
"processedAt": "2020-08-09T06:39:20.588125Z",
"id": "m3jx0XMBDnZIKjln8DsG",
"operation": "ADD_OBJECT"
}
},
{
"error": {
"message": "Type conflict for field \"year\": this field was indexed with another type before",
"code": "INPUT_NOT_VALID"
}
}
]
}
返回项描述说明
id提交的任务 id
status任务状态 COMPLETED 则为完成
hasErrors提交的任务中有无错误只要有任何一个错误,hasErrors 就会是 true
results数组,代表具体每个添加对象的完成情况如果有错误,则为 error,否则返回处理对象的结果

请注意,任务可能部分失败,失败的对象将会被忽略,只有成功添加的对象会被索引。

使用批量添加或更新时,我们建议先新建一个测试索引,并用单个添加端点确认对象格式转化为 JSON 没有问题后,然后再新建一个正式索引用批量添加或更新加速对象。

删除对象


如果你需要删除已经创建的对象,可以用本端点进行删除

API端点

DELETE
https://api.kalasearch.cn/v1/indexes/{indexId}/objects/{objectId}

这里的 indexId 是你希望删除对象所在的索引 id,objectId 是你希望删除的对象 id。

如果在这个索引中 objectId 对应的对象存在,那么这个对象将被删除。

请注意如果在这个索引中,对应的 objectId 不存在,那么服务器仍然会返回删除成功,但其实没有对象被真正删除。

参数

请求示例

curl --location --request DELETE 'https://api.kalasearch.cn/v1/indexes/2bd1fe90-4bc6-41ec-b04d-7f52a757d14a/objects/x65s0HMBqHxfM3zkrJ8H' \
--header 'X-Kalasearch-Id: 981b9401-82fb-4efb-b5e4-c123ceac38da' \
--header 'X-Kalasearch-Key: 6a3125c5-67d6-4e28-8e28-7324f40a6acc'

返回示例 200

{
"processedAt": "2020-08-09T00:40:55.050423Z",
"id": "x65s0HMBqHxfM3zkrJ8H",
"operation": "DELETE_OBJECT"
}

错误信息

HTTP状态码返回消息(message)说明
404index does not exist索引不存在,请检查indexId参数
© 2020, 卡拉搜索, Built with ❤️ in San Francisco + Beijing

京ICP备15049164号-3