Java 用 Azure Cosmos DB クライアントライブラリ - バージョン 4.52.0

[アーティクル]
10/24/2023

Azure Cosmos DB は、運用/分析ワークロード向けの、Microsoft のグローバル分散型マルチモデルデータベースサービスです。スループット、コンピューティング、およびストレージを自動的にスケーリングすることで、マルチマスタリング機能を提供します。このプロジェクトでは、Azure Cosmos DB Database Service の SQL API と対話するための Java の SDK ライブラリを提供します。

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージを組み込む

BOM ファイルを含める

ライブラリの GA バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、バージョンタグのない依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。 //: # ({x-version-update-start;com.azure:azure-cosmos;current})

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

以前のリリースについては、Maven Central を参照してください

パッケージの詳細については、javadocs を参照してください

前提条件

バージョン 8 以降の Java Development Kit (JDK)
アクティブな Azure アカウントアカウントがない場合、Azure 試用版にサインアップして、最大 10 件の無料 Mobile Apps を入手できます。お持ちでない場合は、無料アカウントにサインアップしてください。または、Azure Cosmos DB Emulator を使用して、開発とテストを行うこともできます。エミュレーター https 証明書が自己署名されているため、ここで説明するように、その証明書を Java の信頼された証明書ストアにインポートする必要があります
(省略可能) ログ記録ファサードの SLF4J。
(省略可能) SLF4J バインディングを使用して、特定のログ記録フレームワークを SLF4J と関連付けます。
(省略可能) Maven

SLF4J は、ログ記録を使用する場合にのみ必要です。また、SLF4J API と選択したログ記録の実装をリンクする SLF4J バインディングもダウンロードしてください。詳細については、SLF4J のユーザーマニュアルを参照してください。

SDK には、Reactor Core ベースの非同期 API が用意されています。リアクタコアと Flux/Mono の種類の詳細については、こちらを参照してください。

クライアントを認証する

Azure Cosmos DB サービスと対話するには、Cosmos Client クラスのインスタンスを作成する必要があります。これを可能にするには、Azure Cosmos DB サービスの URL とキーが必要です。

SDK には 2 つのクライアントが用意されています。

CosmosAsyncClient 非同期 API を使用する操作の場合は。
CosmosClient 同期 (ブロック) API を使用する操作の場合。

CosmosAsyncClient を作成する

CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildAsyncClient();

CosmosClient の作成

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildClient();

主要概念

Azure Cosmos DB Java SDK には、Azure Cosmos DB SQL API にアクセスするためのクライアント側の論理表現が用意されています。 Cosmos DB アカウントには 0 個以上のデータベースが含まれており、データベース (DB) には 0 個以上のコンテナーが含まれており、コンテナーには 0 個以上の項目が含まれています。データベース、コンテナー、項目の詳細については、こちらを参照してください。コンテナーのレベルで定義されているいくつかの重要なプロパティには、プロビジョニングされたスループットとパーティションキーがあります。

グローバル分散

Azure Cosmos DB は、待機時間の短縮、スループットのエラスティックなスケーラビリティ、データの一貫性を保つための明確に定義されたセマンティクス、および高可用性を確保するように設計された、グローバル分散データベースサービスです。つまり、世界のどの場所でも高速な応答時間を保証すること、常にオンラインであること、スループットとストレージのスケーラビリティが無制限でエラスティックなことがアプリケーションに求められる場合は、Azure Cosmos DB を使用してアプリケーションを構築してください。グローバル配布の詳細については、こちらを参照してください。

スループットプロビジョニング

Azure Cosmos DB では、データベースとコンテナーでプロビジョニング済みのスループットを設定できます。プロビジョニング済みスループットには、標準 (手動) と自動スケールの 2 種類があります。プロビジョニング済みスループットはコンテナー単位またはデータベース単位で選択できますが、通常はコンテナーレベルのスループット仕様が推奨されます。スループットプロビジョニングの詳細については、こちらを参照してください。

要求ユニット数 (RU)

Azure Cosmos DB では、多くの API (SQL、MongoDB、Cassandra、Gremlin、Table など) がサポートされています。各 API には、固有のデータベース操作のセットがあります。これらの操作の範囲は、単純なポイント読み取り/書き込みから、複雑なクエリにまで及びます。各データベース操作は、それらの操作の複雑さに基づいて、システムリソースを消費します。すべてのデータベース操作のコストは Azure Cosmos DB によって正規化され、要求ユニット (RU) によって表されます。 1 秒間の RU は、スループットのための通貨と考えることができます。 1 秒あたりの RU は、速度に基づく通貨です。それにより、Azure Cosmos DB によってサポートされるデータベース操作を実行するために必要な CPU、IOPS、メモリなどのシステムリソースが抽象化されます。要求ユニットの詳細については、こちらを参照してください。

パーティション分割

Cosmos DB コンテナーに項目を挿入すると、要求を処理するためのストレージとコンピューティングが追加されて、データベースが水平方向に拡張されます。ストレージとコンピューティングの容量は "パーティション" と呼ばれる個別の単位で追加されます。ドキュメント内の 1 つのフィールドを選択し、これを各ドキュメントをパーティションにマップするパーティションキーにする必要があります。パーティションを管理する方法として、各パーティションに、パーティションキー値の範囲を超えて、ほぼ等しいスライスを割り当てます。そのため、比較的ランダムまたは均等に分散されたパーティションキーを選択することをお勧めします。そうしないと、一部のパーティションに非常に多くの要求が集中し ("ホットパーティション")、他のパーティションは少数の要求しか受け取らない ("コールドパーティション") 状況が発生しますが、これは回避する必要があります。パーティション分割の詳細については、こちらを参照してください。

