تنفيذ الترابط والتوازي

مكتمل

بينما تنفذ SDK أنواع مؤشر ترابط آمنة وبعض درجات من التوازي، توجد أفضل الممارسات يمكنك تنفيذها في التعليمات البرمجية لتطبيقك للتأكد من أن عدة SDK تتمتع بأفضل أداء ممكن في حمل العمل لديك.

تجنب المهلات المتعلقة بالموارد

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

استخدم async/await في .NET

تتضمن لغة C# في .NET سلسلة من الميزات المستندة إلى المهام لاستدعاء أساليب عدة SDK للعميل على نحو غير متزامن. على سبيل المثال، يتم استدعاء أسلوب CreateDatabaseIfNotExistsAsync على نحو غير متزامن باستخدام الصيغة التالية.

Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");

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

تجنب حظر التنفيذ غير المتزامن باستخدام Task.Wait أو Task.Result كما هو الحال في مثال التعليمات البرمجية التالية.

Database database = client.CreateDatabaseIfNotExistsAsync("cosmicworks").Result;

استخدام العدادات المضمنة بدلًا من أساليب LINQ

تقوم أساليب LINQ مثل ToList باستنزاف الاستعلام بشغف وبشكل متزامن أثناء حظر أي مكالمات أخرى من التنفيذ. على سبيل المثال، يمنع استدعاء ToList() هذا جميع الاستدعاءات الأخرى ويحتمل أن يسترد مجموعة كبيرة من البيانات:

container.GetItemLinqQueryable<T>()
    .Where(i => i.categoryId == 2)
    .ToList<T>();

يتضمن SDK أساليب مثل ToFeedIterator<T> التي تسترد نتائج الاستعلام دون حظر المكالمات الأخرى بشكل غير متزامن. يوضح هذا المثال السيناريو نفسه ولكن باستخدام عداد خاص بدلاً من ToList.

container.GetItemLinqQueryable<T>()
    .Where(i => i.categoryId == 2)
    .ToFeedIterator<T>();

قم بتكوين الحد الأقصى من التزامن، والتوازي، وعدد العناصر المُخزنة مؤقتا

عندما تقوم بإصدار استعلام من SDK، يتضمن QueryRequestOptions مجموعة من الخصائص لضبط أداء الاستعلام.

الحد الأقصى من عدد العناصر

يتم إرجاع جميع نتائج الاستعلام في Azure Cosmos DB ل NoSQL ك "صفحات" من النتائج. تشير هذه الخاصية إلى عدد العناصر التي ترغب في إرجاعها في كل "صفحة". إن الخدمة الافتراضية هي 100 عنصر في كل صفحة من النتائج. يمكنك تعيين هذه القيمة إلى -1 لتعيين حجم ديناميكي للصفحة.

في هذا المثال، يتم تعيين خاصية MaxItemCount إلى قيمة 500.

QueryRequestOptions options = new ()
{
    MaxItemCount = 500
};

تلميح

إذا كنت تستخدم MaxItemCount بقيمة -1، يجب التأكد من أن إجمالي الاستجابة لا يتجاوز حد الخدمة في حجم الاستجابة. على سبيل المثال، فإن حجم الاستجابة الأقصى هو 4 ميغابايت.

الحد الأقصى للتزامن

تحدد MaxConcurrency عدد العمليات المتزامنة التي تم تشغيلها من جانب العميل أثناء تنفيذ الاستعلام المتوازي. إذا تم تعيينها إلى 1، يتم تعطيل التوازي بشكل فعّال. إذا تم تعيينها إلى -1، تقوم عدة SDK بإدارة هذا الإعداد. وعلى نحو مثالي، يمكنك تعيين هذه القيمة إلى عدد من الأقسام الفعلية في حاويتك.

في هذا المثال، يتم تعيين خاصية MaxItemCount إلى قيمة قدرها 5.

QueryRequestOptions options = new ()
{
    MaxConcurrency = 5
};

