調用PutRow介面插入資料 - 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 單位寫服務能力單元。