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

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

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

هام

يدعم هذا الإصدار من ملحق ربط Azure Cosmos DB الإصدار 4.x من Azure Functions. إذا كان تطبيقك لا يزال يستخدم الإصدار 1.x من وقت تشغيل الوظائف، فشاهد بدلا من ذلك روابط Azure Cosmos DB ل Azure Functions 1.x. في وقت تشغيل Functions v1.x، تمت تسمية DocumentDBهذا الربط في الأصل .

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

يشير هذا الجدول إلى كيفية الاتصال بواجهات برمجة تطبيقات Azure Cosmos DB المختلفة من التعليمات البرمجية للدالة:

API	التوصية
قاعدة بيانات Azure Cosmos لـ NoSQL	استخدام ملحق ربط Azure Cosmos DB
قاعدة بيانات Azure Cosmos لـ MongoDB	استخدم SDK عميل أصلي.
Azure Cosmos DB للجدول	استخدم الإصدار 5.x أو أحدث من ملحق ربط جداول Azure.
Azure Cosmos DB ل Apache Cassandra	استخدم SDK عميل أصلي.
Azure Cosmos DB ل Apache Gremlin (Graph API)	استخدام SDK عميل أصلي
قاعدة بيانات Azure Cosmos لـ PostgreSQL	استخدم SDK عميل أصلي.

تثبيت الملحق

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

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

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

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

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

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

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

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

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

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

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

تثبيت الحزمة

لكي تتمكن من استخدام ملحق الربط هذا في تطبيقك، تأكد من أن ملف host.json في جذر مشروعك يحتوي على هذا extensionBundle المرجع:

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

في هذا المثال، version ترشد قيمة [4.0.0, 5.0.0) مضيف الوظائف إلى استخدام إصدار حزمة على الأقل 4.0.0 ولكن أقل من 5.0.0، والذي يتضمن جميع الإصدارات المحتملة من 4.x. يحافظ هذا النص بشكل فعال على تطبيقك على أحدث إصدار ثانوي متوفر من مجموعة ملحقات v4.x.

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

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

أنواع الربط

تعتمد أنواع الربط المعتمدة ل .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.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.

أنواع ربط SDK

دعم نوع SDK ل Azure Cosmos قيد المعاينة. اتبع روابط Python SDK لعينة CosmosDB لبدء استخدام أنواع SDK ل Cosmos في Python.

هام

يتطلب استخدام روابط نوع SDK نموذج برمجة Python v2.

الربط	أنواع المعلمات	العينات
إدخال CosmosDB	ContainerProxy، CosmosClient، DatabaseProxy	`ContainerProxy`, `CosmosClient`, `DatabaseProxy`

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

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

إعدادات host.json

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

الامتداد 4.x+
الدوال 2.x+

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

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

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

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-09-22