مشغل تخزين Azure Queue والروابط لنظرة عامة على وظائف Azure

يمكن تشغيل وظائف Azure مع إنشاء رسائل تخزين جديدة بـ Azure Queue، كما يمكن كتابة رسائل قائمة الانتظار داخل دالة.

الإجراء	نوع
تشغيل الدالة كتغييرات في بيانات تخزين قائمة الانتظار	المشغِّل
كتابة رسائل تخزين قائمة الانتظار	ربط الإخراج

تثبيت الملحق

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

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

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

تختلف وظيفة الملحق باختلاف إصدار الملحق:

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

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

يسمح هذا الإصدار بربط الأنواع منAzure.Storage.Blobs.

هذا الملحق متوفر من خلال تثبيت حزمةMicrosoft.Azure.WebJobs.Extensions.Storage.Blobs NuGet، الإصدار 5.x.

استخدام .NET CLI:

dotnet add package Microsoft.Azure.WebJobs.Extensions.Storage.Queues

إشعار

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

شُحنت الملحقات سلفاً معاً على أنهاMicrosoft.Azure.WebJobs.Extensions.Storage، الإصدار 4.x. تحتوي هذه الحزمة ذاتها أيضاً علىالإصدار 5.x، والذي يشير إلى الحِزم المنقسمة للعناصر الثنائية كبيرة الحجم وقوائم الانتظار فقط. عند ترقية مراجع الحزمة المتعلقة بك من الإصدارات الأقدم، قد تحتاج للرجوع إلى الحزمة الجديدةMicrosoft.Azure.WebJobs.Extensions.TablesNuGet. أيضاً، عند الرجوع إلى هذه الحزم المقسمة الأحدث، تأكد من أنك لا تشير إلى إصدار أقدم من حزمة التخزين المدمجة، لأن هذا سيؤدي إلى تعارضات من تعريفين لنفس الارتباطات.

يسمح هذا الإصدار بربط الأنواع منAzure.Storage.Blobs.

يدعم هذا الإصدار تكوين المشغلات والروابط من خلال تكامل .NET Aspire.

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

استخدام .NET CLI:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

إشعار

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

في السابق، تم شحن الملحقات معا ك Microsoft.Azure.Functions.Worker.Extensions.Storage، الإصدار 4.x. تحتوي هذه الحزمة ذاتها أيضاً علىالإصدار 5.x، والذي يشير إلى الحِزم المنقسمة للعناصر الثنائية كبيرة الحجم وقوائم الانتظار فقط. عند ترقية مراجع الحزمة من الإصدارات القديمة، قد تحتاج بالتالي إلى الرجوع إلى حزمة NuGet الجديدة Microsoft.Azure.Functions.Worker.Extensions.Tables . أيضاً، عند الرجوع إلى هذه الحزم المقسمة الأحدث، تأكد من أنك لا تشير إلى إصدار أقدم من حزمة التخزين المدمجة، لأن هذا سيؤدي إلى تعارضات من تعريفين لنفس الارتباطات.

تثبيت الحزمة

لكي تتمكن من استخدام ملحق الربط هذا في تطبيقك، تأكد من أن ملف 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.

أنواع الربط

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

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

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

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

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

سيناريو الربط	أنواع المعلمات
مشغِّل قائمة الانتظار	رسالة قائمة الانتظار أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]` بيانات ثنائية
إخراج قائمة الانتظار (رسالة واحدة)	رسالة قائمة الانتظار أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]` بيانات ثنائية
إخراج قائمة الانتظار (رسائل متعددة)	QueueClient `ICollector<T>` أو `IAsyncCollector<T>` أين `T` هو أحد أنواع الرسائل الفردية

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

تعرض الإصدارات السابقة من الملحق الأنواع من مساحة الاسم Microsoft.Azure.Storage.Queues المهملة الآن. الأنواع الأحدث من Azure.Storage.Queues حصرية للملحق 5.x+.

يدعم هذا الإصدار من الملحق أنواع المعلمات وفقا للجدول أدناه.

سيناريو الربط	أنواع المعلمات
مشغِّل قائمة الانتظار	رسالة قائمة انتظار السحابة أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]`
إخراج قائمة الانتظار	رسالة قائمة انتظار السحابة أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]` CloudQueue

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

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

مشغل قائمة الانتظار

يمكن ربط مشغل قائمة الانتظار بالأنواع التالية:

