クイック スタート: Java 用 Azure Cosmos DB for Apache Cassandra クライアント ライブラリ

Java 用 Azure Cosmos DB for Apache Cassandra クライアント ライブラリを使用して、非構造化データの格納、管理、クエリを実行します。 このガイドの手順に従って、新しいアカウントの作成、Java クライアント ライブラリのインストール、アカウントへの接続、一般的な操作の実行、最終的なサンプル データのクエリを実行します。

API リファレンス ドキュメント | ライブラリのソース コード | パッケージ (Maven)

[前提条件]

• Azure サブスクリプション

  • Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

• Azure Cloud Shell の Azure CLI の最新バージョン。

  • CLI 参照コマンドをローカルで実行する場合は、 az login コマンドを使用して Azure CLI にサインインします。

• Java 21 以降

セットアップ中

まず、このガイドのアカウントと開発環境を設定します。 このセクションでは、アカウントの作成、資格情報の取得、開発環境の準備のプロセスについて説明します。

アカウントを作成する

まず、Apache Cassandra アカウント用の API を作成します。 アカウントが作成されたら、キースペースとテーブル リソースを作成します。

資格情報の取得

ここで、最近作成したアカウントへの接続を作成するために使用するクライアント ライブラリのパスワードを取得します。

開発環境の準備

次に、新しいプロジェクトとクライアント ライブラリを使用して開発環境を構成します。 この手順は、このガイドの残りの部分に進む前に必要な最後の前提条件です。

1. 空のディレクトリから開始します。

2. Maven を使用して新しい Java コンソール プロジェクトを生成します。

   mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   

3. Maven から java-driver-core パッケージをインポートします。 このセクションをpom.xmlファイル に 追加します。

   <dependency>
     <groupId>org.apache.cassandra</groupId>
     <artifactId>java-driver-core</artifactId>
     <version>[4.,)</version>
   </dependency>
   

4. /console/src/main/java/quickstart/App.java ファイルを開きます。

5. 既存の Java アプリケーションの定型句を確認します。

   package quickstart;
   
   /**
    * Hello world!
    *
    */
   public class App 
   {
       public static void main( String[] args )
       {
           System.out.println( "Hello World!" );
       }
   }
   

6. 定型文からコメントとコンソール出力を削除します。 このコード ブロックは、このガイドの残りの部分の開始点です。

   package quickstart;
   
   public class App 
   {
       public static void main(String[] args)
       {
       }
   }
   

7. java.security.NoSuchAlgorithmException名前空間をインポートします。

   import java.security.NoSuchAlgorithmException;
   

8. main メソッド シグネチャを更新して、NoSuchAlgorithmException 例外がスローされる可能性があることを示します。

   public static void main(String[] args) throws NoSuchAlgorithmException
   {    
   }
   

   Von Bedeutung

   このガイドの残りの手順では、 main メソッド内にコードを追加することを前提としています。

9. プロジェクトをビルドします。

   mvn compile
   

オブジェクト モデル

コード例

• クライアントの認証
• データのアップサート
• データの読み取り
• データのクエリ

クライアントの認証

まず、このガイドで前に収集した資格情報を使用してクライアントを認証します。

1. 統合開発環境 (IDE) で /console/src/main/java/quickstart/App.java ファイルを開きます。

2. 次の種類をインポートします。

   • java.net.InetSocketAddress
   • javax.net.ssl.SSLContext
   • com.datastax.oss.driver.api.core.CqlIdentifier
   • com.datastax.oss.driver.api.core.CqlSession
   • com.datastax.oss.driver.api.core.cql.BoundStatement
   • com.datastax.oss.driver.api.core.cql.PreparedStatement
   • com.datastax.oss.driver.api.core.cql.ResultSet
   • com.datastax.oss.driver.api.core.cql.Row

   import java.net.InetSocketAddress;    
   
   import javax.net.ssl.SSLContext;
   
   import com.datastax.oss.driver.api.core.CqlIdentifier;
   import com.datastax.oss.driver.api.core.CqlSession;
   import com.datastax.oss.driver.api.core.cql.BoundStatement;
   import com.datastax.oss.driver.api.core.cql.PreparedStatement;
   import com.datastax.oss.driver.api.core.cql.ResultSet;
   import com.datastax.oss.driver.api.core.cql.Row;
   

3. このガイドで前に収集した資格情報の文字列変数を作成します。 変数に username、 password、および contactPointという名前を付けます。 また、ローカル データ センターの region という名前の文字列変数を作成します。

   String username = "<username>";
   String password = "<password>";
   String contactPoint = "<contact-point>";
   

4. Azure Cosmos DB for Apache Cassandra アカウントを作成したリージョンに別の文字列変数を作成します。 この変数に region名前を付けます。

   String region = "<region>";
   