الحد الأقصى لعدد العناصر المُخزنة مؤقتًا

تقوم الخاصية MaxBufferedItemCount بتعيين الحد الأقصى لعدد العناصر المُخزنة مؤقتًا من جانب العميل أثناء تنفيذ الاستعلام المتوازي. إذا تم تعيينها إلى -1، تقوم عدة SDK بإدارة هذا الإعداد. تعتمد القيمة المثالية لهذا الإعداد إلى حد كبير على خصائص جهاز العميل الخاص بك.

في هذا المثال، يتم تعيين خاصية MaxItemCount إلى قيمة قدرها 5,000.

QueryRequestOptions options = new ()
{
    MaxBufferedItemCount = 5000
};

هناك العديد من أفضل الممارسات والخيارات التي يمكنك تنفيذها في تطبيق Python الخاص بك عند استخدام Azure Cosmos DB Python SDK لضمان الأداء الأمثل لأحمال العمل الخاصة بك.

تجنب المهلات المتعلقة بالموارد

تحدث العديد من مهلات الطلب بسبب ارتفاع استخدام وحدة المعالجة المركزية أو الموارد على أجهزة العميل، بدلا من حدوث مشكلات على جانب خدمة Azure Cosmos DB. مراقبة استخدام الموارد على أجهزة العميل، وتوسيع نطاق التطبيق الخاص بك بشكل مناسب لتجنب أخطاء SDK أو إعادة المحاولة بسبب استنفاد الموارد المحلية.

استخدام الاستعلامات غير المتزامنة

يدعم Azure Cosmos DB Python SDK العمليات غير المتزامنة من خلال إطار عمل Python asyncio ويوفر فئات للبرمجة غير المتزامنة ضمن مساحة الاسم azure.cosmos.aio . على سبيل المثال، يمكنك استخدام الطريقة query_items بشكل غير متزامن:

from azure.cosmos.aio import CosmosClient
import asyncio

endpoint = "<cosmos-endpoint>"
key = "<cosmos-key>"

client = CosmosClient(endpoint, key)

async def query_items_async(client):
    # Get database and container clients
    database = client.get_database_client("cosmicworks")
    container = database.get_container_client("products")

    # Define the query and parameters
    query = "SELECT * FROM c WHERE c.categoryId = @categoryId"
    parameters = [{"name": "@categoryId", "value": "bikes"}]

    # Perform the query asynchronously
    async for item in container.query_items(
        query=query,
        parameters=parameters
    ):
        print(item)

    # Close the client
    await client.close()

asyncio.run(query_items_async(client))

قبل استخدام الفئات azure.cosmos.aio للعمليات غير المتزامنة، تأكد من تثبيت المكتبة aiohttp (pip install aiohttp).

يضمن الاستخدام asyncio إمكانية معالجة عمليات متعددة بشكل متزامن دون منع تنفيذ التعليمات البرمجية الأخرى.

تجنب حظر التنفيذ غير المتزامن عن طريق خلط الأساليب المتزامنة وغير المتزامنة بشكل غير صحيح، مثل:

iterator = client.query_items(query=query, parameters=parameters).result()  # Incorrect

بدلا من ذلك، استخدم await دائما للمكالمات غير المتزامنة.

استخدام المكررات للاستعلامات

يتضمن Python SDK مكررات مضمنة لاسترداد نتائج الاستعلام بكفاءة دون حظر العمليات الأخرى. تجنب جمع جميع نتائج الاستعلام بفارغ الصبر، حيث يمكن أن يؤدي إلى استخدام ذاكرة كبيرة وحظر العمليات الأخرى.

مثال غير فعال:

results = list(container.query_items(
    query="SELECT * FROM c WHERE c.categoryId = 'bikes'"
))

مثال فعال باستخدام مكرر:

iterator = container.query_items(
    query="SELECT * FROM c WHERE c.categoryId = 'bikes'"
)

async for item in iterator:
    print(item)

