Tablestore：局部事務

簡單情境：讀-寫情境

當需要進行讀取-修改-寫回（Read-Modify-Write）操作時，您可以選擇如下兩種方式，但這兩種方式有一些限制。

• 條件更新：只能處理單行單次請求，不能處理資料分布在多行或者需要多次寫入的情況。更多資訊，請參見條件更新。

• 原子計數器：只能處理單行單次請求，且只能進行列值的累加操作。更多資訊，請參見原子計數器。

為瞭解決上述問題，您可以使用局部事務功能實現一個分區索引值範圍內的通用讀取-修改-寫迴流程。

1. 使用StartLocalTransaction介面為分區索引值建立一個局部事務，並擷取局部事務ID。

2. 使用GetRow或GetRange介面擷取資料，且在請求中需要帶上局部事務ID。

3. 在用戶端本地修改資料。

4. 使用PutRow、UpdateRow、DeleteRow或BatchWriteRow介面將修改後的資料寫回，且在請求中需要帶上事務ID。

5. 使用CommitTransaction提交局部事務。

複雜情境：郵箱情境

使用局部事務功能，您可以實現對同一個使用者郵件的原子操作。

為了能正常使用局部事務功能，在一張資料表上建立兩張索引表，其主鍵列請參見下表。下表中使用Type列區分資料表和不同的索引表，不同的索引行使用IndexField列儲存不同含義的欄位，而資料表無IndexField列。

在郵箱情境中，使用局部事務功能可以完成如下使用情境。

使用局部事務寫入一行資料

以下樣本用於為表的指定分區鍵建立一個局部事務後，在局部事務內寫入一行資料。

private static void transactionPutRow(SyncClient client) {
    //設定資料表名稱。
    String tableName="<TABLE_NAME>";
    //使用指定分區索引值建立一個局部事務。 
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設定第一個主鍵（即分區鍵）的列名、資料類型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //構造建立局部事務的請求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //發起建立局部事務的請求並擷取局部事務ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();
    
    //在局部事務內寫入一行資料。
    //構造行的主鍵資訊。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設定主鍵的列名、資料類型和列值。如果表的主鍵由多個主鍵列組成，則多個主鍵列需要按照順序依次進行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    //構造行的屬性列。
    RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey1);
    //設定屬性列的列名、資料類型和列值，請根據需要添加所需屬性列。
    rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
    rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));
    PutRowRequest request1 = new PutRowRequest(rowPutChange);
    //設定局部事務ID到請求中。
    request1.setTransactionId(txnId);
    client.putRow(request1);
    
    //提交或丟棄局部事務。 
    //提交局部事務，使局部事務中的所有資料修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丟棄局部事務，局部事務中的所有資料修改均不會應用到原有資料。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
}

使用局部事務讀取一行資料

以下樣本用於為表的指定分區鍵建立一個局部事務後，在局部事務內讀取一行資料。

private static void transactionGetRow(SyncClient client) {
    //設定資料表名稱。
    String tableName="exampletabled";
    //使用指定分區索引值建立一個局部事務。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設定第一個主鍵（即分區鍵）的列名、資料類型和列值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    //構造建立局部事務的請求。
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    //發起建立局部事務的請求並擷取局部事務ID。
    String txnId = client.startLocalTransaction(request).getTransactionID();

    //在局部事務內讀取一行資料。
    //構造行的主鍵資訊。
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    //設定主鍵的列名、資料類型和列值。如果表的主鍵由多個主鍵列組成，則多個主鍵列需要按照順序依次進行配置。
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey1);
    //設定讀取最新版本的資料。
    criteria.setMaxVersions(1);
    GetRowRequest request1 = new GetRowRequest(criteria);
    //設定局部事務ID到請求中。
    request1.setTransactionId(txnId);
    GetRowResponse getRowResponse = client.getRow(request1);
  
    //提交或丟棄局部事務。對於讀操作來說，提交局部事務或丟棄局部事務的操作是等同的。
    //提交局部事務，使局部事務中的所有資料修改生效。
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    //丟棄局部事務，局部事務中的所有資料修改均不會應用到原有資料。
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
    
    //擷取並列印行資料。
    Row row = getRowResponse.getRow();
    System.out.println("讀取完畢，結果為：");
    System.out.println(row);
}