Azure Cosmos DB مشغل لوظائف Azure 2.x وأعلى

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

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

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

هام

تستخدم هذه المقالة علامات التبويب لدعم إصدارات متعددة من نموذج البرمجة Node.js. يتوفر نموذج v4 بشكل عام وتم تصميمه للحصول على تجربة أكثر مرونة وبديهية لمطوري JavaScript وTypeScript. لمزيد من التفاصيل حول كيفية عمل نموذج v4، راجع دليل مطور Azure Functions Node.js. لمعرفة المزيد حول الاختلافات بين v3 وv4، راجع دليل الترحيل.

تدعم Azure Functions نموذجي برمجة ل Python. تعتمد الطريقة التي تحدد بها روابطك على نموذج البرمجة الذي اخترته.

يتيح لك نموذج برمجة Python v2 تحديد الروابط باستخدام المحسنات مباشرة في التعليمات البرمجية لدالة Python. لمزيد من المعلومات، راجع دليل مطور Python.

تدعم هذه المقالة كلا نموذجي البرمجة.

مثال

يعتمد استخدام المشغل على إصدار حزمة الملحق وصيغة C# المستخدمة في تطبيق الوظائف الخاص بك، والتي يمكن أن تكون واحدة مما يلي:

تعمل مكتبة فئة معالجة عامل معزولة تعمل دالة C# المحولة برمجيا في عملية معزولة عن وقت التشغيل.

تعتمد الأمثلة التالية على إصدار الملحق لوضع C# المحدد.

يشير هذا المثال إلى نوع ToDoItem بسيط:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

يتم استدعاء الدالة التالية عند وجود إدراجات أو تحديثات في قاعدة البيانات والمجموعة المحددة.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

يتم استدعاء هذه الدالة عند وجود إدراجات أو تحديثات في قاعدة البيانات والحاوية المحددة.

بسبب تغييرات المخطط في Azure Cosmos DB SDK، يتطلب الإصدار 4.x من ملحق Azure Cosmos DB azure-functions-java-library V3.0.0 لوظائف Java.

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي @CosmosDBTrigger على المعلمات التي تأتي قيمتها من Azure Cosmos DB. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو POJOs أو القيم االخالية Optional<T>.

يوضح المثال التالي دالة TypeScript لمشغل Azure Cosmos DB. تكتب الدالة رسائل السجل عند إضافة سجلات Azure Cosmos DB أو تعديلها.

import { app, InvocationContext } from '@azure/functions';

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

يوضح المثال التالي دالة JavaScript مشغل Azure Cosmos DB. تكتب الدالة رسائل السجل عند إضافة سجلات Azure Cosmos DB أو تعديلها.

const { app } = require('@azure/functions');

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

يوضح المثال التالي كيفية تشغيل دالة مع تغير البيانات في Azure Cosmos DB.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

لاحظ أن بعض أسماء سمات الربط تغيرت في الإصدار 4.x من ملحق Azure Cosmos DB.

في الملف run.ps1، يمكنك الوصول إلى المستند الذي يؤدي إلى تشغيل الدالة عبر معلمة $Documents.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

يوضح المثال التالي ربط مشغل Azure Cosmos DB. يعتمد المثال على ما إذا كنت تستخدم نموذج برمجة v1 أو v2 Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

السمات

تستخدم كل من مكتبات C#‎ للعملية قيد المعالجة والعملية المعزولةCosmosDBTriggerAttribute لتعريف الدالة. يستخدم البرنامج النصي C# بدلا من ذلك ملف تكوين function.json كما هو موضح في دليل البرمجة النصية C#‎.

خاصية السمة ‏‏الوصف
Connection اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
DatabaseName اسم قاعدة بيانات Azure Cosmos DB مع الحاوية التي يتم مراقبتها.
ContainerName اسم الحاوية التي يتم مراقبتها.
LeaseConnection (اختياري) اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي يحتوي على حاوية التأجير.

