調用GetRow介面讀取單行資料 - Tablestore

調用GetRow介面根據指定的主鍵讀取單行資料。

請求訊息結構

message GetRowRequest {
    required string table_name = 1;
    required bytes primary_key = 2;   // Plainbuffer編碼為二進位。
    repeated string columns_to_get = 3; // 不指定則讀出所有的列。
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional bytes filter = 7;
    optional string start_column = 8;
    optional string end_column = 9;
    optional bytes token = 10;
    optional string transaction_id = 11;
}

名稱	類型	是否必選	描述
table_name	string	是	要讀取的資料所在的表名。
primary_key	bytes	是	指定行全部的主鍵列，包含主鍵名和主索引值，由Plainbuffer編碼。更多資訊，請參見Plainbuffer。
columns_to_get	string	否	需要返回的全部列的列名。如果為空白，則返回指定行的所有列。columns_to_get中string的個數不應超過128個。如果指定的列不存在，則不會返回指定列的資料；如果給出了重複的列名，返回結果只會包含一次指定列。
time_range	TimeRange	否，和max_versions必須至少存在一個	讀取資料的版本時間戳記範圍。時間戳記的單位為毫秒，取值最小值為0，最大值為INT64.MAX。如果要查詢一個範圍，則指定start_time和end_time；如果要查詢一個特定時間戳記，則指定specific_time。如果指定的time_range為[100, 200），則返回的列資料的時間戳記必須位於[100, 200）範圍內，前閉後開區間。
max_versions	int32	否，和time_range至少存在一個	讀取資料時，返回的最多版本個數。如果指定max_versions為2，則每一列最多返回2個版本的資料。
filter	bytes	否	過濾條件運算式。Filter經過protobuf序列化後的位元據。
start_column	string	否	指定讀取時的起始列，主要用於寬行讀。列的順序按照列名的字典序排序。返回的結果中包含當前起始列。如果一張表有a、b、c三列，讀取時指定start_column為b，則會從b列開始讀，返回b、c兩列。
end_column	string	否	返回的結果中不包含當前結束列。列的順序按照列名的字典序排序。如果一張表有a、b、c三列，讀取時指定end_column為b，則讀到b列時會結束，返回a列。
token	bytes	否	寬行讀取時指定下一次讀取的起始位置，暫不可用。
transaction_id	string	否	局部事務ID。當使用局部事務功能讀取資料時必須設定此參數。

響應訊息結構

message GetRowResponse {
    required ConsumedCapacity consumed = 1;
    required bytes row = 2; // Plainbuffer編碼為二進位
    optional bytes next_token = 3;
}

名稱	類型	描述
consumed	ConsumedCapacity	本次操作消耗的服務能力單元。更多資訊，請參見服務能力單元消耗。
row	bytes	讀取到的資料。如果該行不存在，則資料為空白。返回的資料為Plainbuffer格式。關於Plainbuffer編碼的更多資訊，請參見Plainbuffer。
next_token	bytes	讀請求一行資料中列數超過128列，會返回next_token。

使用SDK

您可以使用如下語言的SDK讀取單行資料。

服務能力單元消耗

如果請求的行不存在，則消耗1讀CU（讀服務能力單元）。
如果請求的行存在，則消耗讀服務能力單元的數值為指定行所有主鍵列資料大小與實際讀取的屬性列資料大小之和除以4 KB向上取整。關於資料大小計算的更多資訊，請參見產品定價。
如果請求逾時，結果未定義，則服務能力單元有可能被消耗，也可能未被消耗。
如果返回內部錯誤（HTTP狀態代碼：5XX），則此次操作不消耗服務能力單元，其他錯誤情況消耗1讀服務能力單元。