教學課程：將資料移轉至 API for Cassandra 帳戶

發行項
08/15/2024

適用於： Cassandra

身為開發人員，您可能已有在內部部署環境或雲端中執行的 Cassandra 工作負載，而且想將這些工作負載遷移到 Azure。您可以將這類工作負載移轉至 Azure Cosmos DB 中的 API for Cassandra 帳戶。本教學課程會根據可用來將 Apache Cassandra 資料移轉至 Azure Cosmos DB 中 API for Cassandra 帳戶的不同選項提供指示。

本教學課程涵蓋下列工作：

規劃移轉
移轉的必要條件
使用 cqlsh COPY 命令遷移數據
使用 Spark 移轉資料

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

移轉的必要條件

預估輸送量需求：將資料移轉至 Azure Cosmos DB 中的 API for Cassandra 帳戶之前，您應該預估工作負載的輸送量需求。一般而言，請從 CRUD 作業所需的平均輸送量開始著手，然後再納入「擷取、轉換、載入」或棘手作業所需的額外輸送量。您需要有下列詳細資料，才能為移轉進行規劃：
- 現有資料大小或預估資料大小：定義最基本的資料庫大小和輸送量需求。如果您要為新應用程式預估資料大小，您可以假設資料平均分散至所有資料列，然後藉由乘以資料大小來預估值。
- 所需的輸送量：讀取 (查詢/取得) 和寫入 (更新/刪除/插入) 作業的大約輸送速率。必須要有此值，才能計算所需要求單位，以及穩定的狀態資料大小。
- 結構描述：透過 cqlsh 連線至您現有的 Cassandra 叢集，然後從 Cassandra 匯出結構描述：
```
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
```
  在識別現有工作負載的需求之後，根據所收集的輸送量需求，建立 Azure Cosmos DB 帳戶、資料庫及容器。
- 判斷作業的 RU 費用：您可以使用 API for Cassandra 所支援的任何 SDK 來判斷 RU。此範例會示範取得 RU 費用的 .NET 版本。
```
var tableInsertStatement = table.Insert(sampleEntity);
var insertResult = await tableInsertStatement.ExecuteAsync();

foreach (string key in insertResult.Info.IncomingPayload)
  {
     byte[] valueInBytes = customPayload[key];
     double value = Encoding.UTF8.GetString(valueInBytes);
     Console.WriteLine($"CustomPayload:  {key}: {value}");
  }
```
配置所需的輸送量：Azure Cosmos DB 可以依據您的需求成長，自動調整儲存體和輸送量。您可以使用 Azure Cosmos DB 要求單位計算機來評估您的輸送量需求。
在 API for Cassandra 帳戶中建立資料表：在您開始移轉資料之前，請從 Azure 入口網站或從 cqlsh 預先建立所有資料表。如果您要移轉至具有資料庫層級輸送量的 Azure Cosmos DB 帳戶，請務必在建立容器時提供分割區索引鍵。
增加輸送量︰資料移轉持續時間取決於您為 Azure Cosmos DB 中資料表佈建的輸送量多寡。請針對移轉持續時間增加輸送量。藉由較高的輸送量，您可以避免速率限制，並花費較少的時間進行移轉。完成移轉之後，再降低輸送量以節省成本。我們也建議您使用相同區域中的 Azure Cosmos DB 帳戶作為您的來源資料庫。
啟用 TLS：Azure Cosmos DB 具有嚴格的安全性需求和標準。與您的帳戶互動時，請務必啟用 TLS。當您透過 SSH 使用 CQL 時，會有選項要您提供 TLS 資訊。

移轉資料的選項

您可以使用命令或使用 Spark，將資料從現有的 Cassandra 工作負載移至 Azure Cosmos DB cqlsh COPY 。

使用 cqlsh COPY 命令移轉資料

使用 CQL COPY 命令來將本機資料複製至 Azure Cosmos DB 中的 API for Cassandra 帳戶。

警告

僅使用 CQL COPY 來移轉小型資料集。若要移動大型資料集，請使用 Spark 來移轉資料。

