全部產品
Search

搜尋本產品

    Tablestore：局部事務

    文件中心

    Tablestore：局部事務

    更新時間：Jul 19, 2024

    為資料表開啟局部事務後，使用局部事務功能，您可以建立資料範圍在一個分區索引值內的局部事務並對局部事務中的資料進行讀寫操作。通過使用局部事務您可以實現單行或多行讀寫的原子操作。

    使用局部事務可以指定某個分區索引值內的操作是原子的，對分區索引值內的資料進行的操作要麼全部成功要麼全部失敗，並且所提供的隔離等級為讀已提交。

    前提條件

    使用方法

    1. 使用startLocalTransaction在指定的分區索引值建立一個局部事務，並擷取局部事務ID。

    2. 對局部事務範圍內的資料進行讀寫操作。

      支援對局部事務進行操作的介面為GetRow、PutRow、DeleteRow、UpdateRow、BatchWriteRow和GetRange。

    3. 使用commitTransaction提交局部事務或者使用abortTransaction丟棄局部事務。

    注意事項

    • 主鍵自增列功能和局部事務功能不能同時使用。

    • 局部事務通過悲觀鎖（Pessimistic Lock）實現並發控制。

    • 每個局部事務從建立開始生命週期最長為60秒。

      如果超過60秒未提交局部事務或丟棄局部事務，則Table Store服務端會認為此局部事務逾時，並將局部事務丟棄。

    • 如果建立局部事務時逾時，則請求可能在Table Store服務端已執行成功，此時請等待該局部事務逾時後重新建立。

    • 未提交的局部事務可能會失效，如果出現此情況，則需要重試該局部事務內的操作。

    • 如果未對局部事務範圍內的資料進行寫操作，則提交局部事務或丟棄局部事務的操作是等同的。

    • 在局部事務中讀寫資料有如下限制：

      • 不能使用局部事務ID訪問局部事務範圍（即建立時使用的分區索引值）以外的資料。

      • 同一個局部事務中所有寫請求的分區索引值必須與建立局部事務時的分區索引值相同，讀請求則無此限制。

      • 一個局部事務同時只能用於一個請求中，在使用局部事務期間，其他使用此局部事務ID的操作均會失敗。

      • 每個局部事務中兩次讀寫操作的最大間隔為60秒。

        如果超過60秒未操作局部事務，則Table Store服務端會認為此局部事務逾時，並將局部事務丟棄。

      • 每個局部事務中寫入的資料量最大為4 MB，按正常的寫請求資料量計算規則累加。

      • 如果在局部事務中寫入了未指定版本號碼的Cell，則該Cell的版本號碼會在寫入資料時（而非提交局部事務時）由Table Store服務端自動產生，建置規則與正常寫入一個未指定版本號碼的Cell相同。

      • 如果BatchWriteRow請求中帶有局部事務ID，則此請求中所有行只能操作該局部事務ID對應的表。

      • 在使用局部事務期間，對應分區索引值的資料會被加上寫鎖，只有持有局部事務ID在局部事務範圍內的寫請求才會成功。其他非事務請求或持有其他局部事務ID在局部事務範圍內的寫請求均會失敗。在局部事務提交、丟棄或逾時後，對應的鎖也會被釋放。

      • 帶有局部事務ID的讀寫請求失敗不會影響局部事務本身的存活情況，您可以指定重試規則進行重試或者主動丟棄當前局部事務。

    介面

    局部事務相關的startLocalTransaction、commitTransaction和abortTransaction的介面資訊如下。

    startLocalTransaction

        /**
     * 建立局部事務，擷取局部事務ID。
     * @api
     * @param [] $request
     *            請求參數：資料表名稱、分區鍵。
     * @return [] 請求返回。
     * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
     * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
     * @example "src/examples/StartLocalTransaction.php" 50
     */
    public function startLocalTransaction(array $request)

    commitTransaction

        /**
     * 提交局部事務。
     * @api
     *
     * @param [] $request
     *            請求參數：局部事務ID。
     * @return [] 請求返回。
     * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
     * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
     * @example "src/examples/CommitTransaction.php" 50
     */
    public function commitTransaction(array $request)

    abortTransaction

        /**
     * 丟棄局部事務。
     * @api
     *
     * @param [] $request
     *          請求參數：局部事務ID。
     * @return [] 請求返回。
     * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時。
     * @throws OTSServerException 當OTS服務端返回錯誤時。
     * @example "src/examples/AbortTransaction.php" 20
     */
    public function abortTransaction(array $request)

    參數

    參數

    說明

    table_name

    資料表名稱。

    key

    資料表分區鍵。

    建立局部事務時，只需要指定局部事務對應的分區索引值。

    primary_key

    資料表主鍵。

    建立局部事務後，對局部事務範圍內的資料進行讀寫操作時，需要指定完整主鍵。

    transaction_id

    局部事務ID，用於唯一標識一個局部事務。

    建立局部事務後，操作局部事務時均需要帶上局部事務ID。

    樣本

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

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

    // 擷取局部事務ID。 
$response = $client->startLocalTransaction (array (
    'table_name' => 'TransactionTable',
// 主鍵為[PK0:INTEGER,PK1:STRING]。
    'key' => array(  
        array('PK0', 123)
    )
));

$attr = array();
$attr[] = ['col0', 'bbb'];

$request = [
    'table_name' => 'TransactionTable',
    'condition' => RowExistenceExpectationConst::CONST_IGNORE, //condition可以為IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST。
// 設定主鍵。
    'primary_key' => [ 
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'attribute_columns' => $attr,
    'transaction_id' => $response['transaction_id']  
];
// 執行putRow方法寫入資料。 
$client->putRow($request);
// 提交事務，使局部事務中的所有資料修改生效。您也可以通過丟棄事務來使資料寫入不生效。 
$client->commitTransaction(array(      
    'transaction_id' => $response['transaction_id']
));
// 丟棄事務，局部事務中的所有資料修改均不會應用到原有資料。 
// $client->abortTransaction(array( 
//     'transaction_id' => $response['transaction_id']
// ));

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

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

    // 擷取局部事務ID。
$response = $client->startLocalTransaction (array (
    'table_name' => 'TransactionTable',
// 主鍵為[PK0:INTEGER,PK1:STRING]。
    'key' => array(  
        array('PK0', 123)
    )
));

$request = array(
    'table_name' => 'TransactionTable',
// 設定主鍵。
    'primary_key' => array (
        array('PK0', 123),
        array('PK1', 'abc')
    ),
    'max_versions' => 1,
    'columns_to_get' => ['col0'],
    'transaction_id' => $response['transaction_id']
);
// 執行getRow方法讀取資料。 
$client->getRow($request);
// 提交或丟棄局部事務。對於讀操作來說，提交局部事務或丟棄局部事務的操作是等同的。
// 提交局部事務，使局部事務中的所有資料修改生效。
$client->commitTransaction(array(//提交事務 
    'transaction_id' => $response['transaction_id']
 ));
// 丟棄局部事務，局部事務中的所有資料修改均不會應用到原有資料。
// $client->abortTransaction(array(
//     'transaction_id' => $response['transaction_id']
// ));

    相關文檔

    如果要在局部事務內進行批量寫入、範圍讀取等操作，請在建立局部事務後，使用寫入資料或者讀取資料文檔中的相應操作樣本以及在請求中帶上局部事務ID實現。