Compartilhar via

Migrar seu aplicativo para usar o SDK do Java do Azure Cosmos DB v4

  • Aplica-se a: ✅ NoSQL

Importante

Para obter mais informações sobre esse SDK, veja as notas de versão do SDK do Java do Azure Cosmos DB v4, o repositório Maven, as dicas de desempenho do SDK do Java do Azure Cosmos DB v4 e o guia de solução de problemas do SDK do Java v4 do Azure Cosmos DB.

Importante

Como o SDK do Java v4 do Azure Cosmos DB tem até 20% taxa de transferência aprimorada, modo direto baseado em TCP e suporte para os recursos mais recentes do serviço de back-end, recomendamos que você atualize para v4 na próxima oportunidade. Continue lendo abaixo para saber mais.

Atualize para o SDK Java do Azure Cosmos DB mais recente para obter o melhor do que o Azure Cosmos DB tem a oferecer: um serviço de banco de dados não relacional gerenciado com desempenho competitivo, disponibilidade de 99,999%, governança de recursos exclusiva e muito mais. Este artigo explica como atualizar seu aplicativo Java existente que está usando um SDK Java do Azure Cosmos DB mais antigo para o SDK java 4.0 do Azure Cosmos DB mais recente para a API para NoSQL. O SDK do Java v4 do Azure Cosmos DB corresponde ao pacote com.azure.cosmos. Você pode usar as instruções neste documento se estiver migrando seu aplicativo de qualquer um dos seguintes SDKs java do Azure Cosmos DB:

  • Sincronizar o SDK do Java 2.x.x
  • Java Async SDK 2.x.x
  • SDK do Java 3.x.x

Mapeamentos de pacotes e SDKs Java do Azure Cosmos DB

A tabela a seguir lista diferentes SDKs java do Azure Cosmos DB, o nome do pacote e as informações de versão:

Java SDK Data de lançamento APIs agrupadas Maven Jar Nome do pacote Java Referência de API Notas de Lançamento Data de aposentadoria
Async 2.x.x Junho de 2018 Async(RxJava) com.microsoft.azure::azure-cosmosdb com.microsoft.azure.cosmosdb.rx API Notas de versão 31 de agosto de 2024
Sync 2.x.x Setembro de 2018 Sincronizar com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API 29 de fevereiro de 2024
3.x.x Julho de 2019 Async(Reactor)/Sync com.microsoft.azure::azure-cosmos com.azure.data.cosmos API - 31 de agosto de 2024
4,0 Junho de 2020 Async(Reactor)/Sync com.azure::azure-cosmos com.azure.cosmos API - -

Alterações de implementação no nível do SDK

Veja a seguir as principais diferenças de implementação entre diferentes SDKs:

RxJava é substituído por Reactor no SDK do Azure Cosmos DB Java, versões 3.x.x e 4.0.

Se você não estiver familiarizado com programação assíncrona ou Programação Reativa, consulte o guia de padrão do Reator para obter uma introdução à programação assíncrona e ao Project Reactor. Este guia poderá ser útil se você tinha usado o SDK Java do Azure Cosmos DB 2.x.x ou API Sync do SDK Java do Azure Cosmos DB 3.x.x no passado.

Se você estiver usando o SDK do Java Assíncrono do Azure Cosmos DB 2.x.x e planeja migrar para o SDK 4.0, consulte o Guia do Reator vs RxJava para obter orientação sobre como converter o código RxJava para usar o Reator.

O SDK do Java v4 do Azure Cosmos DB tem modo de conectividade direta nas APIs Async e Sync

Se você estiver usando o SDK java de sincronização do Azure Cosmos DB 2.x.x, observe que o modo de conexão direta baseado em TCP (em oposição a HTTP) é implementado no SDK java do Azure Cosmos DB 4.0 para as APIs assíncronas e de Sincronização.

Alterações no nível da API

Veja a seguir as alterações no nível de API no SDK Java do Azure Cosmos DB 4.x.x em comparação com os SDKs anteriores (SDK Java 3.x.x, SDK Java assíncrono 2.x.x e SDK Java síncrono 2.x.x):

Convenções de nomenclatura do SDK do Java do Azure Cosmos DB

  • O SDK java do Azure Cosmos DB 3.x.x e 4.0 referem os recursos do cliente como Cosmos<resourceName>. Por exemplo, CosmosClient, , CosmosDatabaseCosmosContainer. Enquanto na versão 2.x.x, os SDKs java do Azure Cosmos DB não têm um esquema de nomenclatura uniforme.

  • O SDK Java do Azure Cosmos DB 3.x.x e 4.0 oferece APIs Síncrona e Assíncrona.

    • SDK do Java 4.0 : todas as classes pertencem à API de Sincronização, a menos que o nome da classe seja acrescentado com Async depois Cosmos.

    • SDK do Java 3.x.x: todas as classes pertencem à API Assíncrona, a menos que o nome da classe seja acrescentado com Async depois Cosmos.

    • Async Java SDK 2.x.x: os nomes de classe são semelhantes aos do Sync Java SDK 2.x.x, no entanto, o nome começa com Async.

Estrutura de API hierárquica

O SDK java do Azure Cosmos DB 4.0 e 3.x.x introduzem uma estrutura de API hierárquica que organiza os clientes, bancos de dados e contêineres de forma aninhada, conforme mostrado no seguinte snippet de código do SDK 4.0:

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

