مشاركة عبر

ترحيل تطبيقك لاستخدام Azure Cosmos DB Java SDK v4

  • ينطبق على: ✅ NoSQL

مهم

لمزيد من المعلومات حول هذا SDK، يرجى الاطلاع على Azure Cosmos DB Java SDK v4 Release notes، Maven repository، Azure Cosmos DB Java SDK v4 performance plans، وAzure Cosmos DB Java SDK v4 Trouble guide.

مهم

نظرا لأن Azure Cosmos DB Java SDK v4 يحتوي على ما يصل إلى 20% معدل نقل محسن، ووضع مباشر قائم على TCP، ودعم أحدث ميزات خدمات الخلفية، نوصي بالترقية إلى الإصدار 4 في الفرصة القادمة. تابع القراءة أدناه لمعرفة المزيد.

قم بتحديث أحدث حزمة تطوير جافا للعبة Azure Cosmos DB للحصول على أفضل ما يقدمه Azure Cosmos DB - خدمة قاعدة بيانات غير علائقية مدارة بأداء تنافسي، توفر 5-9، حوكمة موارد فريدة من نوعها، والمزيد. تشرح هذه المقالة كيفية ترقية تطبيق جافا الحالي الذي يستخدم مجموعة تطوير جافا قديمة من Azure Cosmos DB إلى Azure Cosmos DB Java SDK 4.0 الأحدث لواجهة برمجة التطبيقات ل NoSQL. Azure Cosmos DB Java SDK v4 يتوافق مع الحزمة com.azure.cosmos . يمكنك استخدام التعليمات في هذا المستند إذا كنت تقوم بترحيل تطبيقك من أي من مجموعات تطوير تطوير جافا لقاعدة بيانات Azure Cosmos التالية:

  • مزامنة Java SDK 2.x.x
  • Async Java SDK 2.x.x
  • Java SDK 3.x.x

Azure Cosmos DB Java SDKs وتعيين الحزم

الجدول التالي يسرد مجموعات تطوير جافا مختلفة من Azure Cosmos DB، واسم الحزمة، ومعلومات الإصدار:

مجموعة تطوير جافا تاريخ الإصدار واجهات برمجة التطبيقات المجمعة مافن جار اسم حزمة جافا مرجع واجهة برمجة التطبيقات ملاحظات الإصدار تاريخ التقاعد
غير متزامن 2.x.x 2018 يونيو Async(RxJava) com.microsoft.azure::azure-cosmosdb com.microsoft.azure.cosmosdb.rx API ملاحظات الإصدار 31 أغسطس 2024
Sync 2.x.x سبتمبر 2018 مزامنه com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API 29 فبراير 2024
3.x.x يوليو 2019 غير متزامن (مفاعل)/التزامن com.microsoft.azure::azure-cosmos com.azure.data.cosmos API - 31 أغسطس 2024
4.0 يونيو 2020 غير متزامن (مفاعل)/التزامن com.azure::azure-cosmos com.azure.cosmos API - -

تغييرات تنفيذ SDK

فيما يلي الفروقات الرئيسية في التنفيذ بين مجموعات تطوير البرمجيات المختلفة:

تم استبدال RxJava بمفاعل في Azure Cosmos DB Java SDK إصدارات 3.x.x و4.0

إذا لم تكن على دراية بالبرمجة غير المتزامنة أو البرمجة التفاعلية، راجع دليل نمط المفاعل لمقدمة في البرمجة غير المتزامنة ومشروع المفاعل. قد يكون هذا الدليل مفيدا إذا كنت تستخدم Azure Cosmos DB Sync Java SDK 2.x.x أو Azure Cosmos DB Java SDK 3.x.x Sync API في السابق.

إذا كنت تستخدم Azure Cosmos DB Async Java SDK 2.x.x، وتخطط للانتقال إلى SDK 4.0، راجع دليل Reactor vs RxJava للحصول على إرشادات حول تحويل كود RxJava لاستخدام Reactor.

يحتوي Azure Cosmos DB Java SDK v4 على وضع اتصال مباشر في كل من واجهات برمجة التطبيقات غير المتزامنة والمزامنة

