Azure Cosmos DB المشغل والروابط ل وظائف Azure 2.x ونظرة عامة أعلى

مقالة
٠٧‏/٠٥‏/١٤٤٥ هـ

توضح هذه المقالة كيفية العمل مع روابط AZURE Cosmos DB في دالات Azure. تدعم دالات Azure روابط المشغل والإدخال والإخراج لـ Azure Cosmos DB.

الإجراء	نوع
تشغيل دالة عند إنشاء مستند Azure Cosmos DB أو تعديله	المشغِّل
قراءة مستند Azure Cosmos DB	ربط الإدخال
حفظ التغييرات على مستند Azure Cosmos DB	ربط الإخراج

ملاحظة

هذا المرجع هو لوظائف Azure والإصدار 2.x وأعلى. للحصول على معلومات حول كيفية استخدام هذه الروابط في الدالات 1.x فالأحدث، راجع روابط Azure Cosmos DB لدالات Azure 1.x.

يُطلق على هذا الرابط في الأصل DocumentDB. في الإصدار 2.x من Azure Functions والإصدارات الأحدث، يطلق على المشغل والروابط والحزمة اسم Azure Cosmos DB.

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

يتم دعم روابط Azure Cosmos DB فقط للاستخدام مع Azure Cosmos DB ل NoSQL. يتم توفير دعم Azure Cosmos DB للجدول باستخدام روابط تخزين الجدول، بدءا من الملحق 5.x. بالنسبة لجميع واجهات برمجة تطبيقات Azure Cosmos DB الأخرى، يجب عليك الوصول إلى قاعدة البيانات من دالتك باستخدام العميل الثابت لواجهة برمجة التطبيقات الخاصة بك، بما في ذلك Azure Cosmos DB ل MongoDB وAzure Cosmos DB ل Cassandra وAzure Cosmos DB ل Apache Gremlin.

تثبيت الملحق

تعتمد حزمة NuGet الملحق التي تقوم بتثبيتها على وضع C# الذي تستخدمه في تطبيق الوظائف:

نموذج عامل معزول
نموذج قيد المعالجة

هام

سينتهي الدعم للنموذج قيد التنفيذ في 10 نوفمبر 2026. نوصي بشدة بترحيل تطبيقاتك إلى نموذج العامل المعزول للحصول على الدعم الكامل.

يتم تنفيذ الوظائف في نفس العملية مثل مضيف الوظائف. لمعرفة المزيد، راجع تطوير دالات مكتبة الفئة C# باستخدام وظائف Azure.

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

تختلف عملية تثبيت الملحق حسب إصدار الملحق:

يصف هذا القسم استخدام مكتبة فئات. بالنسبة إلى البرمجة النصية C#، ستحتاج بدلا من ذلك إلى تثبيت مجموعة الملحقات، الإصدار 4.x.

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

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

يتوفر إصدار الملحق هذا كحزمة NuGet، الإصدار 4.x.

يصف هذا القسم استخدام مكتبة فئات. بالنسبة إلى البرمجة النصية C#، ستحتاج بدلا من ذلك إلى تثبيت حزمة الملحقات، الإصدار 2.x أو 3.x.

يتطلب العمل مع المشغل والارتباطات الرجوع إلى حزمة NuGet المناسبة. تثبيت حزمة NuGet، الإصدار 3.x.

أضف الملحق إلى مشروعك عن طريق تثبيت حزمة NuGet، الإصدار 4.x.

إذا كنت تكتب تطبيقك باستخدام F#، فيجب عليك أيضا تكوين هذا الملحق كجزء من تكوين بدء تشغيل التطبيق. في الاستدعاء إلى ConfigureFunctionsWorkerDefaults() أو ConfigureFunctionsWebApplication()، أضف مفوضا يأخذ معلمة IFunctionsWorkerApplication . ثم داخل نص هذا المفوض، استدع ConfigureCosmosDBExtension() على الكائن :

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

تثبيت الحزمة

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

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

حزمة v4.x
Bundle v2.x and v3.x

يحتوي هذا الإصدار من الحزمة على الإصدار 4.x من ملحق روابط Azure Cosmos DB الذي يقدم القدرة على الاتصال باستخدام هوية بدلا من سر. للحصول على برنامج تعليمي حول تكوين تطبيقات الوظائف الخاصة بك باستخدام الهويات المُدارة، راجع البرنامج التعليمي لإنشاء تطبيق وظائف باستخدام الاتصالات المستندة إلى الهوية.

يمكنك إضافة هذا الإصدار من الملحق من الإصدار الرابع من معاينة مجموعة الملحق عن طريق إضافة أو استبدال التعليمة البرمجية التالية في الملف host.json:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

لمعرفة المزيد، راجع تحديث الإضافات.