Na versão 2.x.x do SDK do Java do Azure Cosmos DB, todas as operações em recursos e documentos são executadas por meio da instância do cliente.

Representando documentos

No Azure Cosmos DB Java SDK 4.0, POJOs personalizados e JsonNodes são as duas opções para ler e gravar os documentos do Azure Cosmos DB.

No SDK java do Azure Cosmos DB 3.x.x, o CosmosItemProperties objeto é exposto pela API pública e servido como uma representação de documento. Essa classe não é mais exposta publicamente na versão 4.0.

Importações

  • Os pacotes do SDK 4.0 do Java do Azure Cosmos DB começam com com.azure.cosmos

  • Os pacotes do SDK 3.x.x do Java do Azure Cosmos DB começam com com.azure.data.cosmos

  • Os pacotes da API de Sincronização do SDK do Java do Azure Cosmos DB 2.x.x começam com com.microsoft.azure.documentdb

  • O SDK Java 4.0 do Azure Cosmos DB coloca várias classes dentro de um pacote com.azure.cosmos.models aninhado. Alguns desses pacotes incluem:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • Os análogos da Async API para todos os pacotes mencionados acima.
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... Etc.

Accessors

O Azure Cosmos DB Java SDK 4.0 expõe os métodos get e set para acessar os membros da instância. Por exemplo, a CosmosContainer instância tem container.getId() e container.setId() métodos.

Isso é diferente do SDK do Java do Azure Cosmos DB 3.x.x, que expõe uma interface fluente. Por exemplo, uma CosmosSyncContainer instância tem container.id() que está sobrecarregada para obter ou definir o id valor.

Gerenciando conflitos de dependência

A atualização do Azure Cosmos DB Java SDK V2 para V4 pode introduzir conflitos de dependência devido a alterações nas bibliotecas do SDK. Resolver esses conflitos requer um gerenciamento cuidadoso das dependências.

  1. Entenda as Novas Dependências: o SDK do Azure Cosmos DB V4 tem seu próprio conjunto de dependências que podem ser diferentes daquelas em versões anteriores. Verifique se você está ciente dessas dependências:

    • 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. Remover dependências conflitantes: comece removendo as dependências relacionadas a versões anteriores do SDK do arquivo pom.xml . Elas incluem azure-cosmosdb e quaisquer dependências transitivas que o SDK antigo possa ter tido.

  3. Adicionar dependências do SDK V4: adicione o SDK V4 e suas dependências ao seu pom.xml. Veja um exemplo:

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

  4. Verifique se há conflitos de dependência: use o comando Maven dependency:tree para gerar uma árvore de dependência e identificar quaisquer conflitos. Correr:

    mvn dependency:tree

    Procure versões conflitantes de dependências. Esses conflitos geralmente ocorrem com bibliotecas como reactor-core, netty-handlere guavajackson.

  5. Usar o Gerenciamento de Dependências: se você encontrar conflitos de versão, talvez seja necessário substituir versões problemáticas usando a <dependencyManagement> seção em seu pom.xml. Aqui está um exemplo para impor uma versão específica de 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. Excluir dependências transitivas: às vezes, talvez seja necessário excluir dependências transitivas trazidas por outras dependências. Por exemplo, se outra biblioteca trouxer uma versão mais antiga de uma dependência em conflito, você poderá excluí-la assim:

    <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. Recompilar e testar: depois de fazer essas alterações, recompile seu projeto e teste-o minuciosamente para garantir que as novas dependências funcionem corretamente e que não ocorram conflitos de runtime.

Comparações de trechos de código

Criar recursos

O trecho de código a seguir mostra as diferenças na forma como os recursos são criados entre as APIs 4.0, 3.x.x assíncronas, 2.x.x síncronas e 2.x.x assíncronas.


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

Operações de item

O trecho de código a seguir mostra as diferenças na forma como as operações com itens são executadas entre as APIs 4.0, 3.x.x Assíncronas, 2.x.x Síncronas e 2.x.x Assíncronas.


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

Indexação

O trecho de código a seguir mostra as diferenças na forma como a indexação é criada entre as APIs Assíncronas 4.0, 3.x.x, Sincronas 2.x.x e Assíncronas 2.x.x:


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

Procedimentos armazenados

O snippet de código a seguir mostra as diferenças na forma como os procedimentos armazenados são criados entre as APIs 4.0 Assíncrona, 3.x.x Assíncrona, 2.x.x Síncrona e 2.x.x Assíncrona:


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 de alteração

O trecho de código a seguir mostra as diferenças em como as operações de fluxo de alterações são executadas entre as versões 4.0 e 3.x.x das APIs assíncronas:


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

TTL (vida útil) no nível do contêiner

O snippet de código a seguir mostra as diferenças em como definir o tempo de vida para dados no contêiner entre as APIs 4.0 Assíncrona, 3.x.x Assíncrona, 2.x.x Sincrona e 2.x.x Assíncrona:


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

TTL (vida útil) no nível do item

O snippet de código a seguir mostra as diferenças de como criar tempo de vida para um item entre as APIs 4.0 Assíncrona, 3.x.x Assíncrona, 2.x.x Síncrona e 2.x.x Assíncrona:


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

Próximas etapas

  • Last updated on