Azure Cosmos DB Cassandra API データを管理する Java アプリを作成する (v4 ドライバー)

適用対象: Cassandra API

このクイックスタートでは、Azure Cosmos DB Cassandra API アカウントを作成し、GitHub からクローンした Cassandra Java アプリと Java 用 v4.x Apache Cassandra ドライバーを使用して Cassandra データベースとコンテナーを作成します。 Azure Cosmos DB は、マルチモデル データベース サービスです。グローバルな分散と水平方向のスケーリング機能により、ドキュメント データベースやテーブル データベース、キーと値のデータベース、グラフ データベースをすばやく作成し、クエリを実行することができます。

前提条件

注意

これは、Java 用のオープンソース Apache Cassandra ドライバーのバージョン 4 を使用する簡単なクイック スタートです。 ほとんどの場合、既存の Apache Cassandra 依存の Java アプリケーションは、既存のコードを変更しなくても Azure Cosmos DB Cassandra API に接続できるはずです。 ただし、全体的なエクスペリエンスを向上するために、カスタム Java 拡張機能を追加して、カスタムの再試行ポリシーと負荷分散ポリシー、推奨される接続設定などを含めることをお勧めします。 必要に応じて、Azure Cosmos DB でのレート制限とアプリケーション レベルのフェールオーバーを処理するためです。 この拡張機能を実装している包括的なサンプルについては、こちらを参照してください。

データベース アカウントの作成

ドキュメント データベースを作成するには、Azure Cosmos DB を含んだ Cassandra アカウントを事前に作成しておく必要があります。

  1. Azure portal のメニューまたは [ホーム] ページで、 [リソースの作成] を選択します。

  2. [新規] ページで、 [Azure Cosmos DB] を検索して選択します。

  3. [Azure Cosmos DB] ページで、 [作成] を選択します。

  4. [Azure Cosmos DB アカウントの作成] ページで、新しい Azure Cosmos アカウントの基本的な設定を入力します。

    設定 説明
    サブスクリプション 該当するサブスクリプション この Azure Cosmos DB アカウントに使用する Azure サブスクリプションを選択します。
    リソース グループ 新規作成

    アカウント名と同じ名前を入力します
    [新規作成] を選択します。 その後、自分のアカウントの新しいリソース グループの名前を入力します。 簡略化のため、Azure Cosmos アカウント名と同じ名前を使用します。
    アカウント名 一意の名前を入力します 自分の Azure Cosmos DB アカウントを識別するための一意の名前を入力します。 アカウント URI は、一意のアカウント名に cassandra.cosmos.azure.com が追加されたものになります。

    アカウント名に使用できるのは、小文字、数字、ハイフン (-) のみで、長さは 3 文字から 31 文字の範囲にする必要があります。
    API Cassandra API によって、作成するアカウントの種類が決まります。 Azure Cosmos DB には、5 種類の API が用意されています。ドキュメント データベース用の Core (SQL)、グラフ データベース用の Gremlin、ドキュメント データベース用の MongoDB、Azure Table、Cassandra です。 API ごとに別のアカウントを作成する必要があります。

    このクイック スタートでは Cassandra API で動作するテーブルを作成しているため、Cassandra を選択します。

    Cassandra API に関する詳細を参照する
    場所 ユーザーに最も近いリージョン Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。
    容量モード プロビジョニング スループットまたはサーバーレス プロビジョニング スループット モードでアカウントを作成するには、 [Provisioned throughput](プロビジョニング スループット) を選択します。 サーバーレス モードでアカウントを作成するには、 [サーバーレス] を選択します。
    Apply Azure Cosmos DB free tier discount (Azure Cosmos DB Free レベル割引を適用する) [適用] または [適用しない] Azure Cosmos DB Free レベルのアカウントでは、最初の 1000 RU/s と 25 GB のストレージを無料でご利用いただけます。 Free レベルの詳細を確認してください。

    注意

    Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。 Free レベルの割引を適用するオプションが表示されない場合は、サブスクリプション内の別のアカウントが Free レベルで既に有効になっていることを意味します。

    Azure Cosmos DB Cassandra API の新しいアカウント ページ

  5. [グローバル分散] タブで、次の詳細を構成します。 このクイックスタートでは、既定値のままでかまいません。

    設定 説明
    geo 冗長性 無効化 リージョンをペア リージョンとペアリングすることによる、アカウントでのグローバル配信を有効または無効にします。 アカウントには、後でさらにリージョンを追加できます。
    マルチリージョン書き込み 無効化 マルチリージョン書き込み機能を使用すると、世界中のデータベースとコンテナーで、プロビジョニングされたスループットを利用できます。

    注意

    [Capacity mode](容量モード) として [サーバーレス] を選択した場合、以下のオプションは利用できません。

    • Apply Free Tier Discount (Free レベルの割引の適用)
    • geo 冗長
    • マルチリージョン ライター
  6. 必要に応じて、次のタブで追加の詳細を構成できます。

    • [ネットワーク] - 仮想ネットワークからのアクセスを構成します。
    • [バックアップ ポリシー] - 定期的または 継続的のいずれかのバックアップ ポリシーを構成します。
    • [暗号化] - サービス マネージド キーまたは カスタマー マネージド キーのいずれかを使用します。
    • [タグ] - タグは名前と値のペアで、同じタグを複数のリソースやリソース グループに適用することでリソースを分類したり、統合した請求を表示したりできるようにします。
  7. [Review + create](レビュー + 作成) を選択します。

  8. アカウントの設定を確認し、 [作成] を選択します。 アカウントの作成には数分かかります。 ポータル ページに "デプロイが完了しました" と表示されるまで待ちます。

    Azure portal の [通知] ペイン

  9. [リソースに移動] を選択し、Azure Cosmos DB アカウント ページに移動します。