يمكنك تثبيت هذا الإصدار من الملحق في تطبيق الوظائف الخاص بك عن طريق تسجيل مجموعة الملحقات، الإصدار 2.x أو 3.x.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

أنواع الربط

تعتمد أنواع الربط المعتمدة ل .NET على كل من إصدار الملحق ووضع تنفيذ C#، والتي يمكن أن تكون واحدة مما يلي:

نموذج عامل معزول
نموذج قيد المعالجة

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

اختر إصدارا للاطلاع على تفاصيل نوع الربط للوضع والإصدار.

يدعم ملحق Azure Cosmos DB أنواع المعلمات وفقا للجدول أدناه.

سيناريو الربط	أنواع المعلمات
مشغل Cosmos DB (مستند واحد)	أنواع^{JSON القابلة للتسلسل 1}
مشغل Cosmos DB (دفعة من المستندات)	`IEnumerable<T>`حيث `T` هو نوع^{JSON قابل للتسلسل 1}
إدخال Cosmos DB (مستند واحد)	أنواع^{JSON القابلة للتسلسل 1}
إدخال Cosmos DB (استعلام يرجع مستندات متعددة)	CosmosClient `IEnumerable<T>` حيث `T` هو نوع^{JSON قابل للتسلسل 1}
إخراج Cosmos DB (مستند واحد)	أنواع^{JSON القابلة للتسلسل 1}
إخراج Cosmos DB (مستندات متعددة)	`ICollector<T>` أو `IAsyncCollector<T>` أين `T` هو نوع^{JSON القابل للتسلسل 1}

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

تعرض الإصدارات السابقة من الملحق أنواعا من مساحة اسم Microsoft.Azure.Documents المهملة الآن. الأنواع الأحدث من Microsoft.Azure.Cosmos حصرية للملحق 4.x وأعلى.

تدعم عملية العامل المعزولة أنواع المعلمات وفقا للجداول أدناه. دعم الربط بالأنواع من Microsoft.Azure.Cosmos قيد المعاينة.

مشغل Cosmos DB

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

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

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

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

ربط إدخال Cosmos DB

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

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

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

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

¹ لاستخدام هذه الأنواع، تحتاج إلى الرجوع إلى Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 أو أحدث والتبعيات الشائعة لروابط نوع SDK.

ربط إخراج Cosmos DB

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

النوع	‏‏الوصف
‏‏أنواع قابلة للتسلسل إلى JSON	كائن يمثل محتوى JSON لمستند. تحاول الدالات تسلسل نوع كائن CLR (POCO) قديم عادي في بيانات JSON.

عندما تريد أن تكتب الدالة إلى مستندات متعددة، يمكن ربط إخراج Cosmos DB بالأنواع التالية:

النوع	‏‏الوصف
`T[]` أين `T` هو نوع JSON القابل للتسلسل	صفيف يحتوي على مستندات متعددة. يمثل كل إدخال مستندا واحدا.

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

الاستثناءات والتعليمات البرمجية للإرجاع

Binding	المرجع
Azure Cosmos DB	رموز حالة HTTP لـ Azure Cosmos DB

إعدادات host.json

يصف هذا القسم إعدادات التكوين المتاحة لهذا الربط في الإصدارات 2.x وأعلى. تنطبق الإعدادات في ملف host.json على جميع الوظائف في مثيل تطبيق الوظائف. يحتوي مثال ملف host.json أدناه على إعدادات الإصدار 2.x + فقط لهذا الربط. للحصول على مزيدٍ من المعلومات عن إعدادات تكوين التطبيق الوظيفي في الإصدارات 2.x والإصدارات الأحدث، راجع مرجع host.json لوظائف Azure.

Extension 4.x+
الدوال 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

الخاصية	Default	‏‏الوصف
connectionMode	`Gateway`	وضع الاتصال المستخدم من قبل الدالة عند الاتصال بخدمة Azure Cosmos DB. الخيارات هي `Direct` و`Gateway`
userAgentSuffix	غير متوفر	إضافة قيمة السلسلة المحددة إلى جميع الطلبات التي تم إجراؤها بواسطة المشغل أو الربط بالخدمة. وهذا يسهل عليك تعقب النشاط في Azure Monitor، استنادا إلى تطبيق وظيفة معين والتصفية حسب `User Agent`.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

الخاصية	Default	‏‏الوصف
connectionMode	`Gateway`	وضع الاتصال المستخدم من قبل الدالة عند الاتصال بخدمة Azure Cosmos DB. الخيارات هي `Direct` و`Gateway`
بروتوكول	`Https`	بروتوكول الاتصال المستخدم من قبل الدالة عند الاتصال بخدمة Azure Cosmos DB. اقرأ هنا للحصول على شرح لكلا الوضعين.
leasePrefix	غير متوفر	بادئة التأجير لاستخدامها عبر جميع الوظائف في التطبيق.

مشاركة عبر