Condividi tramite

Eseguire la migrazione dell'applicazione per usare Azure Cosmos DB Java SDK v4

  • Si applica a: ✅ NoSQL

Importante

Per altre informazioni su questo SDK, vedere le note sulla versione di Java SDK v4 di Azure Cosmos DB, il repository Maven, i suggerimenti sulle prestazioni di Java SDK v4 di Azure Cosmos DB e la guida alla risoluzione dei problemi di Java SDK v4 di Azure Cosmos DB.

Importante

Poiché Azure Cosmos DB Java SDK v4 ha fino a 20% velocità effettiva avanzata, modalità diretta basata su TCP e supporto per le funzionalità più recenti del servizio back-end, è consigliabile eseguire l'aggiornamento alla versione 4 alla successiva opportunità. Continuare a leggere di seguito per altre informazioni.

Esegui l'aggiornamento all'SDK Java più recente di Azure Cosmos DB per ottenere il meglio di ciò che ha da offrire, ovvero un servizio di database non relazionale gestito con prestazioni competitive, un'elevata disponibilità del 99,999%, una governance delle risorse unica nel suo genere e altro ancora. Questo articolo illustra come aggiornare l'applicazione Java esistente che usa un SDK Java di Azure Cosmos DB precedente alla versione più recente di Azure Cosmos DB Java SDK 4.0 per l'API per NoSQL. Azure Cosmos DB Java SDK v4 corrisponde al com.azure.cosmos pacchetto. È possibile usare le istruzioni in questo documento se si esegue la migrazione dell'applicazione da uno degli SDK Java di Azure Cosmos DB seguenti:

  • Sincronizzare Java SDK 2.x.x
  • Async Java SDK 2.x.x
  • Java SDK 3.x.x

Mapping dei pacchetti e di Java SDK di Azure Cosmos DB

La tabella seguente elenca diversi SDK Java di Azure Cosmos DB, il nome del pacchetto e le informazioni sulla versione:

Java SDK Data di rilascio API raggruppate Maven Jar Nome pacchetto Java Informazioni di riferimento sulle API Note di rilascio Data di ritiro
Async 2.x.x 2018 giugno Async(RxJava) com.microsoft.azure::azure-cosmosdb com.microsoft.azure.cosmosdb.rx api note di rilascio 31 agosto 2024
Sync 2.x.x Settembre 2018 Sincronizzazione com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb api 29 febbraio 2024
3.x.x Luglio 2019 Async(Reactor)/Sync com.microsoft.azure::azure-cosmos com.azure.data.cosmos api - 31 agosto 2024
4.0 Giugno 2020 Async(Reactor)/Sync com.azure::azure-cosmos com.azure.cosmos api - -

Modifiche all'implementazione a livello di SDK

Di seguito sono riportate le principali differenze di implementazione tra diversi SDK:

RxJava viene sostituito con Reactor nelle versioni 3.x.x e 4.0 di Azure Cosmos DB Java SDK.

Se non si ha familiarità con la programmazione asincrona o la programmazione reattiva, vedere la guida al modello Reactor per un'introduzione alla programmazione asincrona e a Project Reactor. Questa guida può essere utile se si usa Azure Cosmos DB Sync Java SDK 2.x.x o l'API di sincronizzazione Java SDK 3.x.x di Azure Cosmos DB in passato.

Se si usa Azure Cosmos DB Async Java SDK 2.x.x e si prevede di eseguire la migrazione all'SDK 4.0, vedere la Guida a Reactor vs RxJava per indicazioni sulla conversione del codice RxJava per l'uso di Reactor.

Azure Cosmos DB Java SDK v4 ha la modalità di connettività diretta nelle API Async e Sync

Se si usa Azure Cosmos DB Sync Java SDK 2.x.x, si noti che la modalità di connessione diretta basata su TCP (anziché HTTP) viene implementata in Azure Cosmos DB Java SDK 4.0 per le API Async e Sync.

Modifiche a livello di API

Di seguito sono riportate le modifiche a livello di API in Azure Cosmos DB Java SDK 4.x.x rispetto agli SDK precedenti (Java SDK 3.x.x, Async Java SDK 2.x.x e Sync Java SDK 2.x.x):

