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

# 遷移至 KCL 3.5.x\+ 的單一資料表格式
<a name="kcl-single-table-format"></a>

從 KCL 3.5 開始，您可以使用單一資料表格式將所有 DynamoDB 中繼資料合併為單一租用資料表。 ****根據預設，KCL 3.x 會為每個應用程式建立三個 DynamoDB 資料表：租用資料表、工作者指標資料表和協調器狀態資料表。單一資料表格式會將這三個資料表減少為一個，這可協助您避免 DynamoDB 帳戶層級資料表限制。

## 單一資料表格式的運作方式
<a name="kcl-single-table-how-it-works"></a>

在單一資料表格式中，KCL 會將工作者指標和協調器狀態項目與租用項目一起存放在租用資料表中。每個項目都包含一個`entityType`屬性，可區分不同的記錄類型。

工作者指標和協調器狀態項目使用與租用資料表相同的主索引鍵結構，但包含不同的`entityType`值。此屬性可讓 KCL 在資料表掃描期間識別每個項目的目的。

KCL 的每個元件都會根據 `entityType` 屬性，篩選出其商業邏輯所需的項目。例如，租用指派管理員 (LAM) 會篩選租用和工作者指標項目，以執行租用指派。

## 設定單一資料表格式
<a name="kcl-single-table-config"></a>

如何啟用單一資料表格式取決於您目前的 KCL 版本：
+ **如果您使用 KCL 2.x：**請遵循更新的遷移指南升級至 KCL 3.5。預設會將單一資料表格式用於從 2.x 到 3.5 的新遷移。
+ **如果您使用的是 KCL 3.0–3.4：**您必須執行兩階段部署，才能遷移至單一資料表格式。請參閱下列組態和遷移步驟。

對於現有的 KCL 3.x 客戶，在 中設定`migrateAllEntitiesToLeaseTable`組態選項。 `CoordinatorConfig`此選項控制 KCL 是否將所有中繼資料實體類型存放在租用資料表中。


**的組態值 `migrateAllEntitiesToLeaseTable`**  

| Value | 預設 | Effect | 
| --- | --- | --- | 
| false | 是 | KCL 針對工作者指標和協調器狀態使用不同的資料表。應用程式碼支援單一資料表格式，但不會啟用它。 | 
| true | 否 | KCL 開始將工作者指標和協調器狀態資料寫入租用資料表。在`TableMigrationStatus`達到 `DEPLOYED`且您已針對沒有迴歸進行製作後，在階段 2 部署上設定此值。 | 

從 KCL 3.x 遷移到單一資料表格式需要兩階段部署：

1. **階段 1：**部署更新的 KCL 3.5 程式碼，並將 `migrateAllEntitiesToLeaseTable` 設為 `false`（預設值）。這會安裝支援單一資料表格式但不會啟用遷移的新程式碼。

1. **階段 2：**在所有工作者執行新程式碼且 `TableMigrationStatus`達到 `DEPLOYED`後，您已驗證沒有迴歸，請再次部署 ，並將 `migrateAllEntitiesToLeaseTable`設定為 `true`以開始遷移。

## 遷移狀態
<a name="kcl-single-table-states"></a>

會`TableMigrationStateMachine`管理從多資料表格式轉換為單一資料表格式。KCL 會在協調器狀態資料表中名為 的個別協調器狀態項目`TableMigration3.5`中追蹤目前的遷移狀態。如需狀態、轉換和說明的完整清單，請參閱 GitHub 網站上的 [KCL 單一資料表遷移狀態](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)。


**單一資料表格式遷移狀態**  

| State | 說明 | 轉換條件 | 
| --- | --- | --- | 
| INIT | 初始狀態。所有工作者都會在工作者指標統計資料中發出最低支援碼。工作者會繼續將工作者指標發送到舊版資料表，並從舊版資料表和租用資料表讀取工作者指標和協調器狀態。在功能上，INIT 和 DEPLOYED 之間沒有差異。 | 所有工作者都會在製作時間穩定發出最低支援碼。應用程式已準備好移至階段 2 部署。 | 
| DEPLOYED | 已使用新程式碼部署所有工作者 （階段 1 完成）。應用程式支援單一資料表格式，但尚未啟用。 | 階段 2 部署從 `migrateAllEntitiesToLeaseTable` 設定為 開始`true`。 | 
| PENDING | 所有工作者都會執行新的程式碼。KCL 會將資料從工作者指標和協調器狀態資料表遷移至租用資料表。 | 遷移完成後會經過 24 小時的預設製作時間。 | 
| COMPLETE | 遷移已完成。KCL 只會針對所有讀取和寫入使用租用資料表。不再使用舊的工作者指標和協調器狀態資料表。 | 終端機狀態。不會進一步轉換。 | 

如需每個狀態、轉換條件和完整狀態機器行為的詳細資訊，請參閱 GitHub 網站上的 [KCL 單一資料表遷移狀態機器](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)。

**注意**  
PENDING 和 COMPLETE 狀態之間的預設製作時間為 24 小時，但您最多可以設定一週。在此期間，KCL 會針對所有讀取和寫入使用租用資料表，但不會刪除舊資料表。確認遷移成功後，您必須手動刪除舊的工作者指標和協調器狀態資料表。KCL 不會自動刪除這些資料表。

## 遷移指標
<a name="kcl-single-table-metrics"></a>

使用 KCL，您可以使用 CloudWatch 指標監控單一資料表遷移的進度和運作狀態。使用這些指標來確認工作者已採用新的程式碼，並在遷移通過其狀態時追蹤遷移。您也可以在遷移期間偵測 DynamoDB 讀取、寫入或刪除錯誤。下表依發出指標的 KCL 操作 （指標維度） 和每個指標的發射時間來分組指標。

