調用PutRow介面插入資料 - Tablestore

調用PutRow介面插入資料到指定的行。

說明

如果指定行不存在，則新增一行；如果指定行存在，則覆蓋原有行。
返回結果中如果沒有出現報錯，則表示本次操作成功。

請求訊息結構

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插入單行資料。

服務能力單元消耗

當插入的行不存在時，根據指定的條件檢查不同，插入資料消耗的服務能力單元不同。
- 如果指定條件檢查為IGNORE時，則消耗寫服務能力單元的數值為本行的主鍵資料大小與要插入屬性列資料大小之和除以4 KB向上取整。
- 如果指定條件檢查為EXPECT_NOT_EXIST，則除了消耗本行的主鍵資料大小與要插入屬性列資料大小之和除以4 KB向上取整的寫CU，還需消耗該行主鍵資料大小除以4 KB向上取整的讀CU。
- 如果指定條件檢查為EXPECT_EXIST，則本次插入失敗並且消耗1單位寫CU和1單位讀CU。
當插入的行存在時，根據指定的條件檢查不同，插入資料消耗的服務能力單元不同。
- 如果指定條件檢查為IGNORE，則消耗寫服務能力單元的數值為本行的主鍵資料大小與要插入屬性列資料大小之和除以4 KB向上取整。
- 如果指定條件檢查為EXPECT_EXIST，則除了消耗本行的主鍵資料大小與要插入屬性列資料大小之和除以4 KB向上取整的寫CU，還需消耗該行主鍵資料大小除以4 KB向上取整的讀CU。
- 如果指定條件檢查為EXPECT_NOT_EXIST，則本次插入失敗並且消耗1單位寫CU和1單位讀CU。
關於資料大小計算的更多資訊，請參見產品定價。
使用條件更新（Conditional Update）時，如果操作成功，按照上述消耗服務能力單元方式進行計算。如果操作失敗，則消耗1單位寫CU和1單位讀CU。
如果請求逾時，結果未定義，則服務能力單元有可能被消耗，也可能未被消耗。
如果返回內部錯誤（HTTP狀態代碼：5xx），則此次操作不消耗服務能力單元，其他錯誤情況消耗1寫服務能力單元。