إذا كنت تستخدم Azure Cosmos DB Sync Java SDK 2.x.x، لاحظ أن وضع الاتصال المباشر المعتمد على TCP (بدلا من HTTP) مطبق في Azure Cosmos DB Java SDK 4.0 لكل من واجهات برمجة التطبيقات غير المتزامنة والمزامنة.

تغييرات مستوى واجهة برمجة التطبيقات

فيما يلي التغييرات على مستوى واجهة برمجة التطبيقات في Azure Cosmos DB Java SDK 4.x.x مقارنة ب SDK السابقة (Java SDK 3.x.x، Async Java SDK 2.x.x، و Sync Java SDK 2.x.x):

Azure Cosmos DB Java SDK naging conventions

  • تشير Azure Cosmos DB وJava SDK 3.x.x و4.0 إلى موارد العميل ك .Cosmos<resourceName> على سبيل المثال، CosmosClient، CosmosDatabase، . CosmosContainer بينما في الإصدار 2.x.x، لا تمتلك مجموعات تطوير جافا في Azure Cosmos DB نظام تسمية موحد.

  • توفر Azure Cosmos DB Java SDK 3.x.x و4.0 كل من واجهات برمجة التطبيقات Sync وAsync.

    • Java SDK 4.0 : جميع الفئات تنتمي إلى واجهة برمجة تطبيقات Sync ما لم يرفق Async اسم الفئة بعد Cosmos.

    • Java SDK 3.x.x: جميع الفئات تنتمي إلى واجهة برمجة التطبيقات غير المتزامنة ما لم يرفق Async اسم الفئة بعد Cosmos.

    • Async Java SDK 2.x.x: أسماء الفئات مشابهة ل Sync Java SDK 2.x.x، لكن الاسم يبدأ ب Async.

هيكل واجهات برمجة التطبيقات الهرمي

تقدم Azure Cosmos DB Java SDK 4.0 و3.x.x هيكل واجهة برمجة تطبيقات هرمي ينظم العملاء وقواعد البيانات والحاويات بطريقة متداخلة كما هو موضح في مقتطف كود SDK 4.0 التالي:

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

في الإصدار 2.x.x من مجموعة تطوير جافا لقاعدة بيانات Azure Cosmos، تتم جميع العمليات على الموارد والوثائق عبر مثيل العميل.

تمثيل الوثائق

في Azure Cosmos DB Java SDK 4.0، هناك POJO مخصص وهما JsonNodes الخياران لقراءة وكتابة المستندات من Azure Cosmos DB.

في Azure Cosmos DB Java SDK 3.x.x، يتم كشف الكائن CosmosItemProperties بواسطة واجهة برمجة التطبيقات العامة ويستخدم كتمثيل للمستند. لم تعد هذه الفئة معروضة علنا في الإصدار 4.0.

عمليات الاستيراد

  • تبدأ حزم Azure Cosmos DB Java SDK 4.0 ب com.azure.cosmos

  • Azure Cosmos DB Java SDK 3.x.x packages تبدأ ب com.azure.data.cosmos

  • Azure Cosmos DB Java SDK 2.x.x تبدأ حزم API ب com.microsoft.azure.documentdb

  • Azure Cosmos DB Java SDK 4.0 يضع عدة فئات في حزمة com.azure.cosmos.modelsمتداخلة . بعض هذه الحزم تشمل:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • نظائر واجهة برمجة التطبيقات غير المتزامنة لجميع الحزم المذكورة أعلاه
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... وهكذا.

الملحقات

Azure Cosmos DB Java SDK 4.0 يعرض get وطرق set للوصول إلى أعضاء النسخ. على سبيل المثال، CosmosContainer الحالة لديها container.getId() وطرق container.setId() .

هذا يختلف عن Azure Cosmos DB Java SDK 3.x.x الذي يعرض واجهة سلسة. على سبيل المثال، هناك CosmosSyncContainer حالة تحتوي container.id() على أن يتم تحميل زائد للحصول على القيمة أو تعيينها id .

إدارة تعارضات الاعتماد

