Aracılığıyla paylaş

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

UYGULANANLAR: 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 %20'ye kadar 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 olanaklardan en iyi şekilde yararlanmak için Azure Cosmos DB Java SDK'sını en son sürüme güncelleyin. Rekabetçi performansa sahip, yönetilen ilişkisel olmayan bir veritabanı hizmeti, beş dokuz kullanılabilirlik, benzersiz 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
  • Asenkron 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 Yayımlama Tarihi Paketlenmiş API'ler Maven Jar Java paket adı API Referansı Release Notes (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 Eşitleme com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API 29 Şubat 2024 Perşembe
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'lerde doğrudan bağlantı moduna sahiptir

Azure Cosmos DB Sync Java SDK 2.x.x kullanıyorsanız, hem Zaman Uyumsuz hem de Senkron API'leri için Azure Cosmos DB Java SDK 4.0'da HTTP yerine TCP tabanlı doğrudan bağlantı modunun uygulandığını unutmayı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 sağlar.

    • 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ı öğesinden sonra Asynceklenmediği sürece tüm sınıflar Zaman Uyumsuz 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şlar.

  • Azure Cosmos DB Java SDK 2.x.x Eşitleme API'leri paketleri ile başlar com.microsoft.azure.documentdb

  • 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 Zaman Uyumsuz API analogları
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... ve saire.

Erişimcisi

Azure Cosmos DB Java SDK 4.0, örnek üyelerine erişmek için yöntemler ve get kullanıma sunarset. Ö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() içeren ve id değerini almak veya ayarlamak için aşırı yüklenen bir yapıdadı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 geçişli 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. Bir örnek aşağıda verilmiştir:

    <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. Çalıştır:

    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, içindeki <dependencyManagement> bölümünü kullanarak pom.xml sorunlu sürümleri geçersiz kılmanız gerekebilir. İşte reactor-core'ün belirli bir sürümünü zorunlu kılmak için bir örnek:

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

Kaynak oluşturma

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 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, öğe işlemlerinin nasıl gerçekleştirildiği konusunda 4.0, 3.x.x Asenkron, 2.x.x Senkron ve 2.x.x Asenkron API'leri 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);

Depolanmış yordamlar

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.elastic())
        .subscribe();

Konteyner Seviyesinde Yaşam Süresi (TTL)

Aşağıdaki kod parçacığı, 4.0, 3.x.x Eşzamansız, 2.x.x Eşzamanlı ve 2.x.x Eşzamansız API'leri arasındaki kapsayıcıdaki verilerin yaşam süresi ayarlama arasındaki farkları 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)

Aşağıdaki kod parçacığı, 4.0, 3.x.x Async, 2.x.x Eşitleme ve 2.x.x Zaman Uyumsuz API'leri arasında bir öğe için yaşam süresi oluşturma arasındaki farkları gösterir:


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