数据处理

更新时间:
复制 MD 格式

使用 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),服务器将拒绝接收任何参数,同时返回异常。