Aracılığıyla paylaş

Uygulamanızı Azure Cosmos DB Java SDK v4 kullanacak şekilde geçirme

  • Şunlara uygulanır: ✅ NoSQL

Önemli

Bu SDK hakkında daha fazla bilgi için lütfen Azure Cosmos DB Java SDK v4 Sürüm notları, Maven deposu, Azure Cosmos DB Java SDK v4 performans ipuçları ve Azure Cosmos DB Java SDK v4 sorun giderme kılavuzunu görüntüleyin.

Önemli

Azure Cosmos DB Java SDK v4'te en fazla 20% gelişmiş aktarım hızı, TCP tabanlı doğrudan mod ve en son arka uç hizmeti özellikleri desteği olduğundan, bir sonraki fırsatta v4'e yükseltmenizi öneririz. Daha fazla bilgi edinmek için aşağıdaki okumaya devam edin.

Azure Cosmos DB'nin sunduğu en iyi hizmetlerden yararlanmak için en son Azure Cosmos DB Java SDK'sını güncelleyin - rekabetçi performans sunan yönetilen bir ilişkisel olmayan veritabanı hizmeti, 99.999% kullanılabilirlik, türünün tek örneği kaynak yönetimi ve daha fazlası. Bu makalede, eski bir Azure Cosmos DB Java SDK'sını kullanan mevcut Java uygulamanızı NoSQL için API için daha yeni Azure Cosmos DB Java SDK 4.0'a yükseltme işlemi açıklanmaktadır. Azure Cosmos DB Java SDK v4 paketine com.azure.cosmos karşılık gelir. Uygulamanızı aşağıdaki Azure Cosmos DB Java SDK'larından herhangi birinden geçiriyorsanız bu belgedeki yönergeleri kullanabilirsiniz:

  • Java SDK 2.x.x'i eşitleme
  • Async Java SDK 2.x.x
  • Java SDK 3.x.x

Azure Cosmos DB Java SDK'ları ve paket eşlemeleri

Aşağıdaki tabloda farklı Azure Cosmos DB Java SDK'ları, paket adı ve sürüm bilgileri listelenmiştir:

Java SDK'sı Yayımlama Tarihi Paketlenmiş API'ler Maven Jar Java paket adı API Referansı Sürüm Notları Kullanımdan kaldırma tarihi
Asenkron 2.x.x 2018 Haziran Async(RxJava) com.microsoft.azure::azure-cosmosdb com.microsoft.azure.cosmosdb.rx API Sürüm Notları 31 Ağustos 2024 Cumartesi
Senkronizasyon 2.x.x Eylül 2018 Senkronizasyon com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API 29 Şubat 2024
3.x.x Temmuz 2019 Async(Reactor)/Sync com.microsoft.azure::azure-cosmos com.azure.data.cosmos API - 31 Ağustos 2024 Cumartesi
4,0 Haziran 2020 Async(Reactor)/Sync com.azure::azure-cosmos com.azure.cosmos API - -

SDK düzeyinde uygulama değişiklikleri

Farklı SDK'lar arasındaki temel uygulama farklılıkları şunlardır:

RxJava, Azure Cosmos DB Java SDK'sı 3.x.x ve 4.0 sürümlerinde reaktörle değiştirildi

Zaman uyumsuz programlama veya Reaktif Programlama hakkında bilginiz yoksa, zaman uyumsuz programlamaya ve Project Reactor'a giriş için Reactor desen kılavuzuna bakın. Bu kılavuz, geçmişte Azure Cosmos DB Sync Java SDK 2.x.x veya Azure Cosmos DB Java SDK 3.x.x Eşitleme API'sini kullanıyorsanız yararlı olabilir.

Azure Cosmos DB Async Java SDK 2.x.x kullanıyorsanız ve 4.0 SDK'sına geçiş yapmayı planlıyorsanız RxJava kodunu Reactor'ı kullanacak şekilde dönüştürme yönergeleri için Reactor vs RxJava Kılavuzu'na bakın.

Azure Cosmos DB Java SDK v4, hem Asenkron hem de Senkron API'lerinde doğrudan bağlantı moduna sahiptir.