Convenzioni di denominazione di Java SDK per Azure Cosmos DB

  • Azure Cosmos DB Java SDK 3.x.x e 4.0 fanno riferimento alle risorse client come Cosmos<resourceName>. Ad esempio, CosmosClient, CosmosDatabase, CosmosContainer. Mentre nella versione 2.x.x, gli SDK Java di Azure Cosmos DB non hanno uno schema di denominazione uniforme.

  • Azure Cosmos DB Java SDK 3.x.x e 4.0 offrono api di sincronizzazione e asincrone.

    • Java SDK 4.0 : tutte le classi appartengono all'API di sincronizzazione, a meno che il nome della classe non venga aggiunto dopo AsyncCosmos.

    • Java SDK 3.x.x: tutte le classi appartengono all'API asincrona, a meno che il nome della classe non venga aggiunto dopo AsyncCosmos.

    • Async Java SDK 2.x.x: i nomi delle classi sono simili a Sync Java SDK 2.x.x, ma il nome inizia con Async.

Struttura dell'API gerarchica

Azure Cosmos DB Java SDK 4.0 e 3.x.x introducono una struttura di API gerarchica che organizza i client, i database e i contenitori in modo annidato, come illustrato nel frammento di codice SDK 4.0 seguente:

CosmosContainer container = client.getDatabase("MyDatabaseName").getContainer("MyContainerName");

Nella versione 2.x.x di Azure Cosmos DB Java SDK tutte le operazioni su risorse e documenti vengono eseguite tramite l'istanza client.

Rappresentazione di documenti

In Azure Cosmos DB Java SDK 4.0, i POJO personalizzati e JsonNodes sono le due opzioni per leggere e scrivere i documenti da Azure Cosmos DB.

In Azure Cosmos DB Java SDK 3.x.x l'oggetto CosmosItemProperties viene esposto dall'API pubblica e servito come rappresentazione del documento. Questa classe non viene più esposta pubblicamente nella versione 4.0.

Importazioni

  • I pacchetti Java SDK 4.0 di Azure Cosmos DB iniziano con com.azure.cosmos

  • I pacchetti Java SDK 3.x.x di Azure Cosmos DB iniziano con com.azure.data.cosmos

  • I pacchetti api di sincronizzazione di Azure Cosmos DB Java SDK 2.x.x iniziano con com.microsoft.azure.documentdb

  • Azure Cosmos DB Java SDK 4.0 inserisce diverse classi in un pacchetto com.azure.cosmos.modelsannidato. Alcuni di questi pacchetti includono:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • Analogie dell'API asincrona per tutti i pacchetti precedenti
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... and so on.

Accessors

Azure Cosmos DB Java SDK 4.0 espone get e set metodi per accedere ai membri dell'istanza. Ad esempio, l'istanza CosmosContainer dispone dei metodi container.getId() e container.setId().

Questo è diverso da Azure Cosmos DB Java SDK 3.x.x che espone un'interfaccia Fluent. Ad esempio, un'istanza di CosmosSyncContainer ha un metodo container.id() sovraccaricato per ottenere o impostare il valore di id.

Gestione dei conflitti di dipendenza

L'aggiornamento da Azure Cosmos DB Java SDK V2 a V4 può introdurre conflitti di dipendenza a causa delle modifiche apportate alle librerie usate dall'SDK. La risoluzione di questi conflitti richiede un'attenta gestione delle dipendenze.

  1. Informazioni sulle nuove dipendenze: Azure Cosmos DB V4 SDK ha un proprio set di dipendenze che potrebbero essere diverse da quelle nelle versioni precedenti. Assicurarsi di conoscere queste dipendenze:

    • azure-cosmos
    • reactor-core
    • reactor-netty
    • netty-handler
    • guava
    • slf4j-api
    • jackson-databind
    • jackson-annotations
    • jackson-core
    • commons-lang3
    • commons-collections4
    • azure-core
    • azure-core-http-netty

  2. Rimuovi dipendenze in conflitto: iniziare rimuovendo le dipendenze correlate alle versioni precedenti dell'SDK dal pom.xml file. Questi includono azure-cosmosdb e eventuali dipendenze transitive che l'SDK precedente avrebbe potuto avere.

  3. Aggiungere le dipendenze dell'SDK V4: aggiungere l'SDK V4 e le relative dipendenze a pom.xml. Ecco un esempio:

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.x.x</version> <!-- Use the latest version available -->
</dependency>

  4. Verificare la presenza di conflitti di dipendenza: usare il comando Maven dependency:tree per generare un albero delle dipendenze e identificare eventuali conflitti. Corri!

    mvn dependency:tree

    Cercare eventuali versioni in conflitto delle dipendenze. Questi conflitti si verificano spesso con librerie come reactor-core, netty-handler, guavae jackson.

  5. Usare la gestione delle dipendenze: Nel caso in cui si verifichino conflitti di versione, potrebbe essere necessario eseguire l'override delle versioni problematiche usando la sezione <dependencyManagement> nel pom.xml. Ecco un esempio per applicare una versione specifica di reactor-core:

    <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-core</artifactId>
            <version>3.x.x</version> <!-- Use a compatible version -->
        </dependency>
        <!-- Repeat for any other conflicting dependencies -->
    </dependencies>