サンプル アプリケーションの複製

次は、コードを使った作業に移りましょう。 GitHub から Cassandra アプリの複製を作成し、接続文字列を設定して実行します。 プログラムでデータを処理することが非常に簡単であることがわかります。

  1. コマンド プロンプトを開きます。 git-samples という名前の新しいフォルダーを作成します。 その後、コマンド プロンプトを閉じます。

    md "C:\git-samples"
    
  2. git bash などの git ターミナル ウィンドウを開いて、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 Cassandra API に接続し、アクセスするセッションを返します (v3 ドライバーの Cluster オブジェクトは現在使用できません)。 Cassandra のホスト、ポート、ユーザー名、およびパスワードは、Azure portal の接続文字列ページを使って設定します。

        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 ファイルからのものです。

  • 以前の実行のキースペースが既に存在する場合は、削除します。

    public void dropKeyspace() {
        String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
        session.execute(query);
        LOGGER.info("dropped 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 Portal に戻り、接続文字列情報を取得し、アプリにコピーします。 アプリはこの接続文字列の詳細によって、ホストされているデータベースと通信できます。

  1. Azure portal の Azure Cosmos DB アカウントで、 [接続文字列] を選択します。

    Azure portal の [接続文字列] ページからユーザー名を表示してコピー

  2. 画面右側の ボタンを使用して [CONTACT POINT](コンタクト ポイント) の値をコピーします。

  3. C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources フォルダーから config.properties ファイルを開きます。

  4. 2 行目の <Cassandra endpoint host> にポータルのコンタクト ポイントの値を貼り付けます。

    config.properties の 2 行目は次のようになります。

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

  5. ポータルに戻り、[ユーザー名] の値をコピーします。 4 行目の <cassandra endpoint username> にポータルの [ユーザー名] の値を貼り付けます。

    config.properties の 4 行目は次のようになります。

    cassandra_username=cosmos-db-quickstart

  6. ポータルに戻り、[パスワード] の値をコピーします。 5 行目の <cassandra endpoint password> にポータルの [パスワード] の値を貼り付けます。

    config.properties の 5 行目は次のようになります。

    cassandra_password=2Ggkr662ifxz2Mg...==

  7. 特定の TLS/SSL 証明書を使用する場合は、6 行目の <SSL key store file location> を TLS/SSL 証明書の場所に置き換えます。 値が指定されない場合、<JAVA_HOME>/jre/lib/security/cacerts にインストールされている JDK 証明書が使用されます。

  8. 特定の TLS/SSL 証明書を使用するように 6 行目を変更した場合は、その証明書のパスワードを使用するように 7 行目を更新します。

  9. コンタクト ポイントとして、既定のリージョン (例: West US) を次のように追加する必要があります。

    region=West US

    これは、v.4x ドライバーでは、コンタクト ポイントと組み合わせることができるローカル DC は 1 つのみであるためです。 既定 (Cosmos DB アカウントを最初に作成したときに指定したリージョン) 以外のリージョンを追加する場合は、コンタクト ポイントを追加する際にリージョンのサフィックス (host-westus.cassandra.cosmos.azure.com など) を使用する必要があります。

  10. config.properties ファイルを保存します。

Java アプリを実行する

  1. Git ターミナル ウィンドウで、azure-cosmosdb-cassandra-java-getting-started-v4 フォルダーに cd します。

    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
    

    ターミナル ウィンドウに、キースペースとテーブルが作成されたという通知が表示されます。 その後、テーブル内のすべてのユーザーが選択されて戻されます。次に、出力が表示され、ID で行が選択されて値が表示されます。

    Ctrl + C キーを押してプログラムの実行を停止し、コンソール ウィンドウを閉じます。

  4. Azure portal で Data Explorer を開き、この新しいデータのクエリ、変更、操作を行います。

    データ エクスプローラーでデータを表示する - Azure Cosmos DB

Azure Portal での SLA の確認

Azure portal では、Cosmos DB アカウントのスループット、ストレージ、可用性、待ち時間、および一貫性が監視されます。 Azure Cosmos DB サービス レベル アグリーメント (SLA) に関連付けられたメトリックのグラフに、実際のパフォーマンスと比較された SLA の値が示されます。 この一連のメトリックによって、SLA の監視が透明化されます。

メトリックと SLA を確認するには:

  1. Cosmos DB アカウントのナビゲーション メニューで [メトリック] を選択します。

  2. [遅延時間] など、タブを選択し、右側で期間を選択します。 グラフ上の [実際][SLA] の線を比較します。

    Azure Cosmos DB の一連のメトリック

  3. 他のタブでメトリックを確認します。

リソースをクリーンアップする

アプリと Azure Cosmos DB アカウントの使用を完了したら、それ以上料金がかからないように、作成した Azure リソースを削除できます。 リソースを削除するには、次の手順に従います。

  1. Azure portal の検索バーで、「リソース グループ」を検索して選択します。

  2. 一覧から、このクイック スタートで作成したリソース グループを選択します。

    削除するリソース グループを選択する

  3. リソース グループの [概要] ページで、[リソース グループの削除] を選択します。

    リソース グループを削除します

  4. 次のウィンドウで、削除するリソース グループの名前を入力し、[削除] を選択します。

次のステップ

このクイックスタートでは、Cassandra API を使用して Azure Cosmos DB アカウントを作成する方法と、Cassandra データベースとコンテナーを作成する Cassandra Java アプリの実行方法について説明しました。 これで、Azure Cosmos DB アカウントに追加のデータをインポートできるようになりました。