عند عدم التعيين، تُستخدم القيمة Connection. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في المدخل. يجب أن يكون لسلسلة الاتصال لحاوية التأجير أذونات الكتابة.
LeaseDatabaseName (اختياري) اسم قاعدة البيانات التي تحتوي على الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم قيمة الإعداد databaseName.
LeaseContainerName (اختياري) اسم الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم القيمة leases.
CreateLeaseContainerIfNotExists (اختياري) عند تعيينها إلى true، يتم إنشاء حاوية عقود الإيجار تلقائيًّا عندما لا تكون موجودة بالفعل. القيمة الافتراضية هي false. عند استخدام هويات Microsoft Entra إذا قمت بتعيين القيمة إلى true، فإن إنشاء حاويات ليس عملية مسموحا بها ولن تتمكن الدالة من البدء.
LeasesContainerThroughput (اختياري) تعريف عدد وحدات الطلب لتعيينها عند إنشاء حاوية التأجيرات. يتم استخدام هذا الإعداد فقط عند تعيين CreateLeaseContainerIfNotExists إلى true. يتم تعيين هذه المعلمة تلقائيا عند إنشاء الربط باستخدام المدخل.
LeaseContainerPrefix (اختياري) عند تعيين القيمة، تتم إضافتها كبادئة لعقود الإيجار التي تم إنشاؤها في حاوية التأجير لهذه الدالة. يسمح استخدام بادئة دالتين Azure منفصلة مشاركة نفس حاوية Lease باستخدام بادئات مختلفة.
FeedPollDelay (اختياري) الوقت (بالمللي ثانية) للتأخير بين الاستقصاء عن قسم للتغييرات الجديدة على الخلاصة، بعد أن يتم تجفيف كافة التغييرات الحالية. الافتراضي هو 5000 مللي ثانية أو 5 ثوان.
LeaseAcquireInterval (اختياري) عند تعيينها، فإنه يعرف، في ميلي ثانية، الفاصل الزمني لبدء مهمة لحساب إذا تم توزيع الأقسام بالتساوي بين مثيلات المضيف المعروفة. الافتراضي هو 13000 (13 ثانية).
LeaseExpirationInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، الفترة الزمنية التي يتم أخذ التأجير من أجلها على عقد إيجار يمثل قسمًا. إذا لم يتم تجديد التأجير ضمن هذه الفترة الزمنية، فإنه يؤدي إلى انتهاء صلاحية وملكية القسم سينتقل إلى مثيل آخر. الافتراضي هو 60000 (60 ثانية).
LeaseRenewInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، فترة التجديد لكافة عقود الإيجار للأقسام الموجودة حاليا بواسطة مثيل. الافتراضي هو 17000 (17 ثانية).
MaxItemsPerInvocation (اختياري) عند تعيين هذه الخاصية تعيين الحد الأقصى لعدد العناصر المتلقاة لكل استدعاء دالة. إذا تم تنفيذ العمليات في حاوية المراقبة من خلال الإجراءات المخزنة، يتم الاحتفاظ بنطاق المعاملة عند قراءة العناصر من موجز التغيير. ونتيجة لذلك، قد يكون عدد العناصر المتلقاة أعلى من القيمة المحددة بحيث يتم إرجاع العناصر التي تم تغييرها بواسطة نفس المعاملة كجزء من دفعة ذرية واحدة.
StartFromBeginning (اختياري) يخبر هذا الخيار المشغل قراءة التغييرات من بداية محفوظات التغيير للحاوية بدلًا من البدء في الوقت الحالي. القراءة من البداية يعمل فقط في المرة الأولى التي يبدأ فيها المشغل، كما هو الحال في التشغيلات اللاحقة، يتم تخزين نقاط التفتيش بالفعل. وتعيين هذا الخيار إلى true عندما يكون هناك عقود إيجار تم إنشاؤها بالفعل ليس له أي تأثير.
StartFromTime (اختياري) الحصول على التاريخ والوقت أو تعيينهما لتهيئة عملية قراءة موجز التغيير. التنسيق الموصى به هو ISO 8601 مع المعين UTC، مثل 2021-02-16T14:19:29Z. يتم استخدام هذا فقط لتعيين حالة المشغل الأولي. بعد أن يكون للمشغل حالة تأجير، لا يكون لتغيير هذه القيمة أي تأثير.
PreferredLocations (اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافياً في خدمة Azure Cosmos DB. يجب فصل القيم بفاصلة. على سبيل المثال، "شرق الولايات المتحدة، جنوب وسط الولايات المتحدة، شمال أوروبا".

الديكور

ينطبق فقط على نموذج برمجة Python v2.

بالنسبة لوظائف Python v2 المعرفة باستخدام مصمم الديكور، الخصائص التالية على cosmos_db_trigger:

الخاصية ‏‏الوصف
arg_name اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
database_name اسم قاعدة بيانات Azure Cosmos DB مع المجموعة التي يتم مراقبتها.
collection_name اسم مجموعة Azure Cosmos DB التي تتم مراقبتها.
connection تتم مراقبة سلسلة الاتصال Azure Cosmos DB.

للحصول على وظائف Python المعرفة باستخدام function.json، راجع قسم التكوين.

تعليقات توضيحية

بسبب تغييرات المخطط في Azure Cosmos DB SDK، يتطلب الإصدار 4.x من ملحق Azure Cosmos DB azure-functions-java-library V3.0.0 لوظائف Java.

استخدم التعليق التوضيحي @CosmosDBTrigger على المعلمات التي تقرأ البيانات من Azure Cosmos DB. يدعم التعليق التوضيحي الخصائص التالية:

خاصية السمة ‏‏الوصف
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
الاسم اسم الدالة
databaseName اسم قاعدة بيانات Azure Cosmos DB مع الحاوية التي يتم مراقبتها.
containerName اسم الحاوية التي يتم مراقبتها.
leaseConnectionStringSetting (اختياري) اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي يحتوي على حاوية التأجير.

عند عدم التعيين، تُستخدم القيمة Connection. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في المدخل. يجب أن يكون لسلسلة الاتصال لحاوية التأجير أذونات الكتابة.
leaseDatabaseName (اختياري) اسم قاعدة البيانات التي تحتوي على الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم قيمة الإعداد databaseName.
leaseContainerName (اختياري) اسم الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم القيمة leases.
createLeaseContainerIfNotExists (اختياري) عند تعيينها إلى true، يتم إنشاء حاوية عقود الإيجار تلقائيًّا عندما لا تكون موجودة بالفعل. القيمة الافتراضية هي false. عند استخدام هويات Microsoft Entra إذا قمت بتعيين القيمة إلى true، فإن إنشاء حاويات ليس عملية مسموحا بها ولن تبدأ الدالة.
leasesContainerThroughput (اختياري) تعريف عدد وحدات الطلب لتعيينها عند إنشاء حاوية التأجيرات. يتم استخدام هذا الإعداد فقط عند تعيين CreateLeaseContainerIfNotExists إلى true. يتم تعيين هذه المعلمة تلقائيا عند إنشاء الربط باستخدام المدخل.
leaseContainerPrefix (اختياري) عند تعيين القيمة، تتم إضافتها كبادئة لعقود الإيجار التي تم إنشاؤها في حاوية التأجير لهذه الدالة. يسمح استخدام بادئة دالتين Azure منفصلة مشاركة نفس حاوية Lease باستخدام بادئات مختلفة.
feedPollDelay (اختياري) الوقت (بالمللي ثانية) للتأخير بين الاستقصاء عن قسم للتغييرات الجديدة على الخلاصة، بعد أن يتم تجفيف كافة التغييرات الحالية. الافتراضي هو 5000 مللي ثانية أو 5 ثوان.
leaseAcquireInterval (اختياري) عند تعيينها، فإنه يعرف، في ميلي ثانية، الفاصل الزمني لبدء مهمة لحساب إذا تم توزيع الأقسام بالتساوي بين مثيلات المضيف المعروفة. الافتراضي هو 13000 (13 ثانية).
leaseExpirationInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، الفترة الزمنية التي يتم أخذ التأجير من أجلها على عقد إيجار يمثل قسمًا. إذا لم يتم تجديد عقد الإيجار خلال هذا الفاصل الزمني، فستنتهي صلاحيته وتنتقل ملكية القسم إلى مثيل آخر. الافتراضي هو 60000 (60 ثانية).
leaseRenewInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، فترة التجديد لكافة عقود الإيجار للأقسام الموجودة حاليا بواسطة مثيل. الافتراضي هو 17000 (17 ثانية).
maxItemsPerInvocation (اختياري) عند تعيين هذه الخاصية تعيين الحد الأقصى لعدد العناصر المتلقاة لكل استدعاء دالة. إذا تم تنفيذ العمليات في حاوية المراقبة من خلال الإجراءات المخزنة، يتم الاحتفاظ بنطاق المعاملة عند قراءة العناصر من موجز التغيير. ونتيجة لذلك، قد يكون عدد العناصر المتلقاة أعلى من القيمة المحددة بحيث يتم إرجاع العناصر التي تم تغييرها بواسطة نفس المعاملة كجزء من دفعة ذرية واحدة.
startFromBeginning (اختياري) يخبر هذا الخيار المشغل قراءة التغييرات من بداية محفوظات التغيير للحاوية بدلًا من البدء في الوقت الحالي. القراءة من البداية يعمل فقط في المرة الأولى التي يبدأ فيها المشغل، كما هو الحال في التشغيلات اللاحقة، يتم تخزين نقاط التفتيش بالفعل. وتعيين هذا الخيار إلى true عندما يكون هناك عقود إيجار تم إنشاؤها بالفعل ليس له أي تأثير.
preferredLocations (اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافياً في خدمة Azure Cosmos DB. يجب فصل القيم بفاصلة. على سبيل المثال، "شرق الولايات المتحدة، جنوب وسط الولايات المتحدة، شمال أوروبا".

التكوين

ينطبق فقط على نموذج برمجة Python v1.

يوضح الجدول التالي الخصائص التي يمكنك تعيينها على الكائن الذي options تم تمريره app.cosmosDB() إلى الأسلوب . typedirectionلا تنطبق الخصائص و و name على نموذج v4.

يشرح الجدول التالي خصائص تكوين الرابط التي قمت بتعيينها في الملف function.json، حيث تختلف الخصائص حسب إصدار الملحق:

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى cosmosDBTrigger.
الاتجاه يجب تعيينه إلى in. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء المشغل في مدخل Azure.
الاسم اسم المتغير المستخدم في رمز الدالة الذي يمثل قائمة المستندات ذات التغييرات.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي تتم مراقبته. لمزيد من المعلومات، راجع الاتصالات.
databaseName اسم قاعدة بيانات Azure Cosmos DB مع الحاوية التي يتم مراقبتها.
containerName اسم الحاوية التي يتم مراقبتها.
leaseConnection (اختياري) اسم إعداد تطبيق أو حاوية إعداد تحدد كيفية الاتصال بحساب Azure Cosmos DB الذي يحتوي على حاوية التأجير.

عند عدم التعيين، تُستخدم القيمة connection. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في المدخل. يجب أن يكون لسلسلة الاتصال لحاوية التأجير أذونات الكتابة.
leaseDatabaseName (اختياري) اسم قاعدة البيانات التي تحتوي على الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم قيمة الإعداد databaseName.
leaseContainerName (اختياري) اسم الحاوية المستخدمة لتخزين عقود الإيجار. عند عدم التعيين، تُستخدم القيمة leases.
createLeaseContainerIfNotExists (اختياري) عند تعيينها إلى true، يتم إنشاء حاوية عقود الإيجار تلقائيًّا عندما لا تكون موجودة بالفعل. القيمة الافتراضية هي false. عند استخدام هويات Microsoft Entra إذا قمت بتعيين القيمة إلى true، فإن إنشاء حاويات ليس عملية مسموحا بها ولن تتمكن الدالة من البدء.
leasesContainerThroughput (اختياري) تعريف عدد وحدات الطلب لتعيينها عند إنشاء حاوية التأجيرات. يتم استخدام هذا الإعداد فقط عند تعيين createLeaseContainerIfNotExists إلى true. يتم تعيين هذه المعلمة تلقائيا عند إنشاء الربط باستخدام المدخل.
leaseContainerPrefix (اختياري) عند تعيين القيمة، تتم إضافتها كبادئة لعقود الإيجار التي تم إنشاؤها في حاوية التأجير لهذه الدالة. يسمح استخدام بادئة دالتين Azure منفصلة مشاركة نفس حاوية Lease باستخدام بادئات مختلفة.
feedPollDelay (اختياري) الوقت (بالمللي ثانية) للتأخير بين الاستقصاء عن قسم للتغييرات الجديدة على الخلاصة، بعد أن يتم تجفيف كافة التغييرات الحالية. الافتراضي هو 5000 مللي ثانية أو 5 ثوان.
leaseAcquireInterval (اختياري) عند تعيينها، فإنه يعرف، في ميلي ثانية، الفاصل الزمني لبدء مهمة لحساب إذا تم توزيع الأقسام بالتساوي بين مثيلات المضيف المعروفة. الافتراضي هو 13000 (13 ثانية).
leaseExpirationInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، الفترة الزمنية التي يتم أخذ التأجير من أجلها على عقد إيجار يمثل قسمًا. إذا لم يتم تجديد التأجير ضمن هذه الفترة الزمنية، فإنه يؤدي إلى انتهاء صلاحية وملكية القسم سينتقل إلى مثيل آخر. الافتراضي هو 60000 (60 ثانية).
leaseRenewInterval (اختياري) عند تعيينها، تعرف، بالمللي ثانية، فترة التجديد لكافة عقود الإيجار للأقسام الموجودة حاليا بواسطة مثيل. الافتراضي هو 17000 (17 ثانية).
maxItemsPerInvocation (اختياري) عند تعيين هذه الخاصية تعيين الحد الأقصى لعدد العناصر المتلقاة لكل استدعاء دالة. إذا تم تنفيذ العمليات في حاوية المراقبة من خلال الإجراءات المخزنة، يتم الاحتفاظ بنطاق المعاملة عند قراءة العناصر من موجز التغيير. ونتيجة لذلك، قد يكون عدد العناصر المتلقاة أعلى من القيمة المحددة بحيث يتم إرجاع العناصر التي تم تغييرها بواسطة نفس المعاملة كجزء من دفعة ذرية واحدة.
startFromBeginning (اختياري) يخبر هذا الخيار المشغل قراءة التغييرات من بداية محفوظات التغيير للحاوية بدلًا من البدء في الوقت الحالي. القراءة من البداية يعمل فقط في المرة الأولى التي يبدأ فيها المشغل، كما هو الحال في التشغيلات اللاحقة، يتم تخزين نقاط التفتيش بالفعل. وتعيين هذا الخيار إلى true عندما يكون هناك عقود إيجار تم إنشاؤها بالفعل ليس له أي تأثير.
startFromTime (اختياري) الحصول على التاريخ والوقت أو تعيينهما لتهيئة عملية قراءة موجز التغيير. التنسيق الموصى به هو ISO 8601 مع المعين UTC، مثل 2021-02-16T14:19:29Z. يتم استخدام هذا فقط لتعيين حالة المشغل الأولي. بعد أن يكون للمشغل حالة تأجير، لا يكون لتغيير هذه القيمة أي تأثير.
preferredLocations (اختياري) يعرف المواقع المفضلة (المناطق) لحسابات قاعدة البيانات المنسوخة جغرافياً في خدمة Azure Cosmos DB. يجب فصل القيم بفاصلة. على سبيل المثال، "شرق الولايات المتحدة، جنوب وسط الولايات المتحدة، شمال أوروبا".

راجع قسم Example للحصول على أمثلة كاملة.

الاستخدام

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

هام

إذا تم تكوين دوال متعددة لاستخدام مشغل Azure Cosmos DB لنفس المجموعة، يجب أن تستخدم كل دالة مجموعة تأجير مخصصة أو تحدد مختلفة LeaseCollectionPrefix لكل دالة. وإلا، يتم تشغيل واحد فقط من الدالات. للحصول على معلومات حول البادئة، راجع قسم السمات.

هام

إذا تم تكوين دوال متعددة لاستخدام مشغل Azure Cosmos DB لنفس المجموعة، يجب أن تستخدم كل دالة مجموعة تأجير مخصصة أو تحدد مختلفة leaseCollectionPrefix لكل دالة. وإلا، يتم تشغيل واحد فقط من الدالات. للحصول على معلومات حول البادئة، راجع قسم التعليقات التوضيحية.

هام

إذا تم تكوين دوال متعددة لاستخدام مشغل Azure Cosmos DB لنفس المجموعة، يجب أن تستخدم كل دالة مجموعة تأجير مخصصة أو تحدد مختلفة leaseCollectionPrefix لكل دالة. وإلا، سيتم تشغيل واحد فقط من الدالات. للحصول على معلومات حول البادئة، راجع قسم التكوين.

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

يعتمد نوع المعلمة الذي يدعمه مشغل Azure Cosmos DB على إصدار وقت تشغيل الوظائف وإصدار حزمة الملحق وصيغة C# المستخدمة.

عندما تريد أن تعالج الدالة مستندا واحدا، يمكن ربط مشغل Cosmos DB بالأنواع التالية:

النوع ‏‏الوصف
‏‏أنواع قابلة للتسلسل إلى JSON تحاول الدالات إلغاء تسلسل بيانات JSON للمستند من موجز تغيير Cosmos DB إلى نوع كائن CLR (POCO) قديم عادي.

عندما تريد أن تعالج الدالة دفعة من المستندات، يمكن أن يرتبط مشغل Cosmos DB بالأنواع التالية:

النوع ‏‏الوصف
IEnumerable<T>حيث T هو نوع JSON قابل للتسلسل تعداد للكيانات المضمنة في الدفعة. يمثل كل إدخال مستندا واحدا من موجز تغيير Cosmos DB.

الاتصالات

الخصائص connectionStringSetting/connection وleaseConnectionStringSetting/leaseConnection هي مراجع لتكوين البيئة الذي يحدد كيفية اتصال التطبيق بـAzure Cosmos DB. يمكنهم تحديد:

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

سلسلة الاتصال

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

الاتصالات القائمة على الهوية

إذا كنت تستخدم الإصدار 4.x أو أعلى من الملحق، فبدلا من استخدام سلسلة الاتصال مع سر، يمكنك أن يكون التطبيق يستخدم هوية Microsoft Entra. للقيام بذلك، يمكنك تعريف الإعدادات ضمن بادئة شائعة تعين خاصية الاتصال في تكوين المشغل والربط.

في هذا الوضع، يتطلب الملحق الخصائص التالية:

الخاصية قالب متغير البيئة ‏‏الوصف مثال للقيمة
نقطة نهاية الحساب <CONNECTION_NAME_PREFIX>__accountEndpoint نقطة نهاية حساب Azure Cosmos DB URI. https://<database_account_name>.documents.azure.com:443/

قد يتم تعيين خصائص إضافية لتخصيص الاتصال. راجع الخصائص الشائعة للاتصالات المعتمدة على الهوية.

عند استضافتها في خدمة Azure Functions، تستخدم الاتصالات المستندة إلى الهوية هوية مدارة. تستخدم الهوية المعينة من قبل النظام بشكل افتراضي على الرغم من إمكانية تحديد هوية معينة من قبل المستخدم مع خصائص credential و clientID. لاحظ أن تكوين هوية معينة من المستخدم باستخدام معرف مورد غير معتمد. عند التشغيل في سياقات أخرى، مثل التنمية المحلية، يتم استخدام هوية المطور الخاصة بك بدلًا من ذلك، على الرغم من أنه يمكن تخصيصها. راجع التطوير المحلي من خلال الاتصالات القائمة على الهوية.

منح الإذن للهوية

مهما كانت الهوية المستخدمة يجب أن يكون لديك أذونات لتنفيذ الإجراءات المقصودة. بالنسبة لمعظم خدمات Azure، يعني هذا أنك بحاجة إلى تعيين دور في Azure RBAC، باستخدام أدوار مضمنة أو مخصصة توفر هذه الأذونات.

هام

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

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

نوع الربط مثال على الأدوارالمضمنة 1
المشغل2 مساهم البيانات المضمن في Cosmos DB
ربط بيانات الإدخال قارئ البيانات المضمن في Cosmos DB
ربط بيانات الإخراج مساهم البيانات المضمن في Cosmos DB

1 لا يمكن استخدام هذه الأدوار في تعيين دور Azure RBAC. راجع وثائق نظام التحكم في الوصول استنادا إلى الدور المضمن في Cosmos DB للحصول على تفاصيل حول كيفية تعيين هذه الأدوار.

2 عند استخدام الهوية، يتعامل Cosmos DB مع إنشاء الحاوية على أنها عملية إدارة. لا يتوفر كلعملية مستوى بيانات للمشغل. ستحتاج إلى التأكد من إنشاء الحاويات التي يحتاجها المشغل (بما في ذلك حاوية التأجير) قبل إعداد وظيفتك.

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