次の方法で共有


クイック スタート: Azure Cosmos DB for Apache Cassandra データを管理する Java アプリを作成する (v4 ドライバー)

適用対象: Cassandra

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

前提条件

Note

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

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

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

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

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

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

  4. [API] ページの [Cassandra] セクションで [作成] を選択します。

    API によって、作成するアカウントの種類が決まります。 Azure Cosmos DB には、NoSQL (ドキュメント データベース用)、Gremlin (グラフ データベース用)、MongoDB (ドキュメント データベース用)、Azure Table、Cassandra の 5 種類の API が用意されています。 API ごとに別のアカウントを作成する必要があります。

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

    Cassandra 用 API に関する詳細を確認してください

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

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

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

    アカウント名に使用できるのは、小文字、数字、ハイフン (-) のみで、長さは 3 文字から 31 文字の範囲にする必要があります。
    場所 ユーザーに最も近いリージョン 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 レベルの詳細を確認してください。
    合計アカウント スループットを制限する アカウントのスループットを制限する場合に選択します これは、アカウントの合計スループットを特定の値に制限する場合に便利です。

    Note

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

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

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

    設定 説明
    geo 冗長性 無効化 リージョンをペア リージョンとペアリングすることによる、アカウントでのグローバル配信を有効または無効にします。 アカウントには、後でさらにリージョンを追加できます。
    マルチリージョン書き込み 無効化 マルチリージョン書き込み機能を使用すると、世界中のデータベースとコンテナーで、プロビジョニングされたスループットを利用できます。
    可用性ゾーン 無効にする Availability Zones は、Azure リージョン内の分離された場所です。 それぞれのゾーンは、独立した電源、冷却手段、ネットワークを備えた 1 つまたは複数のデータセンターで構成されています。

    Note

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

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

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

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

    Azure portal の [通知] ペイン

  10. [リソースに移動] を選択し、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 for Apache Cassandra に接続し、アクセスするセッションを返します (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 つのみであるためです。 既定 (Azure 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 では、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 portal の検索バーで、「リソース グループ」を検索して選択します。

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

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

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

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

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

次のステップ

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