5. トランスポート層セキュリティ (TLS) プロトコルを使用していることを確認するために、 SSLContext オブジェクトを作成します。

   SSLContext sslContext = SSLContext.getDefault();
   

6. 前の手順で作成した資格情報と構成変数を使用して、新しい CqlSession オブジェクトを作成します。 連絡先ポイント、ローカル データ センター、認証資格情報、キースペース、トランスポート層セキュリティ (TLS) コンテキストを設定します。

   CqlSession session = CqlSession.builder()
       .addContactPoint(new InetSocketAddress(contactPoint, 10350))
       .withLocalDatacenter(region)
       .withAuthCredentials(username, password)
       .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
       .withSslContext(sslContext)
       .build();
   

データをアップサートする

次に、新しいデータをテーブルにアップサートします。 アップサートにより、同じデータがテーブルに既に存在するかどうかに応じて、データが適切に作成または置換されます。

1. このガイドで前に作成したテーブルに対応するフィールドを使用して、 Product という名前の新しいクラスを定義します。

   class Product {
       public String id;
       public String name;
       public String category;
       public int quantity;
       public boolean clearance;
   
       public Product(String id, String name, String category, int quantity, boolean clearance) {
           this.id = id;
           this.name = name;
           this.category = category;
           this.quantity = quantity;
           this.clearance = clearance;
       }
   
       @Override
       public String toString() {
           return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                   id, name, category, quantity, clearance);
       }
   }
   

   ヒント

   Java では、この型を別のファイルに作成することも、既存のファイルの末尾に作成することもできます。

2. Product型の新しいオブジェクトを作成します。 オブジェクトを product という名前の変数に格納します。

   Product product = new Product(
       "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "Yamba Surfboard",
       "gear-surf-surfboards",
       12,
       false
   );
   

3. 新しい行を挿入するための Cassandra クエリ言語 (CQL) クエリを使用して、 insertQuery という名前の新しい文字列変数を作成します。

   String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
   

4. insert ステートメントを準備し、製品プロパティをパラメーターとしてバインドします。

   PreparedStatement insertStmt = session.prepare(insertQuery);
   BoundStatement boundInsert = insertStmt.bind(
       product.id,
       product.name,
       product.category,
       product.quantity,
       product.clearance
   );
   

5. バインドされたステートメントを実行して製品をアップサートします。

   session.execute(boundInsert);
   

データの読み取り

次に、テーブルにアップサートされたデータを読み取る。

1. 同じid フィールドを持つ項目と一致する CQL クエリを使用して、readQueryという名前の新しい文字列変数を作成します。

   String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. このガイドで前に作成した製品と同じ値を使用して、 id という名前の文字列変数を作成します。

   String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. ステートメントを準備し、製品の id フィールドをパラメーターとしてバインドします。

   PreparedStatement readStmt = session.prepare(readQuery);
   BoundStatement boundRead = readStmt.bind(id);
   

4. バインドされたステートメントを実行し、結果を readResult という名前の変数に格納します。

   ResultSet readResult = session.execute(boundRead);
   

5. 結果セットから最初の行を取得し、見つかった場合は Product オブジェクトにマップします。

   Row row = readResult.one();
   Product matchedProduct = new Product(
       row.getString("id"),
       row.getString("name"),
       row.getString("category"),
       row.getInt("quantity"),
       row.getBoolean("clearance")
   );
   

データのクエリを実行する

次に、クエリを使用して、テーブル内の特定のフィルターに一致するすべてのデータを検索します。

1. 同じcategory フィールドを持つ項目と一致する CQL クエリを使用して、findQueryという名前の新しい文字列変数を作成します。

   String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   

2. このガイドで前に作成した製品と同じ値を使用して、 id という名前の文字列変数を作成します。

   String category = "gear-surf-surfboards";
   

3. ステートメントを準備し、製品カテゴリをパラメーターとしてバインドします。

   PreparedStatement findStmt = session.prepare(findQuery);
   BoundStatement boundFind = findStmt.bind(category);
   

4. バインドされたステートメントを実行し、結果を findResults という名前の変数に格納します。

   ResultSet results = session.execute(boundFind);
   

5. クエリ結果を反復処理し、各行を Product オブジェクトにマップします。

   for (Row result : results) {
       Product queriedProduct = new Product(
           result.getString("id"),
           result.getString("name"),
           result.getString("category"),
           result.getInt("quantity"),
           result.getBoolean("clearance")
       );
       // Do something here with each result
   }
   

セッションを閉じる

Java では、クエリと操作が完了したら、セッションを閉じる必要があります。

session.close();

コードを実行する

アプリケーション ディレクトリのターミナルを使用して、新しく作成したアプリケーションを実行します。

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

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

ここで、最近作成したアカウントへの接続を作成するために使用するクライアント ライブラリのパスワードを取得します。

次のステップ