عمليات دفعة المعاملات في Azure Cosmos DB

ينطبق على: NoSQL

تصف دفعة المعاملات مجموعة من عمليات النقطة التي يجب أن تنجح أو تفشل مع نفس مفتاح القسم في الحاوية. يتم تعريف العمليات وإضافتها إلى الدفعة وتنفيذ الدفعة. إذا نجحت جميع العمليات بالترتيب الموصوف في عملية دُفعة العمليات، فسيتم تثبيت العملية. ومع ذلك، إذا فشلت أي عملية، يتم التراجع عن المعاملة بالكامل.

ما هي المعاملة في Azure Cosmos DB

يمكن تعريف المعاملة في قاعدة البيانات النموذجية على أنها سلسلة من العمليات التي يتم إجراؤها كوحدة عمل منطقية واحدة. توفر كل معاملة ضمانات خاصية ACID (الحالة الذرية، والاتساق، والعزل، والمتانة).

• تضمنAtomicity أن يتم التعامل مع جميع العمليات التي تتم داخل المعاملة كوحدة واحدة، وإما أنها جميعاً ملتزَم بها أو لا يتم الالتزام بأي منها.
• الاتساق يتأكد من أن البيانات دائماً في حالة صالحة عبر العمليات.
• يضمن العزل عدم تداخل معاملتين مع بعضهما - توفر العديد من الأنظمة التجارية مستويات عزل متعددة يمكن استخدامها بناءً على احتياجات التطبيق.
• تضمن المتانة وجود أي تغيير يتم إجراؤه في قاعدة البيانات دائماً. يدعم Azure Cosmos DB العمليات المتوافقة مع ACID الكامل مع عزل اللقطة للعمليات داخل نفس مفتاح القسم المنطقي.

عمليات دُفعة العمليات والإجراءات المخزنة

يدعم Azure Cosmos DB حالياً الإجراءات المخزنة، والتي توفر أيضاً نطاق المعاملات على العمليات. ومع ذلك، تقدم العمليات الدفعية للعمليات الفوائد التالية:

• خيار اللغة - يتم دعم دفعة العمليات على SDK واللغة التي تستخدمها بالفعل، بينما يلزم كتابة الإجراءات المخزنة بلغة JavaScript.
• تعيين إصدار التعليمات البرمجية - يعد تعيين رمز التطبيق وإدخاله على خط أنابيب CI/CD أمراً طبيعياً أكثر من تنظيم تحديث إجراء مخزن والتأكد من حدوث التمرير في الوقت المناسب. كما أنه يجعل التراجع عن التغييرات أسهل.
• الأداء - تقليل وقت الاستجابة للعمليات المكافئة بنسبة تصل إلى 30٪ مقارنةً بتنفيذ الإجراء المخزن.
• تسلسل المحتوى - يمكن لكل عملية داخل دُفعة عمليات استخدام خيارات التسلسل المخصصة للبيانات الأساسية.

كيفية إنشاء عملية مجموعة عمليات

NET.

عند إنشاء عملية دفعة للعمليات، ابدأ بمثيل حاوية ومثيل CreateTransactionalBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

بعد ذلك، أضف عمليات متعددة إلى الدُفعة:

Product bike = new (
    id: "68719520766",
    category: "road-bikes",
    name: "Chropen Road Bike"
);

batch.CreateItem<Product>(bike);

Part part = new (
    id: "68719519885",
    category: "road-bikes",
    name: "Tronosuros Tire",
    productId: bike.id
);

batch.CreateItem<Part>(part);

أخيراً، قم باستدعاء ExecuteAsync على الدُفعة:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

بمجرد تلقي الرد، تحقق مما إذا كانت الاستجابة ناجحة. إذا كانت الاستجابة تشير إلى نجاح، فاستخرج النتائج:

if (response.IsSuccessStatusCode)
{
    TransactionalBatchOperationResult<Product> productResponse;
    productResponse = response.GetOperationResultAtIndex<Product>(0);
    Product productResult = productResponse.Resource;

    TransactionalBatchOperationResult<Part> partResponse;
    partResponse = response.GetOperationResultAtIndex<Part>(1);
    Part partResult = partResponse.Resource;
}

هام

إذا كان هناك فشل، فسيكون للتعلمية البرمجية الفاشلة رمز حالة للخطأ المقابل. سيكون لجميع العمليات الأخرى رمز حالة 424 (التبعية الفاشلة). إذا فشلت العملية لأنها تحاول إنشاء عنصر موجود بالفعل، يتم إرجاع رمز حالة 409 (تعارض). يمكّن رمز الحالة الشخص من تحديد سبب فشل المعاملة.

Java

عند إنشاء عملية دُفعة للعمليات، اتصل بـ CosmosBatch.createCosmosBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

بعد ذلك، أضف عمليات متعددة إلى الدُفعة:

Product bike = new Product();
bike.setId("68719520766");
bike.setCategory("road-bikes");
bike.setName("Chropen Road Bike");

batch.createItemOperation(bike);

Part part = new Part();
part.setId("68719519885");
part.setCategory("road-bikes");
part.setName("Tronosuros Tire");
part.setProductId(bike.getId());

batch.createItemOperation(part);

أخيراً، استخدم مثيل حاوية لاستدعاء executeCosmosBatch بالدُفعة:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

بمجرد تلقي الرد، تحقق مما إذا كانت الاستجابة ناجحة. إذا كانت الاستجابة تشير إلى نجاح، فاستخرج النتائج:

if (response.isSuccessStatusCode())
{
    List<CosmosBatchOperationResult> results = response.getResults();
}

هام