</dependencyManagement>

  6. Escludi dipendenze transitive: a volte potrebbe essere necessario escludere dipendenze transitive causate da altre dipendenze. Ad esempio, se un'altra libreria inserisce una versione precedente di una dipendenza in conflitto, è possibile escluderla come segue:

    <dependency>
    <groupId>some.group</groupId>
    <artifactId>some-artifact</artifactId>
    <version>x.x.x</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting.group</groupId>
            <artifactId>conflicting-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

  7. Ricompilare e testare: dopo aver apportato queste modifiche, ricompilare il progetto e testarlo accuratamente per assicurarsi che le nuove dipendenze funzionino correttamente e che non si verifichino conflitti di runtime.

Confronti tra frammenti di codice

Creare le risorse

Il frammento di codice seguente illustra le differenze di creazione delle risorse tra le API Async 4.0, 3.x.xsync, 2.x.x Sync e 2.x.x Async:


// Create Async client.
// Building an async client is still a sync operation.
CosmosAsyncClient client = new CosmosClientBuilder()
        .endpoint("your.hostname")
        .key("yourmasterkey")
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildAsyncClient();

// Create database with specified name
client.createDatabaseIfNotExists("YourDatabaseName")
        .flatMap(databaseResponse -> {
            testDatabaseAsync = client.getDatabase("YourDatabaseName");
            // Container properties - name and partition key
            CosmosContainerProperties containerProperties =
                    new CosmosContainerProperties("YourContainerName", "/id");

            // Provision manual throughput
            ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

            // Create container
            return database.createContainerIfNotExists(containerProperties, throughputProperties);
        }).flatMap(containerResponse -> {
    testContainerAsync = database.getContainer("YourContainerName");
    return Mono.empty();
}).subscribe();

Operazioni sugli elementi

Il frammento di codice seguente illustra le differenze nell'esecuzione delle operazioni sugli elementi tra le API 4.0 Async, 3.x.x Async, 2.x.x Sync e 2.x.x Async:


// Container is created. Generate many docs to insert.
int number_of_docs = 50000;
ArrayList<JsonNode> docs = generateManyDocs(number_of_docs);

// Insert many docs into container...
Flux.fromIterable(docs)
        .flatMap(doc -> testContainerAsync.createItem(doc))
        .subscribe(); // ...Subscribing triggers stream execution.

Indicizzazione

Il frammento di codice seguente mostra le differenze nella creazione dell'indicizzazione tra le API 4.0 asincrone, 3.x.x asincrone, 2.x.x sincrone e 2.x.x asincrone.


CosmosContainerProperties containerProperties = new CosmosContainerProperties(containerName, "/lastName");

// Custom indexing policy
IndexingPolicy indexingPolicy = new IndexingPolicy();
indexingPolicy.setIndexingMode(IndexingMode.CONSISTENT);

// Included paths
List<IncludedPath> includedPaths = new ArrayList<>();
includedPaths.add(new IncludedPath("/*"));
indexingPolicy.setIncludedPaths(includedPaths);

// Excluded paths
List<ExcludedPath> excludedPaths = new ArrayList<>();
excludedPaths.add(new ExcludedPath("/name/*"));
indexingPolicy.setExcludedPaths(excludedPaths);

containerProperties.setIndexingPolicy(indexingPolicy);

ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

database.createContainerIfNotExists(containerProperties, throughputProperties);
CosmosAsyncContainer containerIfNotExists = database.getContainer(containerName);

Procedure memorizzate

Il frammento di codice seguente illustra le differenze nella creazione delle stored procedure tra le API Async 4.0, 3.x.x Sync, 2.x.x Sync e 2.x.x Async.


logger.info("Creating stored procedure...\n");

String sprocId = "createMyDocument";

