演習 - Maven を使用して Java アプリを設定する

  • 15 分

このユニットでは、任意の IDE を使用してコードを編集することで、基本的なコンソール アプリを作成します。 必要に応じて、任意のターミナルを使用してコードを実行します。

Azure Cosmos DB リソースを作成する

このラボを完了できるよう、Microsoft Learn には、アカウントとリソースを作成できる無料の Azure サンドボックスが用意されています。 このサブスクリプションで Azure Cosmos DB アカウントを設定した後、データベースとコンテナーを作成します。

  1. サンドボックスをアクティブ化したときと同じアカウントを使用して、Azure portal にサインインします。
  2. Azure portal を使用して、任意の名前で Azure Cosmos DB アカウントを作成します。 アカウントのリソース グループの選択を求められたら、リソースグループ [サンドボックス リソース グループ] を見つけて、それを選択します。
  3. をお使い Azure Cosmos DB アカウントで、Users というデータベースを作成します。
  4. Users データベースで、/userId のパーティション キーを持つ WebCustomers という名前のコンテナーを作成します。 WebCustomers に対して 400 RU/秒をプロビジョニングします。

作業ディレクトリを作成する

  1. Java アプリケーション用のテンプレートが用意されています。 テンプレート リポジトリをシステムにクローンします。

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Windows エクスプローラーを開き、クローンされたリポジトリに移動します。 java_lab サブディレクトリを入力します。

    重要

    このモジュールでの作業はすべて、java_lab サブディレクトリで行います。

  3. テンプレートには、プロジェクトに必要な依存関係が既に取り込まれている Maven の pom.xml ファイルが含まれます。 このファイルを開き、次の依存関係を確認します。

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

    この依存関係により、Azure Cosmos DB Java SDK の最新バージョンが取り込まれます。 このファイルを複製できます。

  4. 次に、Hello World をビルドして実行します。 IDE またはターミナルを使用して、このプロジェクトを開きます。 IDE によっては、java サブディレクトリの pom.xml ファイルをプロジェクトとして開くことができる場合があります。

    プロジェクトを開いたら、src/main/java/com/azure/cosmos/examples/mslearnbasicapp に移動し、CosmosApp.java を開きます。これは、開発する Java アプリケーションのテンプレートです。 次のように表示されます。

    import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}

    このアプリケーション コードでは、簡単な "Hello World" が実装されています。

  5. お使いの IDE に Maven アプリケーションをビルドおよび実行するツールが用意されている場合:その IDE を使用してアプリケーションをビルドして実行し、アプリケーションによってターミナルに Hello World が記録されることを確認します。

  6. ターミナルを使用して Maven アプリケーションをビルドおよび実行する場合:次のコマンドを使用して、Maven プロジェクトをビルドします。

    mvn clean package

    次に、次のコマンドを実行します。

    mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    アプリケーションによって次の出力がターミナルに記録されることを確認します。

    INFO: Hello World.