نوع	‏‏الوصف
`string`	محتوى الرسالة كسلسلة. استخدم عندما تكون الرسالة نصا بسيطا.
`byte[]`	وحدات البايت للرسالة.
‏‏أنواع قابلة للتسلسل إلى JSON	عندما تحتوي رسالة قائمة الانتظار على بيانات JSON، تحاول الدالات إلغاء تسلسل بيانات JSON إلى نوع كائن CLR (POCO) قديم عادي.
QueueMessage¹	الرسالة.
BinaryData¹	وحدات البايت للرسالة.

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

ربط إخراج قائمة الانتظار

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

نوع	‏‏الوصف
`string`	محتوى الرسالة كسلسلة. استخدم عندما تكون الرسالة نصاً بسيطاً.
`byte[]`	وحدات البايت للرسالة.
‏‏أنواع قابلة للتسلسل إلى JSON	كائن يمثل محتوى رسالة JSON. تحاول الدالات تسلسل نوع كائن CLR (POCO) قديم عادي في بيانات JSON.

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

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

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

إعدادات host.json

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

إشعار

للحصول على مرجع لـ host.json في دالات 1.x، راجع مرجع host.json لوظائفAzure 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}

الخاصية	الإعداد الافتراضي	‏‏الوصف
الحد الأقصى لPollingInterval	00:01:00	الفاصل الزمني الأقصى بين استطلاعات قائمة الانتظار. الفاصل الزمني الأدنى هو 00:00:00.100 (100 مللي ثانية). زيادة الفواصل الزمنية حتى `maxPollingInterval`. القيمة الافتراضية هي `maxPollingInterval` 00:01:00 (دقيقة واحدة). `maxPollingInterval` يجب ألا يقل عن 00:00:00.100 (100 مللي ثانية). في Functions 2.x والإحدث، يكون نوع البيانات هو `TimeSpan`. في الدالات 1.x، تكون بالمللي ثانية.
مهلة الرؤية	00:00:00	الفاصل الزمني بين إعادة المحاولة عند فشل معالجة الرسالة.
حجم الدفعات	16	عدد رسائل قائمة الانتظار التي يقوم وقت تشغيل الدالات باستردادها في وقت واحد، ومعالجتها بالتوازي. عندما يصل الرقم الذي تتم معالجته إلى `newBatchThreshold`، يحصل وقت التشغيل على دفعة أخرى ويبدأ معالجة هذه الرسائل. لذا فإن الحد الأقصى لعدد الرسائل المتزامنة التي تتم معالجتها لكل وظيفة هو `batchSize` زائد `newBatchThreshold`. ينطبق هذا الحد بشكل منفصل على كل دالة تُشغلها قائمة انتظار. إذا كنت تريد تجنب التنفيذ الموازي للرسائل المتلقاة في قائمة انتظار واحدة، يمكنك تعيين `batchSize` إلى 1. ومع ذلك، يلغي هذا الإعداد التزامن طالما يعمل تطبيق الوظيفة على جهاز ظاهري (VM) واحد فقط. إذا توسع تطبيق الوظيفة لأكثر من جهاز ظاهري، يمكن لكل جهاز ظاهري أن يُشغل مثيل واحد من كل وظيفة تُشغلها قائمة الانتظار. الحد الأقصى لـ `batchSize` هو 32.
maxDequeueCount	5	عدد المرات التي يجب فيها محاولة معالجة إحدى الرسائل قبل نقلها إلى قائمة انتظار الإزالة.
newBatchThreshold	N*حجم الدفعة/ 2	كلما نقص عدد الرسائل التي تتم معالجتها بشكل متزامن وصولاً لهذا الرقم، يقوم وقت التشغيل باسترداد دفعة أخرى. `N` يمثل عدد وحدات vCPUs المتوفرة عند التشغيل على App Service أو Premium Plans. قيمته هي `1` لخطة الاستهلاك.
ترميز الرسالة	قاعدة 64	يتوفر هذا الإعداد فقط في مجموعة الملحقات الإصدار 5.0.0 والإصدارات الأحدث. ويمثل تنسيق الترميز للرسائل. القيم الصالحة هي `base64` و `none`.

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

الملاحظات

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

Last updated on 2025-08-18

مشاركة عبر

مشغل تخزين Azure Queue والروابط لنظرة عامة على وظائف Azure

تثبيت الملحق

تثبيت الحزمة

أنواع الربط

إعدادات host.json

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

الملاحظات

الموارد الإضافية