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

• الإصدار 1
• الإصدار 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# الذي تستخدمه في تطبيق الوظائف:

نموذج عامل معزول

يتم تنفيذ الوظائف في عملية عامل C# معزولة. لمعرفة المزيد، راجع دليل تشغيل وظائف C# Azure في عملية عامل معزولة.

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

هام

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

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

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

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

Extension 4.x+

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

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

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

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

الدوال 2.x+

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

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

Extension 4.x+

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

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

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

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

الدوال 2.x+

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

تثبيت الحزمة

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

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

حزمة v4.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)"
  }
}

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

Bundle v2.x and v3.x

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

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

أنواع الربط

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

نموذج عامل معزول

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

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

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

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

Extension 4.x+

يدعم ملحق 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).

الدوال 2.x+

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

Extension 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 قابل للتسلسل	تعداد للكيانات التي تم إرجاعها بواسطة الاستعلام. يمثل كل إدخال مستندا واحدا.
CosmosClient1	عميل متصل بحساب Cosmos DB.
قاعدة البيانات1	عميل متصل بقاعدة بيانات Cosmos DB.
الحاوية1	عميل متصل بحاوية 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.

الدوال 2.x+

تدعم الإصدارات السابقة من الملحقات في عملية العامل المعزولة الربط فقط بالأنواع القابلة للتسلسل JSON. تتوفر خيارات إضافية للملحق 4.x والإضافات.

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

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+

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

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

الدوال 2.x+

{
    "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	غير متوفر	بادئة التأجير لاستخدامها عبر جميع الوظائف في التطبيق.

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

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