例

次のセクションでは、次のような最も一般的な Cosmos DB SQL API タスクの一部をカバーするいくつかのコードスニペットを示します。

Cosmos クライアントを作成する
データベースの作成
コンテナーの作成
アイテムに対する CRUD 操作

Cosmos クライアントを作成する

// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildAsyncClient();

// Create a new CosmosClient via the CosmosClientBuilder
CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildClient();

// Create a new CosmosClient with customizations
cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .directMode(directConnectionConfig, gatewayConnectionConfig)
    .consistencyLevel(ConsistencyLevel.SESSION)
    .connectionSharingAcrossClientsEnabled(true)
    .contentResponseOnWriteEnabled(true)
    .userAgentSuffix("my-application1-client")
    .preferredRegions(Arrays.asList("West US", "East US"))
    .buildClient();

データベースの作成

前の例で作成したクライアントのいずれかを使用して、次のようなデータベースを作成できます。

// Get a reference to the container
// This will create (or read) a database and its container.
cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .map(databaseResponse -> cosmosAsyncClient.getDatabase(databaseResponse.getProperties().getId()))
    .subscribe(database -> System.out.printf("Created database '%s'.%n", database.getId()));

コンテナーの作成

上記で作成したデータベースを使用すると、次のようなコンテナーを作成するための別の操作をそれにチェーンできます。

cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .flatMap(databaseResponse -> {
        String databaseId = databaseResponse.getProperties().getId();
        return cosmosAsyncClient.getDatabase(databaseId)
            // Create Container
            .createContainerIfNotExists("<YOUR CONTAINER NAME>", "/id")
            .map(containerResponse -> cosmosAsyncClient.getDatabase(databaseId)
                .getContainer(containerResponse.getProperties().getId()));
    })
    .subscribe(container -> System.out.printf("Created container '%s' in database '%s'.%n",
        container.getId(), container.getDatabase().getId()));

アイテムに対する CRUD 操作

// Create an item
cosmosAsyncContainer.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
    .flatMap(response -> {
        System.out.println("Created item: " + response.getItem());
        // Read that item 👓
        return cosmosAsyncContainer.readItem(response.getItem().getId(),
            new PartitionKey(response.getItem().getId()), Passenger.class);
    })
    .flatMap(response -> {
        System.out.println("Read item: " + response.getItem());
        // Replace that item 🔁
        Passenger p = response.getItem();
        p.setDestination("SFO");
        return cosmosAsyncContainer.replaceItem(p, response.getItem().getId(),
            new PartitionKey(response.getItem().getId()));
    })
    // delete that item 💣
    .flatMap(response -> cosmosAsyncContainer.deleteItem(response.getItem().getId(),
        new PartitionKey(response.getItem().getId())))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// ...

サンプルアプリの概要については、こちらを参照してください。

また、プロジェクトの例も増えています。

トラブルシューティング

全般

Azure Cosmos DB は、高速で柔軟性に優れた分散データベースです。待機時間とスループットが保証されており、シームレスにスケーリングできます。 Azure Cosmos DB でデータベースをスケーリングするために、アーキテクチャを大きく変更したり、複雑なコードを記述したりする必要はありません。スケールアップとスケールダウンは、API 呼び出しか SDK メソッド呼び出しを 1 回行うだけで簡単に実行できます。ただし、Azure Cosmos DB にはネットワーク呼び出しによってアクセスするため、Azure Cosmos DB Java SDK v4 を使用するときに最高のパフォーマンスを実現するために、クライアント側の最適化を行うことができます。

パフォーマンスガイドでは、これらのクライアント側の最適化について説明します。
トラブルシューティングガイドでは、Azure Cosmos DB Sql API アカウントで Azure Cosmos DB Java SDK v4 を使用する場合の一般的な問題、回避策、診断手順、およびツールについて説明します。

クライアントのログ記録を有効にする

Azure Cosmos DB Java SDK v4 では、log4j や logback などの一般的なログ記録フレームワークへのログ記録をサポートするロギングファサードとして SLF4j が使用されます。

たとえば、ログ記録フレームワークとして log4j を使用する場合は、Java classpath に次の libs を追加します。

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

また log4j の構成を追加します。

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

次の手順

サンプルについては、こちらを参照してください。
クイックスタートを実行する - Cosmos DB SQL API データを管理するための Java アプリの構築
Azure Cosmos DB サービスについて詳細を確認する

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用 Azure Cosmos DB クライアントライブラリ - バージョン 4.52.0

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

CosmosAsyncClient を作成する

CosmosClient の作成

主要概念

グローバル分散

スループットプロビジョニング

要求ユニット数 (RU)

パーティション分割

例

Cosmos クライアントを作成する

データベースの作成

コンテナーの作成

アイテムに対する CRUD 操作

トラブルシューティング

全般

クライアントのログ記録を有効にする

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Cosmos DB クライアント ライブラリ - バージョン 4.52.0

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

クライアントを認証する

CosmosAsyncClient を作成する

CosmosClient の作成

主要概念

グローバル分散

スループット プロビジョニング

要求ユニット数 (RU)

パーティション分割

例

Cosmos クライアントを作成する

データベースの作成

コンテナーの作成

アイテムに対する CRUD 操作

トラブルシューティング

全般

クライアントのログ記録を有効にする

次の手順

共同作成

フィードバック

その他のリソース

Java 用 Azure Cosmos DB クライアントライブラリ - バージョン 4.52.0

スループットプロビジョニング