無論遷移是否進行中，選擇的領導者工作者都會持續發出下列指標：


**領導者隨時發出的指標**  

| 作業 | 指標 | 單位 | 說明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `StatusOrdinal` | 無 | 目前 DynamoDB 遷移狀態的順序： `0` = UNKNOWN， `1` = INIT， `2` = DEPLOYED， `3` = PENDING， `4` = COMPLETE。 | 
| `WorkerMetrics` | `FleetMinSupportCode` | 無 | 機群中所有租用工作者的最低支援碼。 | 

所選的領導者工作者只會在遷移進行時發出下列指標：


**領導者在遷移期間發出的指標**  

| 作業 | 指標 | 單位 | 說明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `Phase1Worker` | 計數 | 支援使用單一 DynamoDB 資料表操作，但尚未使用單一資料表遷移至 的工作者數量。 | 
| `TableMigration` | `Phase2Worker` | 計數 | 已遷移至寫入單一資料表的工作者數量。這些工作者可能仍會從多個資料表讀取，直到資料表遷移完成為止。 | 
| `TableMigration` | `PrePhase1Worker` | 計數 | 3.5 之前版本上不支援在單一 DynamoDB 資料表上操作的工作者數量。 | 
| `TableMigration` | `WriteFault` | 計數 | `1` 在 DynamoDB 寫入失敗時，在成功`0`時。 | 
| `TableMigration` | `DeleteFault` | 計數 | `1` DynamoDB 刪除失敗時，成功`0`時。 | 
| `TableMigration` | `CompletionFault` | 計數 | `1` 當`COMPLETE`狀態的交易寫入失敗時，`0`表示成功。 | 
| `TableMigrationAsyncMove` | `Success` | 計數 | `1` 在成功交易移動 CoordinatorState 項目`0`時，失敗時。 | 
| `TableMigrationAsyncMove` | `Time` | 毫秒 | 非同步移動操作的持續時間。 | 
| `TableMigrationAsyncMove` | `BatchCount` | 計數 | 已成功移動的批次數量。 | 

遷移進行時，所有工作者都會發出下列指標：


**所有工作者在遷移期間發出的指標**  

| 作業 | 指標 | 單位 | 說明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `ReadFault` | 計數 | `1` 無法`TableMigrationState`從 DynamoDB 讀取 時， 成功`0`時。 | 
| `TableMigration` | `Time` | 毫秒 | 狀態機器執行的持續時間。 | 
| `TableMigrationInitialize` | `Success` | 計數 | `1` 成功初始化時，失敗`0`時。 | 
| `TableMigrationInitialize` | `Time` | 毫秒 | 初始化操作的持續時間。 | 

使用這些指標來決定何時進行遷移。當 `StatusOrdinal` 一致 `2`(DEPLOYED) 且 `PrePhase1Worker`為 時`0`，所有工作者都支援單一資料表格式，而且您可以移至資料表遷移部署的第 2 階段。`StatusOrdinal` 達到 `4`(COMPLETE) 後，您可以安全地刪除舊版資料表。

## 回復考量事項
<a name="kcl-single-table-rollback"></a>

轉返支援取決於目前的 `TableMigrationStatus`：
+ **在階段 1** 期間 (`TableMigrationStatus` 為 `DEPLOYED`或尚未設定）：您可以安全地轉返至先前的版本。新的程式碼會以回溯相容的模式執行，而且並未將資料寫入至租用資料表中的非租用項目。
+ **在階段 2** 期間 (`TableMigrationStatus` 為 `DEPLOYED`或 `PENDING`)：您可以轉返至階段 1。工作者會還原為使用舊版資料表 （多資料表格式） 處理工作者指標和協調器狀態。遷移會復原。
+ **完成狀態後**：不支援轉返。KCL 只會對所有實體使用租用資料表。即使程式碼轉返到階段 1，工作者仍會繼續使用所有實體的租用資料表，並忽略組態。

**警告**  
遷移達到 COMPLETE 狀態後，應用程式只會以單一資料表模式運作。系統會忽略`migrateAllEntitiesToLeaseTable`組態，KCL 不會使用個別資料表還原為 。確定移至 COMPLETE 之前的製作時間足夠，因為之後即使程式碼轉返也不會切換回多個資料表。

## 最佳實務
<a name="kcl-single-table-best-practices"></a>

當您採用單一資料表格式時，請遵循下列最佳實務：
+ 在階段 1 部署之後，驗證協調器狀態項目`TableMigration3.5`是否達到 `DEPLOYED` 狀態。在繼續進行階段 2 之前，請確定沒有迴歸。
+ 在`TableMigration3.5`協調器狀態項目`TableMigrationStatus`中監控 ，以追蹤 DEPLOYED、PENDING 和 COMPLETE 狀態的進度。狀態會以個別項目形式 （不在租用資料表中） 存放在協調器狀態資料表中，直到遷移達到 COMPLETE。
+ 確定移至 COMPLETE 之前的製作時間足夠，因為之後即使程式碼轉返也不會切換回多個資料表。應用程式僅在單一資料表模式中運作。
+ 遷移到達 COMPLETE 後，手動刪除舊的工作者指標和協調器狀態資料表。KCL 不會自動刪除這些資料表，只會停止使用它們。
+ 如果您已設定 `CoordinatorConfig.coordinatorStateTableConfig`或 `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`，您可以在遷移完成後移除這些組態。這些組態已在 KCL 3.5 和更新版本中棄用。