Tablestore：寫入資料

前提條件

• 已初始化Client。具體操作，請參見初始化。
• 已建立資料表並寫入資料。

插入單行資料

調用PutRow介面新寫入一行資料。如果該行已存在，則先刪除原行資料（原行的所有列以及所有版本的資料），再寫入新行資料。

介面

"""
說明：寫入一行資料。返回本次操作消耗的CapacityUnit。
``table_name``是資料表名稱。
``row``是行資料，包括主鍵和屬性列。
``condition``表示執行操作前做條件檢查，滿足條件才執行，是tablestore.metadata.Condition類的執行個體。支援對行的存在性和列條件進行檢查，其中行存在性檢查條件包括'IGNORE'、'EXPECT_EXIST'和'EXPECT_NOT_EXIST'。
``return_type``表示傳回型別，是tablestore.metadata.ReturnType類的執行個體。目前僅支援返回PrimaryKey，一般用於主鍵列自增中。

返回：本次操作消耗的CapacityUnit和需要返回的行資料。
``consumed``表示消耗的CapacityUnit，是tablestore.metadata.CapacityUnit類的執行個體。
``return_row``表示返回的行資料，可能包括主鍵、屬性列。
"""
def put_row(self, table_name, row, condition = None, return_type = None)                   

參數

樣本

插入一行資料。

## 主鍵的第一個主鍵列是gid，值是整數1，第二個主鍵列是uid，值是整數101。
primary_key = [('gid',1), ('uid',101)]

## 屬性列包括五個：
##              第一個屬性列的名字是name，值是字串John，版本號碼沒有指定，使用系統目前時間作為版本號碼。
##              第二個屬性列的名字是mobile，值是整數13900006666，版本號碼沒有指定，使用系統目前時間作為版本號碼。
##              第三個屬性列的名字是address，值是二進位的China，版本號碼沒有指定，使用系統目前時間作為版本號碼。
##              第四個屬性列的名字是female，值是布爾值False，版本號碼沒有指定，使用系統目前時間作為版本號碼。
##              第五個屬性列的名字是age，值是29.7，指定版本號碼為1498184687000。
attribute_columns = [('name','John'), ('mobile',13900006666),('address', bytearray('China')),('female', False), ('age', 29.7, 1498184687000)]

## 通過primary_key和attribute_columns構造Row。
row = Row(primary_key, attribute_columns)

# 設定條件更新，行條件檢查為期望行不存在。如果行存在會出現Condition Update Failed錯誤。
condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)

try :
    # 調用put_row方法，如果沒有指定ReturnType，則return_row為None。
    consumed, return_row = client.put_row(table_name, row, condition)

    # 列印此次請求消耗的寫CU。
    print ('put row succeed, consume %s write cu.' % consumed.write)
# 用戶端異常，一般為參數錯誤或者網路異常。
except OTSClientError as e:
    print "put row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
# 服務端異常，一般為參數錯誤或者流控錯誤。
except OTSServiceError as e:
    print "put row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id())                    

詳細代碼請參見PutRow@GitHub。

更新單行資料

介面

"""
說明：更新一行資料。
``table_name``是資料表名稱。
``row``表示更新的行資料，包括主鍵列和屬性列，主鍵列和屬性列的類型均是list。
``condition``表示執行操作前做條件檢查，滿足條件才執行，是tablestore.metadata.Condition類的執行個體。支援對行的存在性和列條件進行檢查，其中行存在性檢查條件包括'IGNORE'、'EXPECT_EXIST'和'EXPECT_NOT_EXIST'。
``return_type``表示傳回型別，是tablestore.metadata.ReturnType類的執行個體。目前僅支援返回PrimaryKey，一般用於主鍵列自增中。
返回：本次操作消耗的CapacityUnit和需要返回的行資料return_row。
consumed表示消耗的CapacityUnit，是tablestore.metadata.CapacityUnit類的執行個體。
return_row表示需要返回的行資料。
"""
def update_row(self, table_name, row, condition, return_type = None)                    

參數

樣本

更新一行資料。

# 主鍵的第一列是uid，值是整數1，第二列是gid，值是整數101。
primary_key = [('uid',1), ('gid',101)]

# 更新包括PUT，DELETE和DELETE_ALL三部分。
# PUT：新增或者更新列值。樣本中是新增兩列，第一列名字是name，值是David，第二列名字是address，值是Hongkong。
# DELETE: 刪除指定版本號碼（時間戳記）的值。樣本中是刪除版本為1488436949003的address列的值。
# DELETE_ALL：刪除列。樣本中是刪除mobile和age兩列的所有版本的值。
update_of_attribute_columns = {
    'PUT' : [('name','David'), ('address','Hongkong')],
    'DELETE' : [('address', None, 1488436949003)],
    'DELETE_ALL' : [('mobile'), ('age')],
}
row = Row(primary_key, update_of_attribute_columns)

