共用方式為


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

適用於: Cassandra

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

必要條件

注意

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

建立資料庫帳戶

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

  1. 從 Azure 入口網站功能表或 [首頁] 頁面,選取 [建立資源]

  2. 在 [新增] 頁面上,搜尋並選取 [Azure Cosmos DB]

  3. [Azure Cosmos DB] 頁面上,選取 [建立]

  4. 在 [API] 頁面上的 [Cassandra] 區段下面,選取 [建立]

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

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

    深入了解適用於 Cassandra 的 API

  5. 在 [建立 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 新帳戶頁面

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

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

    注意

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

    • 套用免費層折扣
    • 異地備援
    • 多重區域寫入
  7. (選擇性) 您可以在下列索引標籤中設定其他詳細資料:

    • 網路 - 設定從虛擬網路存取
    • 備份原則 - 設定定期連續備份原則。
    • 加密 - 使用服務管理的金鑰或客戶自控金鑰
    • 標籤 - 標籤為成對的名稱和值,可讓您將相同的標籤套用至多個資源與資源群組,以便為資源分類及檢視合併的帳單。
  8. 選取 [檢閱 + 建立]。

  9. 檢閱帳戶設定,然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 請等候入口網站頁面顯示 [您的部署已完成]

    Azure 入口網站的 [通知] 窗格

  10. 選取 [前往資源] 前往 Azure Cosmos DB 帳戶頁面。

複製範例應用程式

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

  1. 開啟命令提示字元。 建立名為 git-samples 的新資料夾。 接著,關閉命令提示字元。

    md "C:\git-samples"
    
  2. 開啟 git 終端機視窗 (例如 git bash),並使用 cd 命令變更至要安裝範例應用程式的新資料夾。

    cd "C:\git-samples"
    
  3. 執行下列命令來複製範例存放庫。 此命令會在您的電腦上建立範例應用程式副本。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
    

檢閱程式碼

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

  • CqlSession 會連線至 Azure Cosmos DB for Apache Cassandra,並傳回要存取的工作階段 (v3 驅動程式中的 Cluster 物件現在已淘汰)。 在 Azure 入口網站中使用連接字串頁面來設定 Cassandra 主機、連接埠、使用者名稱和密碼。

        this.session = CqlSession.builder().withSslContext(sc)
                .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
                .withAuthCredentials(cassandraUsername, cassandraPassword).build();
    

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

  • 如果 keyspace 已經存在於先前的執行中,請將其卸除。

    public void dropKeyspace() {
        String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
        session.execute(query);
        LOGGER.info("dropped keyspace '"+keyspace+"'");
    } 
    
  • 建立新的 keyspace。

    public void createKeyspace() {
        String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
        session.execute(query);
        LOGGER.info("Created keyspace '"+keyspace+"'");
    }
    
  • 建立新的資料表。

      public void createTable() {
          String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
          session.execute(query);
          LOGGER.info("Created table '"+table+"'");
      }
    
  • 會使用備妥的陳述式物件來插入使用者實體。

    public String prepareInsertStatement() {
        final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
        return insertStatement;
    }
    
    public void insertUser(String preparedStatement, int id, String name, String city) {
        PreparedStatement prepared = session.prepare(preparedStatement);
        BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
        session.execute(bound);
    }
    
  • 取得所有使用者資訊的查詢。

    public void selectAllUsers() {
        final String query = "SELECT * FROM "+keyspace+"."+table+"";
        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 "+keyspace+"."+table+" 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 入口網站以取得連接字串資訊,並將它複製到應用程式中。 連接字串詳細資料可讓您的應用程式與託管資料庫進行通訊。

  1. Azure 入口網站中的 Azure Cosmos DB 帳戶中,選取 [連接字串]

    從 [Azure 入口網站 連接字串] 頁面檢視並複製使用者名稱

  2. 使用畫面右側的 按鈕來複製 CONTACT POINT 值。

  3. 從 C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources 資料夾開啟 config.properties 檔案。

  4. 從入口網站將 [連絡點] 值貼到 <Cassandra endpoint host> 的行 2。

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

    cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com

  5. 返回入口網站,並複製 [使用者名稱] 值。 從入口網站將 [使用者名稱] 值貼到 <cassandra endpoint username> 的行 4。

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

    cassandra_username=cosmos-db-quickstart

  6. 返回入口網站,並複製 [密碼] 值。 從入口網站將 [密碼] 值貼到 <cassandra endpoint password> 的行 5。

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

    cassandra_password=2Ggkr662ifxz2Mg...==

  7. 在第 6 行中,如果您想要使用特定的 TLS/SSL 憑證,請將 <SSL key store file location> 取代為 TLS/SSL 憑證的位置。 如果未提供值,會使用安裝在 <JAVA_HOME>/jre/lib/security/cacerts 的 JDK 憑證。

  8. 如果您變更行 6 為使用特定的 TLS/SSL 憑證,請更新行 7 以使用該憑證的密碼。

  9. 請注意,您必須為連絡人點新增預設區域 (例如 West US),例如

    region=West US

    這是因為 v.4x 驅動程式只允許一個本機 DC 與該連絡人點配對。 如果您想要新增預設以外的區域 (這是第一次建立 Azure Cosmos DB 帳戶時所指定的區域),則在新增連絡人點 (例如 host-westus.cassandra.cosmos.azure.com) 時,您必須使用區域尾碼。

  10. 儲存 config.properties 檔案。

執行 Java 應用程式

  1. 在 git 終端機視窗中,cdazure-cosmosdb-cassandra-java-getting-started-v4 資料夾。

    cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
    
  2. 在 git 終端機視窗中,使用下列命令產生 cosmosdb-cassandra-examples.jar 檔案。

    mvn clean install
    
  3. 在 git 終端機視窗中,執行下列命令以啟動 JAVA 應用程式。

    java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
    

    終端機視窗會顯示 keyspace 和資料表已建立的通知。 它會接著選取並傳回資料表中的所有使用者並顯示輸出,然後依識別碼選取資料列並顯示值。

    按 Ctrl+C 來停止執行程式,並關閉主控台視窗。

  4. 在 Azure 入口網站中,開啟 [資料總管] 以查詢、修改及使用這個新資料。

    在數據總管中檢視數據 - Azure Cosmos DB

在 Azure 入口網站中檢閱 SLA

Azure 入口網站會監視 Azure Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。 與 Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。 此計量套件可讓您以更透明的方式監視監視 SLA。

若要檢閱計量和 SLA:

  1. 在 Azure Cosmos DB 帳戶導覽功能表中,選取 [計量]

  2. 選取一個索引標籤 (例如 [延遲]),並在右側選取時間範圍。 比較圖表中的實際SLA 的資料行。

    Azure Cosmos DB 計量套件

  3. 檢閱其他索引標籤中的計量。

清除資源

完成您的應用程式和 Azure Cosmos DB 帳戶之後,您可以將建立的 Azure 資源刪除,以免產生更多費用。 若要刪除資源:

  1. 在 Azure 入口網站的 [搜尋] 列中,搜尋並選取 [資源群組]

  2. 在該清單中,選取您在本快速入門中建立的資源群組。

    選取要刪除的資源群組

  3. 在 [資源群組] 的 [概觀] 頁面中,選取 [刪除資源群組]

    刪除資源群組

  4. 在下個視窗中輸入要刪除的資源群組名稱,然後選取 [刪除]

下一步

在此快速入門中,您已了解如何使用 API for Cassandra 建立 Azure Cosmos DB 帳戶,並執行 Cassandra Java 應用程式來建立 Cassandra 資料庫和容器。 您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。