若要確定您的 csv 檔案中包含了正確的檔案結構，請使用 COPY TO 命令來直接從來源 Cassandra 資料表中將資料匯出至 csv 檔案 (請先確定 cqlsh 使用了適當的認證連接至來源資料表)：
```
COPY exampleks.tablename TO 'data.csv' WITH HEADER = TRUE;   
```
現在，取得您 API for Cassandra 帳戶的連接字串資訊：
- 登入 Azure 入口網站，然後瀏覽至您的 Azure Cosmos DB 帳戶。
- 開啟 [連接字串] 窗格。在這裡您會看到從 cqlsh 連線至 API for Cassandra 帳戶所需的所有資訊。
使用入口網站中的連線資訊來登入 cqlsh。
CQL COPY FROM使用命令來複製 data.csv （仍位於已安裝的使用者根目錄cqlsh）：
```
COPY exampleks.tablename FROM 'data.csv' WITH HEADER = TRUE;
```

注意

API for Cassandra 支援 Cassandra 3.11 隨附的通訊協定第 4 版。將較新的通訊協定版本與我們的 API 搭配使用，可能會發生問題。更新通訊協定版本的 COPY FROM 可能會進入迴圈，並傳回重複的資料列。請將通訊協定版本新增至 cqlsh 命令。

cqlsh <USERNAME>.cassandra.cosmos.azure.com 10350 -u <USERNAME> -p <PASSWORD> --ssl --protocol-version=4

將輸送量限制選項新增至 CQL Copy 命令

cqlsh 中的 COPY 命令支援多種參數，用以控制將文件擷取至 Azure Cosmos DB 中的速率。

COPY 命令的預設設定會嘗試以非常快速的速度擷取資料，且不會考量 CosmosDB 的速率限制行為。您應根據集合上設定的輸送量，降低 CHUNKSIZE 或 INGESTRATE。

如果文件或記錄大小為 1 KB，建議對 20,000 RU 的集合使用下列設定 (至少)。

CHUNKSIZE = 100
INGESTRATE = 500
MAXATTEMPTS = 10

範例命令

將資料從 API for Cassandra 複製至本機 csv 檔案

COPY standard1 (key, "C0", "C1", "C2", "C3", "C4") TO 'backup.csv' WITH PAGESIZE=100 AND MAXREQUESTS=1 ;

將資料從本機 csv 檔案複製至 API for Cassandra

COPY standard2 (key, "C0", "C1", "C2", "C3", "C4") FROM 'backup.csv' WITH CHUNKSIZE=100 AND INGESTRATE=100 AND MAXATTEMPTS=10;

重要

僅支援開放原始碼 Apache Cassandra 版本的 CQLSH COPY。 Datastax Enterprise (DSE) 版本的 CQLSH 可能會遭遇錯誤。

使用 Spark 移轉資料

搭配使用 Spark 與下列步驟，以將資料移轉至 API for Cassandra 帳戶：

佈建一個 Azure Databricks 叢集或 Azure HDInsight 叢集。
將資料移至目的地 API for Cassandra 端點。請參閱本操作指南以瞭解如何使用 Azure Databricks 來進行移轉。

如果您的資料位於 Azure 虛擬機器或任何其他雲端的現有叢集中，則建議使用 Spark 作業來遷移資料。若要這樣做，您必須將 Spark 設定為一次性或定期擷取的中繼項目。您可以使用內部部署環境與 Azure 之間的 Azure ExpressRoute 連線，來加速這項移轉。

即時移轉

如果需要從原生 Apache Cassandra 叢集進行零停機移轉，建議您設定雙重寫入，以及個別的大量資料載入來移轉歷程資料。藉由提供開放原始碼的雙重寫入 Proxy，我們讓實作此模式變得更加簡單，僅需最低限度地修改應用程式程式碼即可。請參閱使用雙重寫入 Proxy 和 Apache Spark 進行即時移轉操作指南文章，以寮解更多有關實作此模式的詳細資訊。

清除資源

若不再需要資源，您可以刪除資源群組、Azure Cosmos DB 帳戶和所有相關資源。請選取虛擬機器的資源群組，選取 [刪除]，然後確認要刪除的資源群組名稱，即可刪除資源。

下一步

在本教學課程中，您已了解如何將資料移轉至 Azure Cosmos DB 中的 API for Cassandra 帳戶。您現在可以瞭解 Azure Cosmos DB 中的其他概念：

Azure Cosmos DB 中的 Tunable 資料一致性層級

共用方式為