クイックスタート: Azure SDK for Java で Azure Cosmos DB for NoSQL を使用する

• 適用対象:

  ✅ NoSQL

• .NET
• Node.js
• Java
• Python
• Go

このクイックスタートでは、Azure SDK for Java を使用して、基本的な Azure Cosmos DB for Table アプリケーションをデプロイします。 Azure Cosmos DB for Table はスキーマレス データ ストアであり、これによりアプリケーションは構造化されたテーブル データをクラウドに保存できます。 Azure SDK for Java を使用して、Azure Cosmos DB リソース内でテーブルや行を作成し、基本的なタスクを実行する方法について説明します。

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

前提条件

• Azure Developer CLI
• Docker Desktop
• Java 21

Azure アカウントをお持ちでない場合は、開始する前に無料アカウントを作成してください。

プロジェクトを初期化する

Azure Developer CLI (azd) を使用して、Azure Cosmos DB for Table アカウントを作成し、コンテナー化されたサンプル アプリケーションをデプロイします。 サンプル アプリケーションでは、クライアント ライブラリを使って、サンプル データの管理、作成、読み取り、クエリを実行します。

1. 空のディレクトリでターミナルを開きます。

2. まだ認証されていない場合は、azd auth login を使用して Azure Developer CLI に対して認証します。 ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。

   azd auth login
   

3. azd init を使ってプロジェクトを初期化します。

   azd init --template cosmos-db-nosql-java-quickstart
   

4. 初期化中に、一意の環境名を構成します。

5. azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。

   azd up
   

6. このプロビジョニング プロセス中に、サブスクリプション、目的の場所、ターゲット リソース グループを選択します。 プロビジョニング プロセスが完了するまで待ちます。 このプロセスには 5 分ほどかかる可能性があります。

7. Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。 実行中のアプリの出力を確認します。

クライアント ライブラリをインストールする

クライアント ライブラリは、Maven を介して azure-spring-data-cosmos パッケージとして入手できます。

1. /src/web フォルダーに移動し、pom.xml ファイルを開きます。

2. まだ存在しない場合は、azure-spring-data-cosmos パッケージのエントリを追加します。

   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-spring-data-cosmos</artifactId>
   </dependency>
   

3. また、azure-identity パッケージに別の依存関係が存在しない場合は追加します。

   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-identity</artifactId>
   </dependency>
   

オブジェクト モデル

名前	説明
EnableCosmosRepositories	この型は、Azure Cosmos DB for NoSQL にアクセスするリポジトリを構成するために使われるメソッド デコレーターです。
CosmosRepository	このクラスは主要なクライアント クラスであり、コンテナー内のデータを管理するために使われます。
CosmosClientBuilder	このクラスは、リポジトリで使われるクライアントを作成するために使われるファクトリです。
Query	この型は、リポジトリが実行するクエリを指定するために使われるメソッド デコレーターです。

コード例

• クライアントを認証する
• データベースの取得
• コンテナーの取得
• 項目の作成
• アイテムを取得する
• クエリ項目

テンプレートのサンプル コードでは、cosmicworks というデータベースと products というコンテナーを使います。 products コンテナーには、各製品の名前、カテゴリ、数量、一意識別子、販売フラグなどの詳細が含まれています。 コンテナーでは、論理パーティション キーとして /category プロパティを使います。

クライアントを認証する

まず、このサンプルは、Azure Cosmos DB for NoSQL への接続を構成するために、AbstractCosmosConfiguration から継承する新しいクラスを作成します。

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

このサンプルでは、構成クラス内で、CosmosClientBuilder クラスの新しいインスタンスを作成し、DefaultAzureCredential インスタンスを使って認証を構成します。

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint("<azure-cosmos-db-nosql-account-endpoint>")
        .credential(credential);
}

データベースの取得

構成クラスで、サンプルでは、cosmicworks という既存のデータベースの名前を返すメソッドを実装します。

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

コンテナーの取得

Container メソッド デコレーターを使って、コンテナー内の項目を表すクラスを構成します。 JSON にシリアル化するすべてのメンバーを含むクラスを作成します。 この例では、型には一意識別子と、カテゴリ、名前、数量、価格、在庫一掃セールのフィールドがあります。

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

    // Extra members omitted for brevity
}

項目を作成する

repository.save を使ってコンテナー内に項目を作成します。

Item item = new Item(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

項目を読み取る

一意識別子 (id) フィールドとパーティション キー フィールドの両方を使って、ポイント読み取り操作を実行できます。 repository.findById を使って、特定の項目を効率的に取得できます。

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", partitionKey);
if (existing_item.isPresent()) {
    // Do something
}

クエリ項目

リポジトリのインターフェイスでクエリを定義することにより、コンテナー内の複数の項目に対してクエリを実行します。 このサンプルでは、Query メソッド デコレーターを使って、このパラメーター化されたクエリを実行するメソッドを定義します。

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {

    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);

}

repository.getItemsByCategory を使ってクエリの結果をすべて取り込みます。 クエリの結果をループ処理します。

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

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

サンプル アプリケーションやリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。

azd down

関連するコンテンツ

• .NET のクイックスタート
• Node.js クイック スタート
• Java クイックスタート
• Go クイックスタート