Azure Cosmos DB にアプリを接続する

  1. CosmosApp クラスに、Azure Cosmos DB 接続の詳細用の次の静的クラス変数を作成します。

    /** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

  2. Azure portal に戻り、[キー] ペインに移動し、Azure Cosmos DB のエンドポイント URI と主キーをコピーして、上記の変数定義に貼り付けます。

    たとえば、URI が https://cosmosacct.documents.azure.com:443/ の場合、新しい変数の割り当ては次のようになります: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";。 主キーが elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== の場合、新しい変数の割り当ては次のようになります: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";。

CosmosAsyncClient インスタンスを作成する

次に、CosmosAsyncClient のインスタンスを作成します。これは、Azure Cosmos DB サービスのクライアント側の表現です。 このクライアントは、サービスに対する要求の構成と実行に使用されます。

  1. CosmosApp.java で、次の静的変数宣言を CosmosApp クラスに追加します。

    /** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;

    多くの場合、client、database、および container クラスはまだ Java ファイルにインポートされていません。 そのため、このタイミングでそれを行うことをお勧めします。 IDE によっては、入力したコードに基づいて依存関係を自動的にインポートすることができ、ここでそれが役に立ちます。 通常、貼り付けるコードのブロックが提供されても、それを動かすには import ステートメントを追加することが必要になる場合があります。

  2. クラスに引数を指定せずに、basicOperations という private void メソッドを作成します。

  3. 次のコードを追加して、basicOperations メソッドに CosmosAsyncClient インスタンスを作成し、Users データベースが存在するかどうかを確認するコードを含めます。

     client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

  4. この時点で、basicOperations メソッドには Azure Cosmos DB と対話するためのコードが含まれています。 ただし、このメソッドは main で呼び出されないため、アプリケーションでは引き続き "Hello World" が出力されます。確認のため、IDE で CosmosApp.java をビルドして実行するか、ターミナルで次のコマンドを使用してプログラムを実行します

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    この場合も、アプリケーションによって次の出力がターミナルに記録されることを確認します。

    INFO: Hello World.

  5. main メソッドに次のコードをコピーして貼り付け、現在の logger.info("Hello World."); 行を上書きします。

    try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

    これにより、アプリケーションで Azure Cosmos DB のコードがトリガーされます。

  6. IDE で CosmosApp.java をビルドして実行するか、またはターミナルで次を使用してプログラムを実行します。

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    ターミナルに多数のログ メッセージが表示されることがあります。その一部は、SDK 自体によって生成されたものです。 目を通して、アプリによって次の出力がターミナルに記録されていることを確認します。

    INFO: Database and container validation complete

このユニットでは、Azure Cosmos DB Java アプリケーション用の基盤を設定しました。 Maven アプリケーションをセットアップし、基本的な "Hello World" プロジェクトを作成し、プロジェクトを Azure Cosmos DB エンドポイントに接続するようにそれを拡張しました。

  1. Java アプリケーション用のテンプレートが用意されています。 テンプレート リポジトリをシステムにクローンします

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. エクスプローラーを開き、クローンしたリポジトリに移動します。 spring_lab サブディレクトリを入力します。

    重要

    このモジュールでの作業はすべて、spring_lab サブディレクトリで行います。

  3. テンプレートには、プロジェクトに必要な依存関係が既に取り込まれている Maven の pom.xml が含まれます。 このファイルを開き、次の依存関係を確認します。

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

    この依存関係により、Spring Data Azure Cosmos DB の最新バージョンが取り込まれます。 このファイルを複製できます。

Azure Cosmos DB にアプリを接続する

  1. IDE またはターミナルを使用して、このプロジェクトを開きます。 IDE によっては、spring サブディレクトリの pom.xml ファイルをプロジェクトとして開くことができる場合があります。 プロジェクトが開いた後、エクスプローラー ツールを使用して src/main/resources/ に移動します。 application.properties.rename という名前のファイルがあるはずです。 Spring Data では、ハードコーディングされた構成パラメーターよりも構成ファイルが優先されます。Spring Data プロジェクトの構成ファイルを作成するには、application.properties.rename を application.properties にコピーし、新しい application.properties ファイルを開きます。 Web サイトの下部に

    cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

    任意の方法を使用して、${ACCOUNT_HOST} と ${ACCOUNT_KEY} を設定します。値をコピーして application.properties に貼り付けるか、お使いの IDE でこれらの環境変数を定義します。 次の手順では、これらの変数に必要な値を確認します。

  2. Azure portal に戻り、[キー] ペインに移動し、Azure Cosmos DB エンドポイント URI と主キーをコピーします。 前の手順で説明したように、任意の方法を使用して、Azure Cosmos DB エンドポイント URI と主キーを前述の変数に割り当てます。

    たとえば、URI が https://cosmosacct.documents.azure.com:443/ であり、エンドポイントと主キーを application.properties に貼り付けることを選択した場合、application.properties の行は次のようになりますcosmos.uri=https://cosmosacct.documents.azure.com:443/。 主キーが elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== の場合、同じプロセスに従うと、新しい変数の割り当ては次のようになりますcosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==。

Azure Cosmos DB クライアントを構成する

Spring Data Azure Cosmos DB を使用すると、Azure Cosmos DB クライアントは起動時に自動的にインスタンス化されます。 Azure Cosmos DB クライアントは、Azure Cosmos DB サービスのクライアント側の表現であり、サービスに対して要求を実行するために使用されます。 コードを使用し、application.properties から取得したプロパティと共に一連のビルダー メソッドを使用することで、インスタンス化する前に Azure Cosmos DB クライアントを構成できます。

  1. CosmosProperties.java を開きます。 このファイルは完成した形で提供されているので、内容を確認するだけで済みます。

    @ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}

    クラス メンバー uri、key、secondaryKey、queryMetricsEnabled を確認します。 application.properties を見直して、CosmosProperties メンバー名が application.properties プロパティ名と密接に対応していることを確認します。 CosmosProperties クラスには、アプリケーションの残りの部分から application.properties の構成設定にアクセスするためのゲッターとセッターが用意されています。 application.properties から構成をプルするコードはここにないことに注意してください。Spring Data によってこのファイルの構造が認識され、構成ファイルの解析後にメンバー変数が自動的に設定されます。

    今後、Azure Cosmos DB クライアントを構成するときに、この設定を活用します。

  2. CosmosSampleConfiguration.java で、CosmosSampleConfiguration クラスを調べて、空の cosmosClientBuilder メソッドを見つけます。

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}

    起動時に、Spring Data によって自動的にこのメソッドが呼び出され、このメソッドから返される CosmosClientBuilder が取得され、その build() メソッドが呼び出されます。その時点で (内部で)、CosmosClientBuilder に含まれている構成設定に基づいて CosmosAsyncClient インスタンスが作成されます。 このメソッドを使用して、ビルダー メソッドを使用して CosmosClientBuilder を構成できます。

  3. コンストラクターの挿入 (@Autowired) を使用するフィールド インジェクションではなく) を使用して properties 変数をインスタンス化し、"そのメンバー変数に構成ファイルから解析された値を設定する" ことに注意してください。 これにより、このクラスのインスタンスが作成されるときに必要なすべての依存関係が存在するようになり、将来テスト コードの記述が容易になります。

    //use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}

    次に示すように、properties を使用して、Azure Cosmos DB アカウントの uri と key を取得し、cosmosClientBuilder を実装することができます。

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}

    この実装内容

    1. properties から uri と key をプルします
    2. それらを endpoint および key ビルダー メソッドに渡します。
    3. さらに、Azure Cosmos DB サービスへのネットワーク接続を構成します ("直接モード" では、クライアント アプリケーションはバックエンドの Azure Cosmos DB パーティションと直接通信します)。

  4. CosmosSampleConfiguration.java に戻り、getDatabaseName メソッドを見つけます。

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

    既定の戻り値をデータベースの名前である "Users" に変更します。 このように、Spring Data によって起動時に Azure Cosmos DB に自動的に接続されると、*Users データベースに接続されます。

  5. WebCustomer.java に移動します。 WebCustomer クラスの前に @Container の注釈が付いていることがわかります。

    @Container(containerName = "", ru = "")

    @Container は 2 つの引数を受け取ります。

    • containerName:Azure Cosmos DB コンテナーの名前 (WebCustomers)
    • ru:コンテナーに対してプロビジョニングされたスループット。 400 RU/秒は、Microsoft Learn の演習に適した既定値です。

    次のように、ユースケースに合わせて @Container をカスタマイズします。

    @Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {

  6. この時点で、Spring Data プロジェクトは Azure Cosmos DB と対話するように設定されています。 次に、Hello World をビルドして実行します。 src/main/java/com/azure/cosmos/examples/springexamples に移動し、CosmosSample.java を開きます。これは、これから開発する Spring Data アプリケーションのテンプレートです。 次のように表示されます。

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

    このアプリケーション コードでは、簡単な "Hello World" が実装されています。

  7. お使いの IDE に Maven アプリケーションをビルドおよび実行するツールが用意されている場合:その IDE を使用してアプリケーションをビルドして実行し、アプリケーションによってターミナルに Hello World が記録されることを確認します。

  8. ターミナルを使用して Maven アプリケーションをビルドおよび実行する場合:次のコマンドを使用して、Maven プロジェクトをビルドします。

    mvn clean package

    次に、次のコマンドを実行します。

    mvn spring-boot:run

    他のすべての出力の中でも、ターミナルに対する次の出力がアプリケーションによって記録されていることを確認します。

    INFO: Hello World.

このユニットでは、Azure Cosmos DB Java アプリケーション用の基盤を設定しました。 Maven アプリケーションをカスタマイズし、基本的な "Hello World" プロジェクトを拡張して Azure Cosmos DB エンドポイントに接続しました。