Azure Cosmos DB Sync Java SDK 2.x.x kullanıyorsanız, hem Asenkron hem de Senkron API'ler için Azure Cosmos DB Java SDK 4.0'da TCP tabanlı doğrudan bağlantı modunun (HTTP'nin aksine) uygulandığını dikkate alın.

API düzeyi değişiklikleri

Azure Cosmos DB Java SDK 4.x.x'te önceki SDK'larla (Java SDK 3.x.x, Async Java SDK 2.x.x ve Sync Java SDK 2.x.x) karşılaştırıldığında API düzeyindeki değişiklikler aşağıda verilmiştir:

Azure Cosmos DB Java SDK adlandırma kuralları

  • Azure Cosmos DB Java SDK 3.x.x ve 4.0, istemci kaynaklarını olarak Cosmos<resourceName>adlandırıyor. Örneğin, CosmosClient, CosmosDatabase, CosmosContainer. 2.x.x sürümünde ise Azure Cosmos DB Java SDK'larının tekdüzen adlandırma düzeni yoktur.

  • Azure Cosmos DB Java SDK 3.x.x ve 4.0, hem Senkron hem de Asenkron API'ler sunar.

    • Java SDK 4.0: Sınıf adı öğesinden sonra Asynceklenmediği Cosmos sürece tüm sınıflar Eşitleme API'sine aittir.

    • Java SDK 3.x.x: Sınıf adı Async ile eklenmediği sürece tüm sınıflar Asenkron API'ye Cosmos aittir.

    • Async Java SDK 2.x.x: Sınıf adları Sync Java SDK 2.x.x'e benzer, ancak ad Async ile başlar.

Hiyerarşik API yapısı

Azure Cosmos DB Java SDK 4.0 ve 3.x.x, aşağıdaki 4.0 SDK kod parçacığında gösterildiği gibi istemcileri, veritabanlarını ve kapsayıcıları iç içe yerleştirilmiş bir şekilde düzenleyen hiyerarşik bir API yapısı sunar:

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

Azure Cosmos DB Java SDK'sının 2.x.x sürümünde, kaynaklar ve belgeler üzerindeki tüm işlemler istemci örneği aracılığıyla gerçekleştirilir.

Belgeleri temsil etme

Azure Cosmos DB Java SDK 4.0'da özel POJO'lar, JsonNodes Azure Cosmos DB'den belgeleri okumak ve yazmak için iki seçenektir.

Azure Cosmos DB Java SDK 3.x.x'te CosmosItemProperties nesnesi genel API tarafından kullanıma sunulur ve belge gösterimi olarak sunulur. Bu sınıf artık 4.0 sürümünde genel kullanıma sunulmaz.

İçeri aktarmalar

  • Azure Cosmos DB Java SDK 4.0 paketleri com.azure.cosmos ile başlar

  • Azure Cosmos DB Java SDK 3.x.x paketleri com.azure.data.cosmos ile başlıyor

  • Azure Cosmos DB Java SDK 2.x.x Senkron API paketleri com.microsoft.azure.documentdb ile başlar.

  • Azure Cosmos DB Java SDK 4.0, iç içe pakete com.azure.cosmos.modelsbirkaç sınıf yerleştirir. Bu paketlerden bazıları şunlardır:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • Yukarıdaki tüm paketler için Asenkron API analogları
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... Vb.

Accessors

Azure Cosmos DB Java SDK 4.0, örnek üyelerine erişmek için get ve set adlı yöntemleri kullanıma sunar. Örneğin, CosmosContainer örneği container.getId() ve container.setId() yöntemlerine sahiptir.

Bu, akıcı bir arabirimi kullanıma sunan Azure Cosmos DB Java SDK 3.x.x'ten farklıdır. Örneğin, bir CosmosSyncContainer örneği, container.id() ile aşırı yüklenmiş olup id değerini almak veya ayarlamak için kullanılır.

Bağımlılık Çakışmalarını Yönetme

Azure Cosmos DB Java SDK V2'den V4'e yükseltme, SDK tarafından kullanılan kitaplıklardaki değişiklikler nedeniyle bağımlılık çakışmalarına neden olabilir. Bu çakışmaları çözmek için bağımlılıkların dikkatli bir şekilde yönetilmesi gerekir.

  1. Yeni Bağımlılıkları Anlama: Azure Cosmos DB V4 SDK'sının önceki sürümlerden farklı olabilecek kendi bağımlılık kümesi vardır. Bu bağımlılıkların farkında olduğunuzdan emin olun:

    • 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. Çakışan Bağımlılıkları Kaldır: Sdk'nın önceki sürümleriyle ilgili bağımlılıkları dosyanızdan pom.xml kaldırarak başlayın. Bunlar azure-cosmosdb ve eski SDK'nın sahip olabileceği taşımalı bağımlılıkları içerir.

  3. V4 SDK Bağımlılıkları Ekleme: V4 SDK'sını ve bağımlılıklarını öğesine pom.xmlekleyin. İşte bir örnek:

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

  4. Bağımlılık Çakışmalarını Denetleme: Bir bağımlılık ağacı oluşturmak ve çakışmaları tanımlamak için Maven dependency:tree komutunu kullanın. Koş!

    mvn dependency:tree

    Bağımlılıkların çakışan sürümlerini arayın. Bu çakışmalar genellikle reactor-core, netty-handler, guava ve jackson gibi kitaplıklarla oluşur.

  5. Bağımlılık Yönetimi'ni kullanın: Sürüm çakışmaları ile karşılaşırsanız, pom.xml dosyanızdaki <dependencyManagement> bölümünü kullanarak sorunlu sürümleri geçersiz kılmanız gerekebilir. Aşağıda belirli bir sürümün kullanılmasını zorunlu kılmak için bir örnek verilmiş 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. Geçişli Bağımlılıkları Dışlama: Bazen, diğer bağımlılıklar tarafından getirilen geçişli bağımlılıkları dışlamanız gerekebilir. Örneğin, başka bir kitaplık çakişen bir bağımlılığın eski bir sürümünü getirirse, bunu şu şekilde hariç tutabilirsiniz:

    <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. Yeniden Oluştur ve Test Et: Bu değişiklikleri yaptıktan sonra projenizi yeniden derleyin ve yeni bağımlılıkların düzgün çalıştığından ve çalışma zamanı çakışması olmadığından emin olmak için projeyi kapsamlı bir şekilde test edin.

Kod parçacığı karşılaştırmaları

Kaynaklar oluştur

Aşağıdaki kod parçacığı, 4.0, 3.x.x Eşzamanlı, 2.x.x Eşzamanlı ve 2.x.x Eşzamanlı Olmayan API'leri arasında kaynakların nasıl oluşturulduğundaki farkları gösterir:


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

Öğe işlemleri

Aşağıdaki kod parçacığında 4.0, 3.x.x Async, 2.x.x Sync ve 2.x.x Async API'leri arasında öğe işlemlerinin nasıl gerçekleştirildiği arasındaki farklar gösterilmektedir.


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

Dizinleme

Aşağıdaki kod parçacığında 4.0, 3.x.x Async, 2.x.x Eşitleme ve 2.x.x Async API'leri arasında dizin oluşturmanın nasıl oluşturulduğundaki farklar gösterilmektedir:


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

Saklanan prosedürler

Aşağıdaki kod parçacığında 4.0, 3.x.x Async, 2.x.x Sync ve 2.x.x Async API'leri arasında saklı yordamların nasıl oluşturulduğundaki farklar gösterilmektedir:


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

Akışı değiştirme

Aşağıdaki kod parçacığı, değişiklik akışı işlemlerinin 4.0 ile 3.x.x Async API'leri arasında nasıl yürütüleceği arasındaki farkları gösterir:


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

Kapsayıcı düzeyi Yaşam Süresi (TTL)

Aşağıdaki kod parçacığı, 4.0, 3.x.x Asenkron, 2.x.x Senkron ve 2.x.x Asenkron API'leri arasında, kapsayıcıdaki veriler için yaşam süresi oluşturma farklarını gösterir.


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

Öğe düzeyinde Yaşam Süresi (TTL)

4.0, 3.x.x Asenkron, 2.x.x Senkron ve 2.x.x Asenkron API'leri arasında bir öğe için yaşam süresi (TTL) oluşturma konusundaki farkları gösteren aşağıdaki kod parçacığı:


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

Sonraki Adımlar

  • V4 SDK'sını kullanarak NoSQL için Azure Cosmos DB verilerini yönetmek için java uygulaması oluşturma
  • Reactor tabanlı Java SDK'ları hakkında bilgi edinin
  • RxJava zaman uyumsuz kodunu Reactor zaman uyumsuz koduna dönüştürme hakkında bilgi edinmek için Reactor vs RxJava Kılavuzu'nu inceleyin
  • Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz?
    • Tek bildiğiniz mevcut veritabanı kümenizdeki sanal çekirdek ve sunucu sayısıysa, sanal çekirdekleri veya vCPU'ları kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
    • Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
  • Last updated on