Guide de développement Azure Cosmos DB

Azure Spring Data pour Azure Cosmos DB fournit la prise en charge de Spring Data pour Azure Cosmos DB pour NoSQL. Azure Cosmos DB est un service de base de données distribué à l’échelle mondiale qui permet aux développeurs d’utiliser des données à l’aide de diverses API standard, telles que SQL, MongoDB, Cassandra, Graph et Table.

Ce guide vous guide tout au long des concepts du Kit de développement logiciel (SDK) Azure Spring Data Azure Cosmos DB, des fonctionnalités prises en charge, des dépannages et des problèmes connus. Pour plus d’informations sur les concepts et exemples de code ci-dessous, consultez le fichier lisez-moi du Kit de développement logiciel (SDK) Spring Data pour Azure Cosmos DB.

Politique de support des versions

Prise en charge des versions de Spring Boot

Ce projet prend en charge plusieurs versions de Spring Boot. Pour plus d’informations, consultez la stratégie de support Spring Boot. Les utilisateurs de Maven peuvent hériter du projet spring-boot-starter-parent pour obtenir une section de gestion des dépendances afin de permettre à Spring de gérer les versions des dépendances. Pour plus d’informations, consultez la prise en charge des versions de Spring Boot.

Prise en charge des versions de Spring Data

Ce projet prend en charge différentes versions courantes de Spring Data. Pour plus d’informations, consultez la prise en charge des versions de Spring Data.

Quelle version d’Azure Spring Data Azure Cosmos DB utiliser

La bibliothèque Azure Spring Data Azure Cosmos DB prend en charge plusieurs versions de Spring Boot / Spring Cloud. Pour plus d’informations sur la version d’Azure Spring Data Azure Cosmos DB à utiliser avec Spring Boot / Spring Cloud, consultez Quelle version d’Azure Spring Data pour Azure Cosmos DB dois-je utiliser ?.

Bien démarrer

Inclure le package

Si vous utilisez Maven, ajoutez la dépendance suivante.

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

Prérequis

  • Kit de développement Java (JDK), version 8 ou ultérieure.
  • Un compte Azure actif. Si vous n’en avez pas, vous pouvez vous inscrire pour bénéficier d’un compte gratuit. Vous pouvez également utiliser l’émulateur Azure Cosmos DB à des fins de développement et de test. Comme le certificat HTTPS de l’émulateur est auto-signé, vous devez importer son certificat dans le magasin de certificats approuvés Java, comme expliqué ici.
  • (Facultatif) SLF4J est une façade de journalisation.
  • (Facultatif) La liaison SLF4J est utilisée pour associer un framework de journalisation spécifique à SLF4J.
  • (Facultatif) Maven

SLF4J n’est nécessaire que si vous envisagez d’utiliser la journalisation. Téléchargez également une liaison SLF4J qui lie l’API SLF4J à l’implémentation de journalisation de votre choix. Pour plus d’informations, consultez le manuel de l’utilisateur SLF4J.

Configurer et personnaliser la classe de configuration

Pour configurer la classe de configuration, vous devez étendre AbstractCosmosConfiguration. Pour plus d’informations, consultez la classe de configuration d’installation.

Vous pouvez personnaliser le sous-jacent CosmosAsyncClient utilisé par le Kit de développement logiciel (SDK) Azure Spring Data Azure Cosmos DB en fournissant DirectConnectionConfig ou GatewayConnectionConfig à la fois et en les CosmosClientBuilderfournissant . Pour obtenir un exemple complet, consultez la section Personnalisation de la configuration.

Configuration d’entité

Vous pouvez définir une entité simple en tant qu’élément dans Azure Cosmos DB. Vous pouvez définir des entités en ajoutant l’annotation @Container et en spécifiant les propriétés associées au conteneur. Pour plus d’informations, consultez Définir une entité.

L’annotation de conteneur prend en charge la spécification du nom du conteneur, des unités de requête (RU), du temps de vie, de la création de conteneurs avec un débit de mise à l’échelle automatique, de la prise en charge de la clé de partition imbriquée et d’autres propriétés de conteneur.

Configuration du référentiel

Azure Spring Data Azure Cosmos DB prend en charge ReactiveCrudRepository (API asynchrones) et CrudRepository (API de synchronisation), qui fournissent les fonctionnalités CRUD de base suivantes :

  • save
  • findAll
  • findOne by ID
  • deleteAll
  • delete by ID
  • delete entity

Vous pouvez étendre CosmosRepository (pour la prise en charge de l’API de synchronisation) ou ReactiveCosmosRepository (pour la prise en charge de l’API asynchrone) pour configurer des référentiels Spring Data pour votre application. Pour plus d’informations, consultez Créer des référentiels.