إذا كان هناك فشل، فسيكون للتعلمية البرمجية الفاشلة رمز حالة للخطأ المقابل. سيكون لجميع العمليات الأخرى رمز حالة 424 (التبعية الفاشلة). إذا فشلت العملية لأنها تحاول إنشاء عنصر موجود بالفعل، يتم إرجاع رمز حالة 409 (تعارض). يمكّن رمز الحالة الشخص من تحديد سبب فشل المعاملة.

Python

الحصول على مثيل حاوية أو إنشائه:

container = database.create_container_if_not_exists(id="batch_container",
                                                        partition_key=PartitionKey(path='/category'))

في Python، تبدو عمليات دفعة المعاملات مشابهة جدا لواجهة برمجة تطبيقات العمليات المفردة، وهي مجموعات تحتوي على (operation_type_string، args_tuple، batch_operation_kwargs_dictionary). فيما يلي نماذج العناصر التي سيتم استخدامها لإظهار وظائف عمليات الدفعات:

create_demo_item = {
    "id": "68719520766",
    "category": "road-bikes",
    "name": "Chropen Road Bike"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item1 = {
    "id": "68719519884",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item2 = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item3 = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, we'll upsert the item with id 68719519885
upsert_demo_item = {
    "id": "68719519885",
    "category": "road-bikes",
    "name": "Tronosuros Tire Upserted",
    "productId": "68719520768"
}

# for replace demo, we'll replace the read_demo_item2 with this item
replace_demo_item = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire replaced",
    "productId": "68719520769"
}

# for replace with etag match demo, we'll replace the read_demo_item3 with this item
# The use of etags and if-match/if-none-match options allows users to run conditional replace operations
# based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
# matches the passed in value. For more on optimistic concurrency control, see the link below:
# https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
replace_demo_item_if_match_operation = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tireh",
    "wasReplaced": "Replaced based on etag match"
    "productId": "68719520769"
}

إعداد العمليات لإضافتها إلى الدفعة:

create_item_operation = ("create", (create_demo_item,), {})
read_item_operation = ("read", ("68719519884",), {})
delete_item_operation = ("delete", ("68719519885",), {})
upsert_item_operation = ("upsert", (upsert_demo_item,), {})
replace_item_operation = ("replace", ("68719519886", replace_demo_item), {})
replace_item_if_match_operation = ("replace",
                                       ("68719519887", replace_demo_item_if_match_operation),
                                       {"if_match_etag": container.client_connection.last_response_headers.get("etag")})

أضف العمليات إلى الدفعة:

batch_operations = [
        create_item_operation,
        read_item_operation,
        delete_item_operation,
        upsert_item_operation,
        replace_item_operation,
        replace_item_if_match_operation
    ]

وأخيرا، قم بتنفيذ الدفعة:

try:
    # Run that list of operations
    batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key="road_bikes")
    # Batch results are returned as a list of item operation results - or raise a CosmosBatchOperationError if
    # one of the operations failed within your batch request.
    print("\nResults for the batch operations: {}\n".format(batch_results))
except exceptions.CosmosBatchOperationError as e:
        error_operation_index = e.error_index
        error_operation_response = e.operation_responses[error_operation_index]
        error_operation = batch_operations[error_operation_index]
        print("\nError operation: {}, error operation response: {}\n".format(error_operation, error_operation_response))
    # [END handle_batch_error]

ملاحظة لاستخدام عملية التصحيح وتشغيل replace_if_match_etag في الدفعة
القاموس kwargs عملية الدفعة محدودة، ويأخذ فقط ما مجموعه ثلاث قيم مفتاح مختلفة. في حالة الرغبة في استخدام التصحيح الشرطي داخل الدفعة، يتوفر استخدام مفتاح filter_predicate لعملية التصحيح، أو في حالة الرغبة في استخدام etags مع أي من العمليات، يتوفر استخدام مفاتيح if_match_etag/if_none_match_etag أيضا.

batch_operations = [
       ("replace", (item_id, item_body), {"if_match_etag": etag}),
       ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
   ]

هام

إذا كان هناك فشل، فسيكون للتعلمية البرمجية الفاشلة رمز حالة للخطأ المقابل. سيكون لجميع العمليات الأخرى رمز حالة 424 (التبعية الفاشلة). إذا فشلت العملية لأنها تحاول إنشاء عنصر موجود بالفعل، يتم إرجاع رمز حالة 409 (تعارض). يمكّن رمز الحالة الشخص من تحديد سبب فشل المعاملة.

كيف يتم تنفيذ العمليات الدفعية للعمليات

عند تنفيذ دفعة المعاملات، يتم تجميع جميع العمليات في دفعة المعاملات، وتسلسلها في حمولة واحدة، وإرسالها كطلب واحد إلى خدمة Azure Cosmos DB.

تتلقى الخدمة الطلب وتنفذ جميع العمليات ضمن نطاق العمليات، وترجع استجابة باستخدام نفس بروتوكول التسلسل. هذه الاستجابة إما ناجحة أو فاشلة وتوفر استجابات عملية فردية لكل عملية.

تعرض SDK الاستجابة لك للتحقق من النتيجة، واختيارياً، استخراج كل نتيجة من نتائج العملية الداخلية.

القيود

حالياً، هناك حدين معروفين:

• يقيد حد حجم طلب Azure Cosmos DB حجم حمولة دفعة المعاملات بحيث لا يتجاوز 2 ميغابايت، والحد الأقصى لوقت التنفيذ هو 5 ثوان.
• هناك حد حالي يبلغ 100 عملية لكل دفعة معاملات لضمان الأداء كما هو متوقع وضمن اتفاقيات مستوى الخدمة.

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

• تعرف على المزيد حول ما يمكنك فعله باستخدام TransactionalBatch

• تفضل بزيارة عيناتنا لمزيد من الطرق لاستخدام Azure Cosmos DB .NET SDK