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

# KCL 的單一資料表格式
<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`中追蹤目前的遷移狀態。如需狀態、轉換和描述的完整清單，請參閱 [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 僅針對所有讀取和寫入使用租用資料表。不再使用舊的工作者指標和協調器狀態資料表。 | 終端機狀態。不會進一步轉換。 | 

如需每個狀態、轉換條件和完整狀態機器行為的詳細資訊，請參閱 [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-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 和更新版本中棄用。