ترحيل التطبيق الخاص بك لاستخدام Azure Cosmos DB Java SDK الإصدار الرابع
ينطبق على: NoSQL
هام
برجاء عرض Azure Cosmos DB Java SDK v4 ملاحظات الإصدار ومستودع Maven وتلميحات أداءحزمة تطوير برامج Java Azure Cosmos DB - الإصدار 4 ودليل استكشاف الأخطاء وإصلاحها الخاص بـحزمة تطوير برامج Java Azure Cosmos DB - الإصدار 4 لمزيد من المعلومات.
هام
نظراً لأن Azure Cosmos DB Java SDK الإصدار 4 يحتوي على إنتاجية محسّنة تصل إلى 20٪، ووضع مباشر قائم على بروتوكول تحكم الإرسال ودعم لأحدث ميزات خدمة الواجهة الخلفية، نوصيك بالترقية إلى الإصدار 4 في الفرصة التالية. مواصلة القراءة أدناه لمعرفة المزيد.
قم بالتحديث إلى أحدث إصدار من Azure Cosmos DB Java SDK للحصول على أفضل ما يجب أن تقدمه Azure Cosmos DB - خدمة قاعدة بيانات غير علائقية مُدارة ذات أداء تنافسي، وتوافر خمسة، وإدارة موارد فريدة من نوعها، والمزيد. توضح هذه المقالة كيفية ترقية تطبيق Java الحالي الذي يستخدم Azure Cosmos DB Java SDK أقدم إلى Azure Cosmos DB Java SDK 4.0 الأحدث لواجهة برمجة التطبيقات ل NoSQL. يتوافق Azure Cosmos DB Java SDK الإصدار 4 مع الحزمة com.azure.cosmos
. يمكنك استخدام الإرشادات الواردة في هذا المستند إذا كنت تقوم بترحيل تطبيقك من أي من حزم SDK التالية لـ Azure Cosmos DB Java:
- مزامنة Java SDK 2.x.x
- عدم مزامنة Java SDK 2.x.x
- Java SDK 3.x.x
تطبيق Azure Cosmos DB Java SDK وتعيينات الحزم
يسرد الجدول التالي مجموعات تطوير Java SDK مختلفة لـ Azure Cosmos DB واسم الحزمة ومعلومات الإصدار:
Java SDK | تاريخ الإصدار | واجهات برمجة التطبيقات المجمعة | Maven Jar | اسم حزمة Java | مرجع API | ملاحظات الإصدار | تاريخ الإيقاف |
---|---|---|---|---|---|---|---|
غير متزامن 2.x.x | 2018 يونيو | غير متزامن (RxJava) | com.microsoft.azure::azure-cosmosdb |
com.microsoft.azure.cosmosdb.rx |
API | ملاحظات الإصدار | 31 أغسطس 2024 |
مزامنة 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
فيما يلي الاختلافات الرئيسية في التنفيذ بين حزم SDK المختلفة:
تم استبدال RxJava بالمفاعل في إصدارات Azure Cosmos DB Java SDK 3.x.x و4.0
إذا لم تكن معتاداً على البرمجة غير المتزامنة أو البرمجة التفاعلية، فراجع دليل نمط المفاعل للحصول على مقدمة حول البرمجة غير المتزامنة وProject Reactor. قد يكون هذا الدليل مفيداً إذا كنت تستخدم Azure Cosmos DB Sync Java SDK 2.x.x أو واجهة برمجة التطبيقات المتزامنة Azure Cosmos DB Java SDK 3.x.x في الماضي.
إذا كنت تستخدم Azure Cosmos DB لمزامنة Java SDK 2.xx، وكنت تخطط للترحيل إلى 4.0 SDK، فراجع Reactor مقابل RxJava Guide للحصول على إرشادات حول تحويل رمز RxJava لاستخدام Reactor.
يحتوي Azure Cosmos DB Java SDK الإصدار 4 على وضع اتصال مباشر في كل من واجهات برمجة التطبيقات الغير متزامنة والمتزامنة
إذا كنت تستخدم Azure Cosmos DB Sync Java SDK 2.x.x، فلاحظ أن وضع الاتصال المباشر المستند إلى بروتوكول تحكم الإرسال (على عكس بروتوكول نقل نص تشعبي) يتم تنفيذه في 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):
يشير الإصداران 3.x.x و4.0 من Azure Cosmos DB Java SDK إلى موارد العميل كـ
Cosmos<resourceName>
. على سبيل المثال،CosmosClient
،CosmosDatabase
،CosmosContainer
. بينما في الإصدار 2.x.x، لا تحتوي حزم تطوير برامج Java SDK من Azure Cosmos DB على نظام تسمية موحد.توفر Azure Cosmos DB Java SDK 3.x.x و4.0 كلاً من واجهات برمجة التطبيقات المتزامنة وغير المتزامنة.
Java SDK 4.0: تنتمي جميع الفئات إلى واجهات برمجة التطبيقات المتزامنة ما لم يتم إلحاق اسم الفئة بـ
Async
بعدCosmos
.Java SDK 3.x.x: تنتمي جميع الفئات إلى واجهات برمجة التطبيقات المتزامنة ما لم يتم إلحاق اسم الفئة بـ
Async
بعدCosmos
.Async Java SDK 2.x.x: أسماء الفئات مشابهة لـ Sync Java SDK 2.x.x، إلا إن الاسم يبدأ بـ غير متزامن.
هيكل واجهات برمجة التطبيقات الهرمي
يقدم Azure Cosmos DB Java SDK 4.0 و3.x.x هيكل واجهات برمجة تطبيقات هرمية تنظم العملاء وقواعد البيانات والحاويات بطريقة متداخلة كما هو موضح في مقتطف التعليمات البرمجية 4.0 SDK التالي:
CosmosContainer container = client.getDatabase("MyDatabaseName").getContainer("MyContainerName");
في الإصدار 2.x.x من Azure Cosmos DB Java SDK، يتم تنفيذ جميع العمليات على الموارد والمستندات من خلال مثيل العميل.
تقديم المستندات
في 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 بـ
com.azure.data.cosmos
تبدأ حزم Azure Cosmos DB Java SDK 2.x.x Sync 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
أو تعيينها.
مقارنات قصاصة برمجية
إنشاء الموارد
يُظهر مقتطف الشفرة التالي الاختلافات في كيفية إنشاء الموارد بين واجهات برمجة التطبيقات 4.0, 3.x.x غير المتزامنة، و2.x.x المتزامنة، و2.x.x غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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 المتزامنة، و2.x.x غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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 غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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 المتزامنة، و2.x.x غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 2.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.elastic())
.subscribe();
مدة البقاء على مستوى الحاوية (TTL)
يوضح مقتطف الشفرة التالي الاختلافات في كيفية إنشاء وقت بقاء للبيانات في الحاوية بين واجهات برمجة تطبيقات 4.0، 3.x.x غير المتزامنة، و2.x.x المتزامنة، و2.x.x غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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 المتزامنة، و2.x.x غير المتزامنة:
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 4.0
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 3.x.x
- واجهة برمجة التطبيقات المتزامنةJava SDK 2.x.x
- واجهة برمجة التطبيقات غير المتزامنةJava SDK 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
);
الخطوات التالية
- إنشاء تطبيق Java لإدارة Azure Cosmos DB لبيانات NoSQL باستخدام V4 SDK
- تعرف على معلومات حول مجموعات Java SDK المستندة إلى المفاعلات
- تعرف على كيفية تحويل رمز RxJava غير المتزامن إلى رمز Reactor غير المتزامن باستخدام Reactor مقابل RxJava Guide
- هل تحاول القيام بتخطيط السعة للترحيل إلى Azure Cosmos DB؟
- في حال كان كل ما تعرفه هو عدد vcores والخوادم في مجموعة قاعدة البيانات الحالية، فاقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs
- إذا كان كل ما تعرفه هو عدد vcores والخوادم الموجودة في مجموعة قاعدة البيانات، اقرأ عن تقدير وحدات الطلب باستخدام vCores أو vCPUs