String sprocBody = "function createMyDocument() {\n" +
        "var documentToCreate = {\"id\":\"test_doc\"}\n" +
        "var context = getContext();\n" +
        "var collection = context.getCollection();\n" +
        "var accepted = collection.createDocument(collection.getSelfLink(), documentToCreate,\n" +
        "    function (err, documentCreated) {\n" +
        "if (err) throw new Error('Error' + err.message);\n" +
        "context.getResponse().setBody(documentCreated.id)\n" +
        "});\n" +
        "if (!accepted) return;\n" +
        "}";

CosmosStoredProcedureProperties storedProcedureDef = new CosmosStoredProcedureProperties(sprocId, sprocBody);
container.getScripts()
        .createStoredProcedure(storedProcedureDef,
                new CosmosStoredProcedureRequestOptions()).block();

// ...

logger.info(String.format("Executing stored procedure %s...\n\n", sprocId));

CosmosStoredProcedureRequestOptions options = new CosmosStoredProcedureRequestOptions();
options.setPartitionKey(new PartitionKey("test_doc"));

container.getScripts()
        .getStoredProcedure(sprocId)
        .execute(null, options)
        .flatMap(executeResponse -> {
            logger.info(String.format("Stored procedure %s returned %s (HTTP %d), at cost %.3f RU.\n",
                    sprocId,
                    executeResponse.getResponseAsString(),
                    executeResponse.getStatusCode(),
                    executeResponse.getRequestCharge()));
            return Mono.empty();
        }).block();

Feed di modifiche

Il frammento di codice seguente mostra le differenze di esecuzione delle operazioni del change feed tra le API asincrone 4.0 e 3.x.x.


ChangeFeedProcessor changeFeedProcessorInstance =
        new ChangeFeedProcessorBuilder()
                .hostName(hostName)
                .feedContainer(feedContainer)
                .leaseContainer(leaseContainer)
                .handleChanges((List<JsonNode> docs) -> {
                    logger.info("--->setHandleChanges() START");

                    for (JsonNode document : docs) {
                        try {
                            //Change Feed hands the document to you in the form of a JsonNode
                            //As a developer you have two options for handling the JsonNode document provided to you by Change Feed
                            //One option is to operate on the document in the form of a JsonNode, as shown below. This is great
                            //especially if you do not have a single uniform data model for all documents.
                            logger.info("---->DOCUMENT RECEIVED: " + OBJECT_MAPPER.writerWithDefaultPrettyPrinter()
                                    .writeValueAsString(document));

                            //You can also transform the JsonNode to a POJO having the same structure as the JsonNode,
                            //as shown below. Then you can operate on the POJO.
                            CustomPOJO pojo_doc = OBJECT_MAPPER.treeToValue(document, CustomPOJO.class);
                            logger.info("----=>id: " + pojo_doc.getId());

                        } catch (JsonProcessingException e) {
                            e.printStackTrace();
                        }
                    }
                    logger.info("--->handleChanges() END");

                })
                .buildChangeFeedProcessor();

// ...

changeFeedProcessorInstance.start()
        .subscribeOn(Schedulers.boundedElastic())
        .subscribe();

Durata di vita del contenitore (TTL)

Il frammento di codice seguente illustra le differenze su come creare il tempo di vita per i dati nel contenitore tra le API 4.0, 3.x.x Async, 2.x.x Sync e 2.x.x Async:


CosmosAsyncContainer container;

// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);
database.createContainerIfNotExists(containerProperties, throughputProperties).block();
container = database.getContainer("myContainer");

Tempo di vita (TTL) per livello di elemento

Il frammento di codice seguente illustra le differenze nel modo di creare il tempo di vita per un elemento tra le API asincrone 4.0, 3.x.x asincrone, 2.x.x sincrone e 2.x.x asincrone.


// Include a property that serializes to "ttl" in JSON
class SalesOrder
{
    private String id;
    private String customerId;
    private Integer ttl;

    public SalesOrder(String id, String customerId, Integer ttl) {
        this.id = id;
        this.customerId = customerId;
        this.ttl = ttl;
    }

    public String getId() {return this.id;}
    public void setId(String new_id) {this.id = new_id;}
    public String getCustomerId() {return this.customerId;}
    public void setCustomerId(String new_cid) {this.customerId = new_cid;}
    public Integer getTtl() {return this.ttl;}
    public void setTtl(Integer new_ttl) {this.ttl = new_ttl;}

    //...
}



// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
        "SO05",
        "CO18009186470",
        60 * 60 * 24 * 30  // Expire sales orders in 30 days
);

Passaggi successivi

  • Last updated on