使用 OpenSearch 召回引擎版流量 API 批量新增和删除文档。高可用版本还支持批量更新文档的指定属性字段。
URL
/update/$table_name/actions/bulk
-
$table_name 为数据源名称
-
以上 URL 省略了请求Header参数及编码等因素
-
以上 URL 中省略了访问应用的 host 地址
支持格式
JSON
HTTP请求方式
POST
Header参数
|
参数 |
类型 |
描述 |
|
authorization |
string |
签名 |
|
X-Opensearch-Swift-PK-Field |
string |
推送索引表主键,示例:id |
|
host |
string |
请求host,可在实例详情>API入口>API域名查看,示例:ha-cn-**********.ha.aliyuncs.com |
签名机制
可用以下方法计算签名(authorization)
|
参数 |
类型 |
描述 |
|
accessUserName |
string |
用户名,可在实例详情页>网络信息 查看 |
|
accessPassWord |
string |
密码,可在实例详情页>网络信息 修改 |
import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;
public class GenerateAuthorization {
public static void main(String[] args) throws Exception {
String accessUserName = "username";
String accessPassWord = "password";
String realmStr = "" + accessUserName + ":" + accessPassWord + "";
String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
System.out.println(authorization);
}
}
authorization正确返回格式
cm9vdDp******mdhbA==
注意:使用HTTP请求设置authorization参数是需加上Basic前缀
示例:
authorization: Basic cm9vdDp******mdhbA==
文档数据格式(body)
[
{
"cmd": "add",
"fields": {
"id": "1",
"title": "This is the title",
"body": "This is the body"
}
},
{
"cmd": "delete",
"fields": {
"id": "3"
}
}
]
-
cmd为必选字段,用于指定操作。标准版本支持add和delete,高可用版本还支持update_field。add新增文档。主键对应的文档已存在时,系统先删除原文档,再添加新文档。delete删除文档。主键对应的文档不存在时,系统仍视为删除成功。update_field更新指定的属性字段。可更新的单值属性字段类型包括INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、DOUBLE、DATE、TIME和TIMESTAMP。要更新单值
STRING属性字段,请在索引表配置中将该字段的updatable_multi_value设置为true。 -
fields为必选字段,必须包含文档主键。执行delete时仅需提供主键。执行update_field时,提供主键和要更新的属性字段及其新值。 -
对于Array类型,需要使用JsonArray来处理,如[{“fields”: { “id”: “0”,”int_array”: [14,85],”string_array”: [“abc”,”xyz”]},”cmd”: “add”}];
-
请求体为 JSON 数组。可在一次请求中操作多个文档,以减少网络开销。
示例
请求:(此处省略了请求Header参数及编码等因素)
http://ha-cn-**********.ha.aliyuncs.com/update/$table_name/actions/bulk
//下面的待上传数据,需要放到body体中
[{
"cmd": "add",
"fields": {
"id": 1,
"name": "Test Data Push"
}
}]
以下请求体适用于高可用版本。假设 stock 是 INT32 类型的属性字段,示例将两条已有文档的 stock 分别更新为 12 和 18。
[
{
"cmd": "update_field",
"fields": {
"id": "1",
"stock": 12
}
},
{
"cmd": "update_field",
"fields": {
"id": "2",
"stock": 18
}
}
]
成功返回
HTTP 200 且响应体为空表示系统已接收请求。数据处理为异步操作,推送后可查询文档确认更新结果。
错误返回
[
{
"code": 3012,
"message": "Resource not found."
}
]
注意事项
-
使用API/SDK推送数据时,应用的字段名称大小写不敏感。
-
使用API/SDK推送数据有次数及大小限制,不同应用限制不同,具体请参考系统限制描述。
-
数据上传后请务必检查返回值,并对相关错误码进行重试(尤其是3007错误),否则会出现数据丢失情况。同时,数据处理是异步的,系统返回“OK”后只表示系统接收数据成功,数据处理过程的错误会在控制台错误信息中展示,请注意及时检查。
-
POST的数据大小有限制,如果您上传的文档总量过大(编码前2M),服务器将拒绝接收任何参数,同时返回异常。