Bibliothèque de client Azure Cosmos DB pour Java - version 4.52.0

  • Article

Azure Cosmos DB est un service Microsoft de base de données multimodèle distribué dans le monde entier destiné aux charges de travail opérationnelles et analytiques. Il offre une fonctionnalité multimaître en mettant automatiquement à l’échelle le débit, le calcul et le stockage. Ce projet fournit une bibliothèque sdk en Java pour interagir avec l’API SQLd’Azure Cosmos DB Database Service.

| Code sourcePackage (Maven) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version ga de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<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>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit. // : # ({x-version-update-start ; com.azure :azure-cosmos ; current})

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

Reportez-vous à maven Central pour connaître les versions précédentes

Pour plus d’informations sur le package, consultez javadocs .

Prérequis

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.

Le Kit de développement logiciel (SDK) fournit des API asynchrones basées sur Reactor Core. Vous pouvez en savoir plus sur les types Core et Flux/Mono de réacteur ici

Authentifier le client

Pour interagir avec le service Azure Cosmos DB, vous devez créer un instance de la classe Cosmos Client. Pour ce faire, vous aurez besoin d’une URL et d’une clé du service Azure Cosmos DB.

Le Kit de développement logiciel (SDK) fournit deux clients.

  1. CosmosAsyncClient pour les opérations utilisant des API asynchrones.
  2. CosmosClient pour les opérations utilisant des API synchrones (bloquantes).

Créer CosmosAsyncClient

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

Créer CosmosClient

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

Concepts clés

Le SDK Java Azure Cosmos DB fournit une représentation logique côté client pour accéder à l’API SQL Azure Cosmos DB. Un compte Cosmos DB contient zéro ou plusieurs bases de données, une base de données (DB) contient zéro ou plusieurs conteneurs et un conteneur contient zéro ou plusieurs éléments. Vous pouvez en savoir plus sur les bases de données, les conteneurs et les éléments ici. Quelques propriétés importantes définies au niveau du conteneur, parmi elles, sont le débit approvisionné et la clé de partition.

Diffusion mondiale

  • Azure Cosmos DB est un service de base de données distribué au niveau mondial conçu pour offrir une faible latence, une évolutivité élastique du débit, une sémantique bien définie pour la cohérence des données et une haute disponibilité. En résumé, si votre application a besoin d’un temps de réponse rapide garanti partout dans le monde, si elle a besoin d’être toujours en ligne et a besoin d’une évolutivité illimitée et élastique du débit et du stockage, nous vous conseillons de développer votre application sur Azure Cosmos DB. Vous pouvez en savoir plus sur la distribution mondiale ici.

Provisionnement du débit

  • Azure Cosmos DB vous permet de définir le débit approvisionné sur vos bases de données et conteneurs. Il existe deux types de débit approvisionné, standard (manuel) ou avec mise à l’échelle automatique. Vous pouvez choisir un débit provisionné par conteneur ou par base de données. Toutefois, il est généralement préférable de spécifier le débit au niveau du conteneur. Vous pouvez en savoir plus sur l’approvisionnement de débit ici.

Unités de requête (RU)

  • Azure Cosmos DB prend en charge de nombreuses API, notamment SQL, MongoDB, Cassandra, Gremlin et Table. Chaque API possède son propre ensemble d’opérations de base de données, qui vont de simples opérations ponctuelles de lecture et d'écriture à des requêtes complexes. Chaque opération de base de données consomme des ressources système en fonction de sa complexité. Le coût de toutes les opérations de base de données, normalisé par Azure Cosmos DB, est exprimé en unités de requête (RU). Vous pouvez considérer les RU/s comme la devise du débit, qui dépend de la vitesse. Elles représentent une abstraction des ressources système (processeur, IOPS et mémoire, notamment) nécessaires pour effectuer les opérations de base de données prises en charge par Azure Cosmos DB. Vous pouvez en savoir plus sur les unités de requête ici.

Partitionnement

  • À mesure que des éléments sont insérés dans un conteneur Cosmos DB, la base de données croît horizontalement : les capacités de stockage et de calcul augmentent pour assurer le traitement des requêtes. Les capacités de stockage et de calcul sont ajoutées par unités séparées appelées partitions. Vous devez choisir dans vos documents un champ qui sera la clé de partition qui mappe chaque document à une partition. Les partitions sont gérées de la façon suivante : à chaque partition est attribuée une section relativement équivalente de la plage de valeurs de clé de partition. Il est donc recommandé de choisir une clé de partition relativement aléatoire ou distribuée uniformément. Dans le cas contraire, un plus grand nombre de requêtes sera adressé à certaines partitions (partitions à chaud) et un nombre de requêtes sensiblement inférieur sera adressé à d’autres partitions (partitions à froid). Cette situation doit être évitée. Pour en savoir plus sur le partitionnement, consultez cette page.

Exemples

La section suivante fournit plusieurs extraits de code couvrant certaines des tâches les plus courantes de l’API SQL Cosmos DB, notamment :

Créer un client 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();

Créer une base de données

À l’aide de l’un des clients créés dans l’exemple précédent, vous pouvez créer une base de données comme suit :

// 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()));

Create Container

À l’aide de la base de données créée ci-dessus, vous pouvez lui chaîner une autre opération pour créer un conteneur comme suit :

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()));

Opération CRUD sur les éléments

// 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)
// ...

Nous avons un exemple d’application de prise en main disponible ici.

En outre, nous avons d’autres exemples de projet d’exemples.

Dépannage

Général

Azure Cosmos DB est une base de données distribuée rapide et flexible qui peut être mise à l’échelle en toute transparence avec une latence et un débit garantis. Vous n’avez pas à apporter de modifications d’architecture majeures ou écrire de code complexe pour mettre à l’échelle votre base de données avec Azure Cosmos DB. La réduction et l’augmentation de l’échelle est aussi simple que le passage d’un appel d’API ou de Kit de développement logiciel (SDK). Toutefois, étant donné qu’Azure Cosmos DB est accessible au moyen d’appels réseau, vous pouvez apporter des optimisations côté client de manière à atteindre des performances de pointe quand vous utilisez le SDK Java v4 Azure Cosmos DB.

  • Le Guide des performances couvre ces optimisations côté client.

  • Le guide de résolution des problèmes décrit les problèmes courants, les solutions de contournement, les étapes de diagnostic et les outils lorsque vous utilisez le SDK Java Azure Cosmos DB v4 avec des comptes d’API SQL Azure Cosmos DB.

Activer la journalisation du client

Le kit SDK Java v4 Azure Cosmos DB utilise SLF4j comme façade de journalisation prenant en charge la journalisation dans les frameworks de journalisation populaires tels que log4j et logback.

Par exemple, si vous souhaitez utiliser log4j en tant que framework de journalisation, ajoutez les bibliothèques suivantes dans votre chemin de classe Java.

<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>

Ajoutez également une configuration 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

É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.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat 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