الترقية من Azure Cosmos DB Java SDK V2 إلى V4 يمكن أن تسبب تعارضات تبعية بسبب التغييرات في المكتبات التي تستخدمها SDK. يتطلب حل هذه النزاعات إدارة دقيقة للتبعيات.

  1. فهم التبعيات الجديدة: حزمة تطوير Azure Cosmos DB V4 لها مجموعة تبعيات خاصة بها قد تختلف عن تلك الموجودة في الإصدارات السابقة. تأكد من معرفتك بهذه الاعتماديات:

    • 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. إزالة الاعتماديات المتضاربة: ابدأ بإزالة الاعتماديات المتعلقة بالإصدارات السابقة من مجموعة تطوير البرمجيات من ملفك pom.xml . تشمل azure-cosmosdb هذه وأي تبعيات انتقالية قد تكون موجودة في SDK القديمة.

  3. إضافة تبعيات حزمة تطوير V4: أضف مجموعة تطوير V4 وتبعياتها إلى .pom.xml فيما يلي مثال:

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

  4. تحقق من تعارضات الاعتماد: استخدم أمر Maven dependency:tree لإنشاء شجرة تبعيات وتحديد أي تعارضات. تشغيل:

    mvn dependency:tree

    ابحث عن أي نسخ متضاربة من التبعيات. غالبا ما تحدث هذه التعارضات مع مكتبات مثل reactor-core، netty-handler، guava، و jackson.

  5. استخدم إدارة الاعتماد: إذا واجهت تعارضات في الإصدارات، قد تحتاج إلى تجاوز الإصدارات المشكلة باستخدام القسم <dependencyManagement> في .pom.xml إليك مثال لتطبيق نسخة محددة من 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. استبعاد التبعيات الانتقالية: أحيانا، قد تحتاج إلى استبعاد التبعيات الانتقالية التي تسببها تبعيات أخرى. على سبيل المثال، إذا جلبت مكتبة أخرى نسخة أقدم من تبعية تتعارض، يمكنك استبعادها بهذه الطريقة:

    <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. إعادة البناء والاختبار: بعد إجراء هذه التغييرات، أعد بناء مشروعك واختبره بدقة للتأكد من أن التبعيات الجديدة تعمل بشكل صحيح وعدم حدوث تعارضات وقت تشغيل.

مقارنات مقتطفات الكود

إنشاء الموارد

يظهر مقتطف الكود التالي الفروقات في كيفية إنشاء الموارد بين واجهات برمجة التطبيقات غير المتزامنة 4.0 و3.x.x و2.x.x Sync و2.x.x:


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

عمليات العناصر

يظهر مقتطف الكود التالي الفروقات في كيفية تنفيذ عمليات العناصر بين واجهات برمجة التطبيقات غير المتزامنة 4.0، 3.x.x غير متزامنة، 2.x.x Sync، و2.x.x:


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

الفهرسه

يظهر مقتطف الكود التالي الفروقات في كيفية إنشاء الفهرسة بين واجهات برمجة التطبيقات غير المتزامنة 4.0، 3.x.x غير متزامنة، 2.x.x، و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);

الإجراءات المخزنة

يظهر مقتطف الكود التالي الفروقات في كيفية إنشاء الإجراءات المخزنة بين واجهات برمجة التطبيقات غير المتزامنة 4.0 و3.x.x و2.x.x Sync و2.x.x:


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

موجز التغيير

يظهر مقتطف الكود التالي الفروقات في كيفية تنفيذ عمليات تغذية التغيير بين واجهات برمجة التطبيقات غير المتزامنة 4.0 و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();

مدة العيش على مستوى الحاوية (TTL)

يظهر مقتطف الكود التالي الفروقات في كيفية إنشاء وقت للعيش للبيانات في الحاوية بين واجهات برمجة التطبيقات غير المتزامنة 4.0، 3.x.x Async، 2.x.x Sync، و2.x.x:


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)

يوضح مقطع الكود التالي الفروقات في كيفية إنشاء وقت للعيش لعنصر بين واجهات برمجة التطبيقات غير المتزامنة 4.0 و3.x.x و2.x.x Sync و2.x.x:


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

الخطوات التالية

  • Last updated on