Azure Spring Data Azure Cosmos DB prend en charge la spécification de requêtes annotées dans les référentiels à l’aide @Queryde . Pour plus d’informations, consultez QueryAnnotation : Utilisation de requêtes annotées dans des référentiels.

Annotations Spring Data

Annotation @Id Spring Data

Il existe plusieurs façons de mapper un champ dans la classe de domaine à id. Pour plus d’informations, consultez la section code d’annotation de l’ID de données spring.

Génération automatique d’ID

Azure Spring Data Azure Cosmos DB prend en charge la génération automatique d’ID à l’aide de l’annotation @GeneratedValue . Pour plus d’informations, consultez la section Génération automatique d’ID.

Expression SpEL et nom de conteneur personnalisé

Par défaut, le nom du conteneur est le nom de classe de la classe de domaine utilisateur. Pour personnaliser, ajoutez l’annotation @Container(containerName="myCustomContainerName") à la classe de domaine. Pour plus d’informations, consultez la section Relative à l’expression SpEL et au nom de conteneur personnalisé.

Custom IndexingPolicy

Par défaut, IndexingPolicy sera défini par le service Azure. Pour personnaliser, ajoutez l’annotation @CosmosIndexingPolicy à la classe de domaine. Pour plus d’informations, consultez la section de stratégie d’indexation.

Stratégie de clé unique

Azure Spring Data Azure Cosmos DB prend en charge la définition UniqueKeyPolicy sur le conteneur en ajoutant l’annotation @CosmosUniqueKeyPolicy à la classe de domaine. Pour plus d’informations, consultez la section stratégie de clé unique.

Partition Azure Cosmos DB

Azure-spring-data-cosmos prend en charge les partitions Azure Cosmos DB.

Pour spécifier un champ de la classe de domaine pour qu’il s’agit d’un champ de clé de partition, il vous suffit de l’annoter avec @PartitionKey.

Quand vous effectuez une opération CRUD, spécifiez la valeur de votre partition.

Pour plus d’informations, consultez la section test ici.

Verrouillage optimiste

Azure-spring-data-cosmos prend en charge le verrouillage optimiste pour des conteneurs spécifiques, ce qui signifie que les upserts/deletes par élément échouent avec une exception au cas où l’élément est modifié par un autre processus en attendant. Pour plus d’informations, consultez la section verrouillage optimiste.

Requête personnalisée Spring Data, pagination et tri

Azure-spring-data-cosmos prend en charge les requêtes personnalisées Spring Data, par exemple, une opération de recherche telle que findByAFieldAndBField. Il prend également en charge spring Data Pagable, Slice et Sort. Pour plus d’informations, consultez la section requête, paginable et tri.

Utilisation du Kit de développement logiciel (SDK) Java Azure Cosmos DB via Spring Data Cosmos

Azure-spring-data-cosmos prend en charge l’utilisation Azure Cosmos DB Java SDKde . Les utilisateurs peuvent obtenir ou âner CosmosClientApplicationContext et CosmosAsyncClient exécuter toutes les opérations prises en charge par le Kit de développement logiciel (SDK) Java Azure Cosmos DB. Pour plus d’informations, consultez la section Utilisation d’Azure Cosmos Client via Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos prend en charge SPRING Data REST. Pour plus d’informations, consultez la section API REST Azure Spring Data Azure Cosmos DB.

Audit

Azure-spring-data-cosmos prend en charge l’audit des champs sur les entités de base de données à l’aide d’annotations spring-data standard. Pour plus d’informations, consultez la section d’audit d’Azure Cosmos DB Spring Data.

Configuration de plusieurs bases de données

Azure-spring-data-cosmos prend en charge la configuration multi-base de données, notamment « plusieurs comptes de base de données » et « compte unique, avec plusieurs bases de données ». Pour obtenir un extrait de code complet, consultez la section configuration de plusieurs bases de données.

Dépannage

Général

Si vous rencontrez un bogue, créez un problème ici.

Pour suggérer une nouvelle fonctionnalité ou des modifications, signalez un problème comme vous le feriez pour un bogue.

Activer la journalisation du client

Azure-spring-data-cosmos utilise SLF4j comme façade de journalisation qui prend en charge la connexion dans des frameworks de journalisation populaires tels que log4j et logback. Pour plus d’informations, consultez la section Activer la journalisation des clients.

Exemples

Pour obtenir un exemple de projet complet, consultez l’exemple de projet.

Plusieurs comptes de base de données

Pour obtenir un exemple de projet complet, consultez l’exemple de projet multi-base de données.

Compte unique avec plusieurs bases de données

Pour obtenir un exemple de projet complet, consultez le compte unique avec l’exemple de projet multi-base de données.

Étapes suivantes

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Lorsque vous envoyez une demande de tirage( pull request), un bot CLA détermine automatiquement si vous devez fournir un CLA et décorer correctement la demande de tirage (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin d’effectuer cette opération qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions