Share via

Azure Cosmos DB 開発ガイド

  • [アーティクル]

Azure Cosmos DB 用 Azure Spring Data では、NoSQL 用 Azure Cosmos DB の Spring Data サポートが提供されます。 Azure Cosmos DB は、開発者が SQL、MongoDB、Cassandra、Graph、Table などのさまざまな標準 API を使用してデータを操作できるようにするグローバル分散型データベース サービスです。

このガイドでは、Azure Spring Data Azure Cosmos DB SDK の概念、サポートされている機能、トラブルシューティング、既知の問題について説明します。 以下の概念とコード サンプルの詳細については、Azure Cosmos DB SDK の Spring Data の readme を参照してください。

バージョンのサポート ポリシー

Spring Boot バージョンのサポート

このプロジェクトでは、複数の Spring Boot バージョンがサポートされています。 詳細については、Spring Boot のサポート ポリシーを参照してください。 Maven ユーザーは、spring-boot-starter-parent プロジェクトを継承して、依存関係管理セクションを取得し、Spring で依存関係のためにバージョンを管理できるようにします。 詳細については、Spring Boot のバージョン サポートを参照してください。

Spring Data バージョンのサポート

このプロジェクトでは、さまざまな spring-data-commons のバージョンがサポートされています。 詳細については、Spring Data のバージョン サポートを参照してください。

使用する Azure Spring Data Azure Cosmos DB のバージョン

Azure Spring Data Azure Cosmos DB ライブラリでは、Spring Boot/Spring Cloud の複数のバージョンがサポートされています。 Spring Boot/Spring Cloud バージョンで使用する Azure Spring Data Azure Cosmos DB のバージョンの詳細については、Azure Cosmos DB 用の Azure Spring Data のどのバージョンを使用する必要があるかを参照してください。

作業の開始

パッケージを組み込む

Maven を使用している場合は、以下の依存関係を追加します。

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

前提条件

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

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

構成クラスを設定してカスタマイズする

構成クラスを設定するには、拡張する必要があります AbstractCosmosConfiguration。 詳細については、「構成クラスの設定」を参照してください。

Azure Spring Data Azure Cosmos DB SDK で使用される基になる機能CosmosAsyncClientをカスタマイズするには、その両方または両方をDirectConnectionConfigGatewayConnectionConfig指定し、その両方を指定しますCosmosClientBuilder。 完全なサンプルについては、構成のカスタマイズに関するセクションを参照してください。

エンティティ設定

単純なエンティティを Azure Cosmos DB の項目として定義できます。 エンティティを定義するには、@Container 注釈を追加し、コンテナーに関連するプロパティを指定します。 詳しくは、「エンティティの定義」をご覧ください。

コンテナー注釈では、コンテナー名、要求ユニット (RU)、有効期間、自動スケーリング スループットを使用したコンテナーの作成、入れ子になったパーティション キーのサポート、およびその他のコンテナー プロパティの指定がサポートされています。

リポジトリの設定

Azure Spring Data Azure Cosmos DB では、次の ReactiveCrudRepository 基本的な CRUD 機能を提供する (非同期 API) と CrudRepository (同期 API) がサポートされています。

  • save
  • findAll
  • ID による findOne
  • deleteAll
  • ID による削除
  • エンティティの削除

アプリケーションの Spring Data リポジトリを設定するために、CosmosRepository (同期 API のサポート用) または ReactiveCosmosRepository (非同期 API サポート用) を拡張できます。 詳細については、「リポジトリの作成」を参照してください。

Azure Spring Data Azure Cosmos DB では、次を使用して @Queryリポジトリ内の注釈付きクエリを指定できます。 詳細については、「QueryAnnotation: リポジトリ内の注釈付きクエリの使用」を参照してください。

Spring Data の注釈

Spring Data の @Id 注釈

ドメイン クラスのフィールドを id にマップするための複数の方法があります。 詳細については、Spring Data ID の注釈コードのセクションを参照してください。

ID の自動生成

Azure Spring Data Azure Cosmos DB では、注釈を使用した ID の自動生成が @GeneratedValue サポートされています。 詳細については、ID の自動生成に関するセクションを参照してください。

