快速入門：建置 Java 應用程式來管理 Azure Cosmos DB for Apache Cassandra 資料 (v3 驅動程式)

發行項
08/15/2024

適用於： Cassandra

在本快速入門中，您會建立 Azure Cosmos DB for Apache Cassandra 帳戶，並使用適用於 Java 的 v3.x Apache Cassandra 驅動程式，以及自 GitHub 複製的 Cassandra Java 應用程式來建立 Cassandra 資料庫和容器。 Azure Cosmos DB 是多模型的資料庫服務，可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立一個。或免費試用 Azure Cosmos DB (不需 Azure 訂用帳戶)。
Java 開發套件 (JDK) 8 \(英文\)。將 JAVA_HOME 環境變數指向 JDK 安裝所在的資料夾。
Maven 二進位檔封存。在 Ubuntu 上，執行 apt-get install maven 來安裝 Maven。
Git。在 Ubuntu 上，執行 sudo apt-get install git 來安裝 Git。

注意

此為使用開放原始碼，適用於 JAVA 的 Apache Cassandra 驅動程式第 3 版的簡單快速入門。在大多數情況下，您應該能夠將現有相依於 Apache Cassandra 的 JAVA 應用程式連線至 Azure Cosmos DB for Apache Cassandra，而不需要變更現有的程式碼。不過，仍建議您新增自訂 JAVA 延伸模組，其中包括了自訂重試和負載平衡原則，讓您能獲得更好的整體體驗。這是為了能夠分別處理 Azure Cosmos DB 中的速率限制和應用程式層級的容錯移轉。您可以在這裡找到該延伸模組實作上的完整範例。

建立資料庫帳戶

您必須先使用 Azure Cosmos DB 建立 Cassandra 帳戶，才可以建立文件資料庫。

從 Azure 入口網站功能表或 [首頁] 頁面，選取 [建立資源]。
在 [新增] 頁面上，搜尋並選取 [Azure Cosmos DB]。
在 [Azure Cosmos DB] 頁面上，選取 [建立]。
在 [API] 頁面上的 [Cassandra] 區段下面，選取 [建立]。

API 會決定要建立的帳戶類型。 Azure Cosmos DB 提供五個 API：NoSQL (適用於文件資料庫)、Gremlin (適用於圖形資料庫)、MongoDB (適用於文件資料庫)、Azure 資料表與 Cassandra。您必須為每個 API 建立個別帳戶。

選取 [Cassandra]，因為在此快速入門中，您會建立可搭配 API for Cassandra 使用的資料表。

深入了解適用於 Cassandra 的 API。

在 [建立 Azure Cosmos DB 帳戶] 頁面中，輸入新 Azure Cosmos DB 帳戶的基本設定。

設定	值	Description
訂用帳戶	您的訂用帳戶	選取您要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。
資源群組	新建然後，輸入與帳戶名稱相同的名稱	選取 [新建] 然後為您的帳戶輸入新的資源群組名稱。為求簡化，請使用與 Azure Cosmos DB 帳戶名稱相同的名稱。
客戶名稱	輸入唯一名稱	輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。您的帳戶 URI 將是 cassandra.cosmos.azure.com，並附加至您的唯一帳戶名稱。帳戶名稱只能使用小寫字母、數字和連字號 (-)，且長度必須介於 3 到 31 個字元之間。
Location	最接近使用者的區域	選取用來裝載 Azure Cosmos DB 帳戶的地理位置。使用最接近使用者的位置，讓他們能以最快速度存取資料。
容量模式	佈建輸送量或無伺服器	選取 [佈建的輸送量]，以佈建的輸送量模式建立帳戶。選取 [無伺服器]，以無伺服器模式建立帳戶。
申請 Azure Cosmos DB 免費階層折扣	適用或不適用	使用 Azure Cosmos DB 免費層，您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。深入了解免費層。
限制帳戶總輸送量	選取此選項會限制帳戶的輸送量	如果您想要將帳戶的總輸送量限制為特定值，這會很有用。

注意

每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶，而且必須在建立帳戶時選擇加入。如果您看不到套用免費層折扣的選項，這表示訂用帳戶中的另一個帳戶已透過免費層啟用。

適用於 Apache Cassandra 的 Azure Cosmos DB 新帳戶頁面

在 [全域散發] 索引標籤中，設定下列詳細資料。您可以保留預設值，以供本快速入門的目的之用：

設定	值	Description
異地備援	停用	藉由將您的區域與配對區域進行配對，在您的帳戶上啟用或停用全域散發。您可以在稍後將更多區域新增至您的帳戶。
多重區域寫入	停用	多重區域寫入功能可讓您利用在全球為資料庫及容器佈建的輸送量。
可用性區域	停用	可用性區域是 Azure 區域內的隔離位置。每個區域都是由一或多個資料中心所組成，配備了獨立的電力、冷卻系統及網路系統。

注意

如果您選取 [無伺服器] 作為容量模式，則無法使用下列選項：

套用免費層折扣
異地備援
多重區域寫入