# 行條件檢查為忽略，無論行是否存在，均會更新。
condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", 20, ComparatorType.EQUAL)) # update row only when this row is exist

try:
    consumed, return_row = client.update_row(table_name, row, condition)
# 用戶端異常，一般為參數錯誤或者網路異常。
except OTSClientError as e:
    print "update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
# 服務端異常，一般為參數錯誤或者流控錯誤。
except OTSServiceError as e:
    print "update row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id())

詳細代碼請參見UpdateRow@GitHub。

批量寫入資料

調用BatchWriteRow介面在一次請求中進行批量的寫入操作，也支援一次對多張表進行寫入。BatchWriteRow操作由多個PutRow、UpdateRow、DeleteRow子操作組成，構造子操作的過程與使用PutRow介面、UpdateRow介面和DeleteRow介面時相同，也支援使用條件更新。

BatchWriteRow的各個子操作獨立執行，Tablestore會分別返回各個子操作的執行結果。

注意事項

由於批量寫入可能存在部分行失敗的情況，失敗行的Index及錯誤資訊在返回的BatchWriteRowResponse中，但並不拋出異常。因此調用BatchWriteRow介面時，需要檢查傳回值，判斷每行的狀態是否成功；如果不檢查傳回值，則可能會忽略掉部分操作的失敗。

當服務端檢查到某些操作出現參數錯誤時，BatchWriteRow介面可能會拋出參數錯誤的異常，此時該請求中所有的操作都未執行。

介面

"""
說明：批量修改多行資料。
request = MiltiTableInBatchWriteRowItem()
request.add(TableInBatchWriteRowItem(table0, row_items))
request.add(TableInBatchWriteRowItem(table1, row_items))
response = client.batch_write_row(request)
``response``為返回的結果，類型為tablestore.metadata.BatchWriteRowResponse。
"""
def batch_write_row(self, request):                   

樣本

批量寫資料。

put_row_items = []
# 增加PutRow的行。
for i in range(0, 10):
    primary_key = [('gid',i), ('uid',i+1)]
    attribute_columns = [('name','somebody'+str(i)), ('address','somewhere'+str(i)), ('age',i)]
    row = Row(primary_key, attribute_columns)
    condition = Condition(RowExistenceExpectation.IGNORE)
    item = PutRowItem(row, condition)
    put_row_items.append(item)

# 增加UpdateRow的行。
for i in range(10, 20):
    primary_key = [('gid',i), ('uid',i+1)]
    attribute_columns = {'put': [('name','somebody'+str(i)), ('address','somewhere'+str(i)), ('age',i)]}
    row = Row(primary_key, attribute_columns)
    condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", i, ComparatorType.EQUAL))
    item = UpdateRowItem(row, condition)
    put_row_items.append(item)

# 增加DeleteRow的行。
delete_row_items = []
for i in range(10, 20):
    primary_key = [('gid',i), ('uid',i+1)]
    row = Row(primary_key)
    condition = Condition(RowExistenceExpectation.IGNORE)
    item = DeleteRowItem(row, condition)
    delete_row_items.append(item)

# 構造批量寫請求。
request = BatchWriteRowRequest()
request.add(TableInBatchWriteRowItem(table_name, put_row_items))
request.add(TableInBatchWriteRowItem('notExistTable', delete_row_items))

# 調用batch_write_row方法執行批量寫，如果請求參數等錯誤會拋異常；如果部分行失敗，則不會拋異常，但是內部的Item會失敗。
try:
    result = client.batch_write_row(request)
    print ('Result status: %s'%(result.is_all_succeed()))

    # 檢查Put行的結果。
    print ('check first table\'s put results:')
    succ, fail = result.get_put()
    for item in succ:
        print ('Put succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print ('Put failed, error code: %s, error message: %s' % (item.error_code, item.error_message))

    # 檢查Update行的結果。
    print ('check first table\'s update results:')
    succ, fail = result.get_update()
    for item in succ:
        print ('Update succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print ('Update failed, error code: %s, error message: %s' % (item.error_code, item.error_message))

    # 檢查Delete行的結果。
    print ('check second table\'s delete results:')
    succ, fail = result.get_delete()
    for item in succ:
        print ('Delete succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print ('Delete failed, error code: %s, error message: %s' % (item.error_code, item.error_message)) 
# 用戶端異常，一般為參數錯誤或者網路異常。
except OTSClientError as e:
    print "get row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
# 服務端異常，一般為參數錯誤或者流控錯誤。
except OTSServiceError as e:
    print "get row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id())                    

詳細代碼請參見BatchWriteRow@GitHub。