更新时间：2025-05-20 GMT+08:00

批量写请求

功能介绍

批量写请求，其中可以携带一或多个表的不同kv的写操作，上传kv/删除kv。

URI

POST /v1/batch-write-kv

表1 Query参数
参数	是否必选	参数类型	描述
store_name	否	String	仓名，全域唯一，不同租户的仓名不能相同。格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
table_opers	是	Array of table_batch objects	行操作数组，可以是多个表的操作。

表3 table_batch
参数	是否必选	参数类型	描述
table_name	是	String	表名，仓内唯一。长度：[3, 52] 取值字符限制：[a-z0-9_-]+
kv_opers	是	Array of oper_item objects	kv操作数组。

表4 oper_item
参数	是否必选	参数类型	描述
put_kv	否	put_kv object	上传kv操作。
delete_kv	否	delete_kv object	删除kv操作。

表5 put_kv
参数	是否必选	参数类型	描述
oper_id	是	Integer	请求内的操作编码，未成功的操作返回该标识。
kv_doc	否	Document	用户文档。

表6 delete_kv
参数	是否必选	参数类型	描述
oper_id	是	Integer	请求内的操作编码，未成功的操作返回该标识。
primary_key	是	Document	用户自定义的主键名及值。

响应参数

状态码：200

表7 响应Body参数
参数	参数类型	描述
unprocessed_opers	Array of table_oper_ids objects	未处理的操作列表。

表8 table_oper_ids
参数	参数类型	描述
table_name	String	表名，仓内唯一。长度：[3, 52] 取值字符限制：[a-z0-9_-]+
kv_oper_ids	kv_oper_ids object	kv操作数组。

表9 kv_oper_ids
参数	参数类型	描述
put_kv_ids	Array of integers	上传kv操作, "oper_id"数组。数组元素：请求内的操作编码，未成功的操作返回该标识。
delete_kv_ids	Array of integers	请求内的操作编码，未成功的操作返回该标识。数组元素：请求内的操作编码，未成功的操作返回该标识。

状态码：400

BatchExceedLimit

请求示例

批量写请求，向test-store仓内的test-table-1表中插入和删除一个kv

POST https://test-store.{endpoint}/v1/batch-write-kv

{
  "table_opers" : [ {
    "table_batch" : {
      "table_name" : "test-table-1",
      "kv_opers" : [ {
        "put_kv" : {
          "oper_id" : 1,
          "kv_doc" : {
            "owner" : "user-1",
            "filename" : "test-file-1"
          }
        }
      }, {
        "delete_kv" : {
          "oper_id" : 2,
          "primary_key" : {
            "owner" : "user-2",
            "filename" : "test-file-2"
          }
        }
      } ]
    }
  } ]
}