(選擇性) 您可以在下列索引標籤中設定其他詳細資料：
- 網路 - 設定從虛擬網路存取。
- 備份原則 - 設定定期或連續備份原則。
- 加密 - 使用服務管理的金鑰或客戶自控金鑰。
- 標籤 - 標籤為成對的名稱和值，可讓您將相同的標籤套用至多個資源與資源群組，以便為資源分類及檢視合併的帳單。
選取 [檢閱 + 建立]。
檢閱帳戶設定，然後選取 [建立]。建立帳戶需要幾分鐘的時間。請等候入口網站頁面顯示 [您的部署已完成]。
選取 [前往資源] 前往 Azure Cosmos DB 帳戶頁面。

複製範例應用程式

現在讓我們切換為使用程式碼。我們將從 GitHub 複製 Cassandra 應用程式、設定連接字串，然後加以執行。您會看到，以程式設計方式來處理資料有多麼的容易。

開啟命令提示字元。建立名為 git-samples 的新資料夾。接著，關閉命令提示字元。
```
md "C:\git-samples"
```
開啟 git 終端機視窗 (例如 git bash)，並使用 cd 命令變更至要安裝範例應用程式的新資料夾。
```
cd "C:\git-samples"
```
執行下列命令來複製範例存放庫。此命令會在您的電腦上建立範例應用程式副本。
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started.git
```

檢閱程式碼

此步驟是選擇性的。如果您有興趣了解程式碼如何建立資料庫資源，您可以檢閱下列程式碼片段。或者也可以直接跳至更新您的連接字串。這些程式碼片段摘錄自 src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java 檔案。

Cassandra 主機、連接埠、使用者名稱、密碼與 TLS/SSL 選項皆已設定。連接字串資訊來自 Azure 入口網站的連接字串頁面。

cluster = Cluster.builder().addContactPoint(cassandraHost).withPort(cassandraPort).withCredentials(cassandraUsername, cassandraPassword).withSSL(sslOptions).build();

cluster 會連線至 Azure Cosmos DB for Apache Cassandra，並傳回要存取的工作階段。
```
return cluster.connect();
```

下列程式碼片段摘錄自 src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java 檔案。

建立新的 keyspace。

public void createKeyspace() {
    final String query = "CREATE KEYSPACE IF NOT EXISTS uprofile WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '3' } ";
    session.execute(query);
    LOGGER.info("Created keyspace 'uprofile'");
}

建立新表格。

public void createTable() {
      final String query = "CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)";
      session.execute(query);
      LOGGER.info("Created table 'user'");
}

使用備妥的陳述式物件插入使用者實體。

public PreparedStatement prepareInsertStatement() {
    final String insertStatement = "INSERT INTO  uprofile.user (user_id, user_name, user_bcity) VALUES (?,?,?)";
    return session.prepare(insertStatement);
}

public void insertUser(PreparedStatement statement, int id, String name, String city) {
    BoundStatement boundStatement = new BoundStatement(statement);
    session.execute(boundStatement.bind(id, name, city));
}

取得所有使用者資訊的查詢。

public void selectAllUsers() {
    final String query = "SELECT * FROM uprofile.user";
    List<Row> rows = session.execute(query).all();

    for (Row row : rows) {
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
}

取得單一使用者資訊的查詢。

public void selectUser(int id) {
    final String query = "SELECT * FROM uprofile.user where user_id = 3";
    Row row = session.execute(query).one();

    LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
}

更新您的連接字串

現在，返回 Azure 入口網站以取得連接字串資訊，並將它複製到應用程式中。連接字串詳細資料可讓您的應用程式與託管資料庫進行通訊。

在 Azure 入口網站中的 Azure Cosmos DB 帳戶中，選取 [連接字串]。
使用畫面右側的按鈕來複製 CONTACT POINT 值。
從 C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources 資料夾開啟 config.properties 檔案。
從入口網站將 [連絡點] 值貼到 <Cassandra endpoint host> 的行 2。

config.properties 的第 2 行現在看起來應該類似於

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
返回入口網站，並複製 [使用者名稱] 值。從入口網站將 [使用者名稱] 值貼到 <cassandra endpoint username> 的行 4。

config.properties 的第 4 行現在看起來應該類似於

cassandra_username=cosmos-db-quickstart
返回入口網站，並複製 [密碼] 值。從入口網站將 [密碼] 值貼到 <cassandra endpoint password> 的行 5。

config.properties 的第 5 行現在看起來應該類似於

cassandra_password=2Ggkr662ifxz2Mg...==
在第 6 行中，如果您想要使用特定的 TLS/SSL 憑證，請將 <SSL key store file location> 取代為 TLS/SSL 憑證的位置。如果未提供值，會使用安裝在 <JAVA_HOME>/jre/lib/security/cacerts 的 JDK 憑證。
如果您變更行 6 為使用特定的 TLS/SSL 憑證，請更新行 7 以使用該憑證的密碼。
儲存 config.properties 檔案。

執行 Java 應用程式

在 git 終端機視窗中，cd 至 azure-cosmosdb-cassandra-java-getting-started 資料夾。
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started"
```
在 git 終端機視窗中，使用下列命令產生 cosmosdb-cassandra-examples.jar 檔案。
```
mvn clean install
```
在 git 終端機視窗中，執行下列命令以啟動 JAVA 應用程式。
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
終端機視窗會顯示 keyspace 和資料表已建立的通知。它會接著選取並傳回資料表中的所有使用者並顯示輸出，然後依識別碼選取資料列並顯示值。

按 Ctrl+C 來停止執行程式，並關閉主控台視窗。
在 Azure 入口網站中，開啟 [資料總管] 以查詢、修改及使用這個新資料。