本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon DocumentDB 中的可重試寫入
<a name="retryable-writes"></a>

從引擎 8.0.2 版開始，Amazon DocumentDB 支援可重試的寫入。當寫入操作因暫時性網路錯誤或主要選擇而失敗時，驅動程式可以僅自動重試一次操作。Amazon DocumentDB 會刪除重複的重試寫入，以便最多套用一次操作，保留冪等性。

可重試寫入需要支援可重試寫入通訊協定的 MongoDB 相容驅動程式。根據預設，最新的 MongoDB 相容驅動程式會啟用可重試寫入 (`retryWrites=true`在連線字串中）。如果您要從舊版升級至引擎 8.0.2，您可以從`retryWrites=false`連線字串中移除 ，以啟用此功能。

## 要求
<a name="retryable-writes-requirements"></a>

若要使用可重試寫入，您必須符合下列要求：
+ Amazon DocumentDB 引擎 8.0.2 版或更新版本。
+ 支援可重試寫入的 MongoDB 相容驅動程式。如需最低版本，請參閱驅動程式的文件。
+ 連線字串必須包含 `retryWrites=true`，或驅動程式必須預設為可重試寫入 （最新的驅動程式會這麼做）。

## 受支援的操作
<a name="retryable-writes-supported-operations"></a>

可重試寫入適用於寫入操作，其中每個個別寫入最多會影響一個文件。批次操作符合資格，因為批次中的每個寫入都會分別刪除重複項目。

下列寫入操作是可重試的：
+ `insertOne`
+ `insertMany`
+ `updateOne`
+ `deleteOne`
+ `findOneAndUpdate`
+ `findOneAndDelete`
+ `findOneAndReplace`
+ `bulkWrite` （由 `insertOne`、`deleteOne`、 `updateOne`或 `replaceOne`操作組成時）

對於 `insertMany`和 `bulkWrite`，批次中的每個文件都會個別刪除重複項目。如果需要重試，只會插入尚未套用的文件。

**注意**  
`commitTransaction` 和 `abortTransaction` 也可以重試，作為交易控制命令，而不是作為寫入。交易內的個別寫入無法重試。如需詳細資訊，請參閱[限制](#retryable-writes-limitations)。

## 限制
<a name="retryable-writes-limitations"></a>

下列限制適用於 Amazon DocumentDB 中的可重試寫入：
+ `updateMany` 和 `deleteMany` 無法重試。
+ 多陳述式交易內的寫入無法重試。交易遞交和中止操作可個別重試。
+ 文件必須包含可重試插入`_id`的欄位。
+ 可重試寫入僅適用於引擎 8.0.2 版和更新版本。在較早的引擎版本上，在您的連線字串`retryWrites=false`中設定 以避免錯誤。
+ 使用查詢規劃器 1.0 版的叢集無法重試寫入操作。
+ 對於傳回大型文件的 `findOneAndDelete`、 `findOneAndUpdate`和 `findOneAndReplace`操作，可重試寫入可能會增加寫入延遲，因為完整結果文件會快取進行重複資料刪除。如果寫入效能至關重要，且傳回的文件很大，請考慮`retryWrites=false`為這些工作負載設定 。

## 啟用可重試寫入
<a name="retryable-writes-enabling"></a>

若要啟用可重試寫入，請在連線字串`retryWrites=true`中包含 ：

```
mongodb://{{<username>}}:{{<password>}}@{{<cluster-endpoint>}}:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=true
```

如果您的驅動程式預設為 `retryWrites=true`，您可以從`retryWrites=false`連線字串中移除任何明確的 。

如需完整的連線字串逐步解說，請參閱 [以程式設計方式連線至 Amazon DocumentDB](connect_programmatically.md)。

## 可重試寫入的運作方式
<a name="retryable-writes-how-it-works"></a>

當您的應用程式使用 傳送寫入時`retryWrites=true`，驅動程式會將邏輯工作階段 ID (`lsid`) 和交易編號 (`txnNumber`) 附加至寫入命令。Amazon DocumentDB 使用這些識別符來刪除重複寫入：
+ 在第一次嘗試時，Amazon DocumentDB 會執行寫入並快取結果。
+ 如果驅動程式重試相同的寫入 （相同 `lsid`和 `txnNumber`)，Amazon DocumentDB 會傳回快取的結果，而不會重新執行寫入。
+ Amazon DocumentDB 會在原始寫入後 60 分鐘內接受重試。驅動程式會立即重試，因此此時段遠超過驅動程式的需求。

如果重試在原始寫入超過 60 分鐘後抵達，Amazon DocumentDB 就不再有快取結果，並以新的操作執行寫入。

## 錯誤處理
<a name="retryable-writes-errors"></a>

以下是 Amazon DocumentDB 中可重試寫入的特定錯誤：


| 錯誤碼 | 名稱 | 描述 | 
| --- | --- | --- | 
| 225 | TransactionTooOld | 相同工作階段和陳述式的較新交易號碼已遞交，因此此重試太舊而無法套用。 | 
| 301 | 不支援可重試寫入 | 寫入包含可重試的寫入欄位，但引擎版本不支援可重試的寫入，或操作無法重試。連線至早於 8.0.2 的引擎版本retryWrites=false時設定 。 | 

## 從 retryWrites=false 遷移
<a name="retryable-writes-migration"></a>

如果您要升級至引擎 8.0.2 版，且目前在連線字串`retryWrites=false`中使用 ：

1. 將您的叢集升級至引擎 8.0.2 版或更新版本。

1. `retryWrites=false` 從應用程式的連線字串中移除 ，或將其變更為 `retryWrites=true`。

1. 不需要變更應用程式程式碼。驅動程式會自動處理重試。