调用PutRow接口插入数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

说明

若指定行不存在，则新增该行；若指定行已存在，则覆盖原有数据。
调用成功时，返回结果中无错误信息。

请求消息结构

message PutRowRequest {
    required string table_name = 1;
    required bytes row = 2; // Plainbuffer编码为二进制。
    required Condition condition = 3;
    optional ReturnContent return_content = 4;
    optional string transaction_id = 5;
}

名称	类型	是否必选	描述
table_name	string	是	写入数据的目标表名称。
row	bytes	是	待写入的行数据，包含主键列和属性列，使用 Plainbuffer 格式编码。详情请参见Plainbuffer。
condition	Condition	是	写入前是否对行进行存在性检查。取值如下： IGNORE（默认）：跳过存在性检查，直接写入。 EXPECT_EXIST：要求行存在，否则写入失败。 EXPECT_NOT_EXIST：要求行不存在，否则写入失败。
return_content	ReturnContent	否	写入成功后返回的数据类型。目前仅支持返回主键，主要配合主键列自增功能使用。
transaction_id	string	否	局部事务 ID。在局部事务中写入数据时，必须设置此参数。

响应消息结构

message PutRowResponse {
    required ConsumedCapacity consumed = 1;
    optional bytes row = 2;
}

名称

类型

描述

consumed

ConsumedCapacity

本次操作消耗的服务能力单元。详情请参见消耗的服务能力单元。

row

bytes

设置 return_content 后返回的数据。若未设置 return_content 或无返回数据，则此字段为 NULL。

返回的数据为Plainbuffer格式。关于Plainbuffer编码的更多信息，请参见Plainbuffer。

使用 SDK

以下SDK支持调用 PutRow 接口插入单行数据。

服务能力单元消耗

插入的行不存在时，根据 condition 取值不同，消耗的服务能力单元不同。
- IGNORE：消耗写 CU，计算方式为（主键数据大小 + 属性列数据大小）÷ 4 KB，向上取整。
- EXPECT_NOT_EXIST：同时消耗写 CU 和读 CU。写 CU 计算方式为（主键数据大小 + 属性列数据大小）÷ 4 KB，向上取整；读 CU 计算方式为主键数据大小 ÷ 4 KB，向上取整。
- EXPECT_EXIST：写入失败，消耗 1 单位写 CU 和 1 单位读 CU。
插入的行已存在时，根据 condition 取值不同，消耗的服务能力单元不同。
- IGNORE：消耗写 CU，计算方式为（主键数据大小 + 属性列数据大小）÷ 4 KB，向上取整。
- EXPECT_EXIST：同时消耗写 CU 和读 CU。写 CU 计算方式为（主键数据大小 + 属性列数据大小）÷ 4 KB，向上取整；读 CU 计算方式为主键数据大小 ÷ 4 KB，向上取整。
- EXPECT_NOT_EXIST：写入失败，消耗 1 单位写 CU 和 1 单位读 CU。
数据大小计算方式的详细信息，请参见产品定价。
使用条件更新（Conditional Update）时，操作成功按上述规则计算消耗量；操作失败则消耗 1 单位写 CU 和 1 单位读 CU。
如果请求超时，结果未定义，则服务能力单元有可能被消耗，也可能未被消耗。
返回内部错误（HTTP 状态码：5xx）时，本次操作不消耗服务能力单元；其他错误情况消耗 1 单位写服务能力单元。