يسمح لك استخدام المكررات بمعالجة البيانات بطريقة فعالة في الذاكرة ومعالجة النتائج عند وصولها.

تكوين خيارات الاستعلام للأداء

عند إصدار استعلام، تتيح لك Python SDK تكوين العديد من الخيارات عبر QueryIterable طرق أو query_items لتحسين الأداء.

الحد الأقصى من عدد العناصر

يتم إرجاع جميع نتائج الاستعلام في Azure Cosmos DB ل NoSQL في "صفحات" النتائج. تحدد المعلمة max_item_count عدد العناصر التي سيتم إرجاعها في كل صفحة. الإعداد الافتراضي للخدمة هو 100 عنصر لكل صفحة.

مثال مع 500 max_item_count :

iterator = container.query_items(
    query="SELECT * FROM c",
    max_item_count=500
)

تلميح

إذا كنت تستخدم من max_item_count-1، فتأكد من أن حجم الاستجابة الإجمالي لا يتجاوز حد الخدمة البالغ 4 ميغابايت.

استخدام مفتاح القسم

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

على سبيل المثال:

iterator = container.query_items(
    query="SELECT * FROM c WHERE c.categoryId = @categoryId",
    parameters=[{"name": "@categoryId", "value": "bikes"}],
    partition_key="bikes"
)

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

يسمح Python SDK بعمليات الدفعة على العناصر داخل نفس مفتاح القسم. استخدم الفئة TransactionalBatch لتنفيذ عمليات متعددة ذريا.

على سبيل المثال:

# Define the partition key and batch operations
partition_key = "socks"
batch = [
    ("create", ({"id": "sock7", "categoryId": partition_key, "name": "Red Racing Socks"},)),
    ("create", ({"id": "sock8", "categoryId": partition_key, "name": "White Racing Socks"},))
]

# Execute the batch
batch_response = container.execute_item_batch(batch, partition_key=partition_key)

# Print the resource body results to see the created items
for result in batch_response:
    print(result.get("resourceBody"))

إشعار

يجب أن تستهدف عمليات الدفعات مفتاح قسم واحد ويمكن أن تتضمن ما يصل إلى 100 عملية أو 4 ميغابايت في الحجم.

هناك العديد من أفضل الممارسات والخيارات التي يمكنك تنفيذها في التطبيق الخاص بك عند استخدام Azure Cosmos DB JavaScript SDK لضمان الأداء الأمثل لأحمال العمل الخاصة بك.

تجنب المهلات المتعلقة بالموارد

غالبا ما تحدث مهلات الطلب بسبب ارتفاع استخدام وحدة المعالجة المركزية أو الموارد على أجهزة العميل بدلا من مشكلات جانب الخدمة. مراقبة استخدام الموارد على أجهزة العميل، وتوسيع نطاق التطبيق الخاص بك بشكل مناسب لتجنب أخطاء SDK أو إعادة المحاولة الناجمة عن استنفاد الموارد المحلية.

استخدام الاستعلامات غير المتزامنة

يدعم Azure Cosmos DB JavaScript SDK العمليات غير المتزامنة باستخدام الوعود و async/await. على سبيل المثال، يمكنك استخدام الطريقة createDatabaseIfNotExists بشكل غير متزامن:

const { CosmosClient } = require("@azure/cosmos");

const client = new CosmosClient({ endpoint: "<cosmos-endpoint>", key: "<cosmos-key>" });

async function createDatabase() {
    const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
    console.log(`Database created: ${database.id}`);
}
createDatabase();

يضمن الاستخدام async/await عمليات عدم الحظر ويسمح ل SDK بالتعامل مع طلبات متعددة بكفاءة.

تجنب حظر التنفيذ غير المتزامن عن طريق الاستخدام .then() غير الصحيح أو .catch() بطريقة تعيق الأداء.

استخدام المكررات للاستعلامات