SpEL 式とカスタム コンテナー名

既定では、コンテナー名はユーザー ドメイン クラスのクラス名になります。 カスタマイズするには、注釈 @Container(containerName="myCustomContainerName") をドメイン クラスに追加します。 詳細については、SpEL 式とカスタム コンテナー名に関するセクションを参照してください。

カスタム IndexingPolicy

既定では、IndexingPolicy が Azure サービスによって設定されます。 カスタマイズするには、注釈 @CosmosIndexingPolicy をドメイン クラスに追加します。 詳細については、インデックス ポリシーに関するセクションを参照してください。

一意のキー ポリシー

Azure Spring Data Azure Cosmos DB では、doメイン クラスに注釈@CosmosUniqueKeyPolicyを追加することで、コンテナーの設定UniqueKeyPolicyをサポートしています。 詳細については、一意のキー ポリシーに関するセクションを参照してください。

Azure Cosmos DB パーティション

Azure-spring-data-cosmos では Azure Cosmos DB パーティションがサポートされます。

パーティション キー フィールドにするドメイン クラスのフィールドを指定するには、それに @PartitionKey の注釈を付けるだけです。

CRUD 操作を実行するときに、パーティションの値を指定します。

詳細については、こちらのテスト セクションを参照してください。

オプティミスティック ロック

Azure-spring-data-cosmos では、特定のコンテナーでオプティミスティック ロックがサポートされます。つまり、項目ごとの upsert/削除は、その間に別のプロセスによってその項目が変更されると、例外が発生して失敗することを意味します。 詳細については、オプティミスティック ロックに関するセクションを参照してください。

Spring Data カスタム クエリ、ページング、並べ替え

Azure-spring-data-cosmos では、Spring Data カスタム クエリがサポートされています。たとえば、findByAFieldAndBField などの検索操作があります。 さらに、Spring Data の Pageable、Slice、Sort がサポートされています。 詳細については、クエリ、ページング、並べ替えのセクションを参照してください。

Spring Data Cosmos を使用した Azure Cosmos DB Java SDK の使用

Azure-spring-data-cosmos の使用 Azure Cosmos DB Java SDKをサポートしています。 ユーザーは、Azure Cosmos DB Java SDK でサポートされている操作をApplicationContext取得CosmosClientまたはCosmosAsyncClient実行できます。 詳細については、「Spring Data Cosmos を使用した Azure Cosmos クライアントの 使用」セクションを参照してください。

Spring Data REST

Azure-spring-data-cosmos は Spring Data REST をサポートしています。 詳細については、「 Azure Spring Data Azure Cosmos DB REST API」セクションを参照してください。

監査

Azure-spring-data-cosmos では、標準の spring-data 注釈を使用して、データベース エンティティ上で監査フィールドがサポートされます。 詳細については、「 Spring Data Azure Cosmos DB 監査」セクションを参照してください。

マルチデータベース構成

Azure-spring-data-cosmos では、"マルチデータベース アカウント"および "マルチデータベースを使用した単一アカウント" を含む、マルチデータベース構成がサポートされています。 完全なコード スニペットについては、マルチデータベース構成に関するセクションを参照してください。

トラブルシューティング

全般

バグを見つけた場合は、こちらで問題を報告してください。

新しい機能または変更された可能性のある変更を提案するには、バグの場合と同じ方法で問題を報告します。

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

Azure-spring-data-cosmos では、log4j や logback などの一般的なログ記録フレームワークへのログ記録をサポートするロギング ファサードとして SLF4j を使用します。 詳細については、クライアント ログの有効化に関するセクションを参照してください。

例

完全なサンプル プロジェクトについては、サンプル プロジェクトを参照してください。

マルチデータベース アカウント

完全なサンプル プロジェクトについては、マルチデータベースのサンプル プロジェクトを参照してください。

マルチデータベースを使用した単一アカウント

完全なサンプル プロジェクトについては、マルチデータベースを使用した単一アカウントのサンプル プロジェクトを参照してください。

次のステップ

投稿

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

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

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

Impressions