يتضمن JavaScript SDK مكررات مضمنة لاسترداد نتائج الاستعلام بكفاءة دون حظر العمليات الأخرى. تجنب جمع جميع نتائج الاستعلام بفارغ الصبر، حيث يمكن أن تستهلك كمية كبيرة من الذاكرة وتمنع العمليات الأخرى.

مثال غير فعال

const results = await container.items
    .query("SELECT * FROM c WHERE c.categoryId = 2", { enableCrossPartitionQuery: true })
    .fetchAll();
console.log(results.resources);

مثال فعال باستخدام مكرر

const iterator = container.items.query(
    "SELECT * FROM c WHERE c.categoryId = 2",
    { enableCrossPartitionQuery: true }
);

while (iterator.hasMoreResults()) {
    const { resources } = await iterator.fetchNext();
    for (const item of resources) {
        console.log(item);
    }
}

يسمح لك استخدام المكررات بمعالجة النتائج على دفعات أصغر، ما يقلل من استخدام الذاكرة ويحسن الكفاءة.

تكوين خيارات الاستعلام للأداء

عند إصدار استعلام، تتيح لك JavaScript SDK تكوين عدة خيارات عبر query طريقة تحسين الأداء.

الحد الأقصى من عدد العناصر

يتم إرجاع جميع نتائج الاستعلام في Azure Cosmos DB ل NoSQL في "صفحات" النتائج. تحدد المعلمة maxItemCount عدد العناصر التي سيتم إرجاعها في كل صفحة. الإعداد الافتراضي للخدمة هو 100 عنصر لكل صفحة.

مثال مع 500 maxItemCount :

const iterator = container.items.query(
    "SELECT * FROM c",
    { maxItemCount: 500, enableCrossPartitionQuery: true }
);

تلميح

إذا كنت تستخدم من maxItemCount-1، فتأكد من أن حجم الاستجابة الإجمالي لا يتجاوز حد الخدمة البالغ 4 ميغابايت.

استخدام مفتاح القسم

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

على سبيل المثال:

const iterator = container.items.query(
    {
        query: "SELECT * FROM c WHERE c.categoryId = @categoryId",
        parameters: [{ name: "@categoryId", value: "socks" }]
    },
    { partitionKey: "socks" }
);

نظرا لأنه categoryId أيضا مفتاح القسم ، يمكنك أيضا استخدام بناء الجملة المختصر:

const iterator = container.items.query(
    {
        query: "SELECT * FROM c"
    },
    { partitionKey: "socks" }
);

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

يسمح JavaScript SDK بعمليات الدفعة على العناصر داخل نفس مفتاح القسم. استخدم الطريقة container.items.batch لإجراء عمليات متعددة ذريا.

على سبيل المثال:

const { CosmosClient, BulkOperationType } = require("@azure/cosmos");

const partitionKey = "bikes";
    const operations = [
        {
            operationType: BulkOperationType.Create,
            resourceBody: {
                id: "rb3k",
                name: "Road Bike 3000",
                description: "This is a very fast road bike.",
                categoryId: "bikes"
            }
        },
        {
            operationType: BulkOperationType.Create,
            resourceBody: {
                id: "mb2k",
                name: "Mountain Bike 2000",
                description: "This is a capable and sturdy mountain bike.",
                categoryId: "bikes"
            }
        },
        {
            operationType: BulkOperationType.Create,
            resourceBody: {
                id: "tb1k",
                name: "Touring Bike 1000",
                description: "This is a casual touring bike.",
                categoryId: "bikes"
            }
        }
    ];

    const response = await container.items
        .bulk(operations, { partitionKey });
    console.log(response);

إشعار

يجب أن تستهدف عمليات الدفعة مفتاح قسم واحد ويمكن أن تتضمن ما يصل إلى 100 عملية أو 2 ميغابايت في الحجم.

إشعار

يتم استكشاف هذه الإعدادات بمزيد من التفصيل في وحدات Azure Cosmos DB الأخرى ل NoSQL على إصدار الاستعلامات باستخدام SDK.