مشغل مراكز الأحداث في Azure وعمليات ربط لوظائف Azure

مقالة
07/12/2023

توضح هذه المقالة كيفية العمل مع روابط مراكز الأحداث في Azure لوظائف Azure. تدعم Azure Functions روابط المشغل والمخرجات لمراكز الأحداث.

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

تثبيت الملحق

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

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

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

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

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

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

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

تثبيت الحزمة

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

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

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

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

أنواع الربط

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

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

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

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

يدعم ملحق مراكز الأحداث أنواع المعلمات وفقا للجدول أدناه.

سيناريو الربط	أنواع المعلمات
مشغل مراكز الأحداث (حدث واحد)	Azure.Messaging.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]` [بيانات ثنائية]
مشغل مراكز الأحداث (دفعة من الأحداث)	`EventData[]` `string[]`
إخراج مراكز الأحداث (حدث واحد)	Azure.Messaging.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]` [بيانات ثنائية]
إخراج مراكز الأحداث (أحداث متعددة)	`ICollector<T>` أو `IAsyncCollector<T>` أين `T` هو أحد أنواع الأحداث الفردية

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

تعرض الإصدارات السابقة من الملحق الأنواع من مساحة اسم Microsoft.Azure.EventHubs المهملة الآن. الأنواع الأحدث من Azure.Messaging.EventHubs حصرية ل Extension v5.x+.

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

سيناريو الربط	أنواع المعلمات
مشغل مراكز الأحداث (رسالة واحدة)	Microsoft.Azure.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]`
مشغل مراكز الأحداث (دفعة)	`EventData[]` `string[]`
إخراج مراكز الأحداث	Microsoft.Azure.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]`

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

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

سيناريو الربط	أنواع المعلمات
مشغل مراكز الأحداث (حدث واحد)	Microsoft.Azure.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]`
مشغل مراكز الأحداث (دفعة من الأحداث)	`EventData[]` `string[]`
إخراج مراكز الأحداث	Microsoft.Azure.EventHubs.EventData أنواع^{JSON القابلة للتسلسل 1} `string` `byte[]`

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

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

مشغل مراكز الأحداث

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

النوع	‏‏الوصف
`string`	الحدث كسلسلة. استخدم عندما يكون الحدث نصا بسيطا.
`byte[]`	وحدات بايت الحدث.
‏‏أنواع قابلة للتسلسل إلى JSON	عندما يحتوي حدث على بيانات JSON، تحاول الدالات إلغاء تسلسل بيانات JSON إلى نوع كائن CLR (POCO) قديم عادي.
Azure.Messaging.EventHubs.EventData¹	كائن الحدث. إذا كنت تقوم بالترحيل من أي إصدارات قديمة من Event Hubs SDKs، فلاحظ أن هذا الإصدار يسقط الدعم للنوع القديم `Body` لصالح EventBody.

عندما تريد أن تعالج الدالة دفعة من الأحداث، يمكن أن يرتبط مشغل مراكز الأحداث بالأنواع التالية:

النوع	‏‏الوصف
`string[]`	صفيف من الأحداث من الدفعة، كسلاسل. يمثل كل إدخال حدثا واحدا.
`EventData[]`¹	صفيف من الأحداث من الدفعة، كمثيلات Azure.Messaging.EventHubs.EventData. يمثل كل إدخال حدثا واحدا.
`T[]` حيث `T` هو نوع^{JSON قابل للتسلسل 1}	صفيف من الأحداث من الدفعة، كمثيلات لنوع POCO مخصص. يمثل كل إدخال حدثا واحدا.

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

ربط إخراج مراكز الأحداث

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

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

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

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

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

إعدادات host.json

يحتوي ملف host.json على الإعدادات التي تتحكم في سلوك مشغل مراكز الأحداث. يختلف التكوين حسب إصدار الملحق.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}

الخاصية	Default	‏‏الوصف
maxEventBatchSize²	100	الحد الأقصى لعدد الأحداث المضمنة في دفعة استدعاء واحد. يجب أن يكون على الأقل 1.
minEventBatchSize¹	1	الحد الأدنى لعدد الأحداث المطلوبة في دفعة واحدة. ينطبق الحد الأدنى فقط عندما تتلقى الدالة أحداثا متعددة ويجب أن تكون أقل من `maxEventBatchSize`. الحد الأدنى للحجم غير مضمون بشكل صارم. يتم إرسال دفعة جزئية عندما لا يمكن إعداد دفعة كاملة قبل `maxWaitTime` انقضاء . من المحتمل أيضا أن تكون الدفعات الجزئية للتحضير الأول للدالة بعد إجراء التحجيم.
maxWaitTime¹	00:01:00	الحد الأقصى للفاصل الزمني الذي يجب أن ينتظره المشغل لتعبئة دفعة قبل استدعاء الدالة. يتم النظر في وقت الانتظار فقط عندما `minEventBatchSize` يكون أكبر من 1 ويتم تجاهله بخلاف ذلك. إذا كان أقل من `minEventBatchSize` الأحداث متوفرة قبل انقضاء وقت الانتظار، يتم استدعاء الدالة مع دفعة جزئية. أطول وقت انتظار مسموح به هو 10 دقائق. ملاحظة: هذا الفاصل الزمني ليس ضمانا صارما للتوقيت الدقيق الذي يتم استدعاء الدالة عليه. هناك هامش خطأ صغير بسبب دقة المؤقت. عند إجراء التحجيم، قد يحدث أول استدعاء مع دفعة جزئية بسرعة أكبر أو قد يستغرق ما يصل إلى ضعف وقت الانتظار المكون.
batchCheckpointFrequency	1	عدد الدُفعات المراد معالجتها قبل إنشاء نقطة اختبار لمركز الحدث.
prefetchCount	300	عدد الأحداث المطلوبة بفارغ الصبر من مراكز الأحداث والمحتفظ بها في ذاكرة التخزين المؤقت المحلية للسماح للقراءات بتجنب انتظار عملية الشبكة
transportType	amqpTcp	البروتوكول والنقل المستخدمان للتواصل مع مراكز الأحداث. الخيارات المتاحة: `amqpTcp`، `amqpWebSockets`
webProxy	قيمة فارغة	الوكيل المراد استخدامه للتواصل مع مراكز الأحداث عبر مآخذ الويب. لا يمكن استخدام الوكيل مع النقل `amqpTcp`.
customEndpointAddress	قيمة فارغة	العنوان المراد استخدامه عند إنشاء اتصال بمراكز الأحداث، ما يسمح بتوجيه طلبات الشبكة عبر بوابة تطبيق أو مسار آخر لازم للبيئة المضيفة. لا تزال هناك حاجة إلى مساحة الاسم المؤهلة بالكامل لمركز الأحداث عند استخدام عنوان نقطة نهاية مخصصة، ويجب تحديدها بشكل صريح أو عبر سلسلة الاتصال.
targetUnprocessedEventThreshold¹	قيمة فارغة	العدد المطلوب من الأحداث غير المعالجة لكل مثيل دالة. يتم استخدام الحد في التحجيم المستند إلى الهدف لتجاوز حد التحجيم الافتراضي المستنتج من `maxEventBatchSize` الخيار. عند التعيين، يتم تقسيم إجمالي عدد الأحداث غير المعالجة على هذه القيمة لتحديد عدد مثيلات الدالة المطلوبة. يتم تقريب عدد المثيلات إلى رقم ينشئ توزيع قسم متوازن.
initialOffsetOptions/type	fromStart	الموقع في دفق الحدث لبدء المعالجة عند عدم وجود نقطة فحص في التخزين. ينطبق على كافة الأقسام. لمزيد من المعلومات، راجع وثائق OffsetType. الخيارات المتاحة: `fromStart`، `fromEnd`، `fromEnqueuedTime`
initialOffsetOptions/enqueuedTimeUtc	قيمة فارغة	يحدد الوقت في قائمة الانتظار للحدث في الدفق الذي تبدأ منه المعالجة. عندما يتم تكوين `initialOffsetOptions/type` على أنه `fromEnqueuedTime`، يكون هذا الإعداد إلزامياً. يدعم الوقت بأي تنسيق يدعمه DateTime.Parse ()، مثل `2020-10-26T20:31Z`. للتوضيح، يجب عليك أيضاً تحديد منطقة زمنية. عندما لا يتم تحديد المنطقة الزمنية، تفترض الوظائف المنطقة الزمنية المحلية للجهاز الذي يقوم بتشغيل Function App، وهو UTC عند التشغيل على Azure.
clientRetryOptions/mode	exponential	الأسلوب المستخدم لحساب تأخيرات إعادة المحاولة. يعيد الوضع الأسي محاولة المحاولات بتأخير استنادا إلى استراتيجية التراجع حيث ستزيد كل محاولة من المدة التي تنتظرها قبل إعادة المحاولة. يعيد الوضع الثابت المحاولة على فترات زمنية ثابتة مع وجود مدة متناسقة لكل تأخير. الخيارات المتاحة: `exponential`، `fixed`
clientRetryOptions/tryTimeout	00:01:00	أقصى مدة انتظار حتى تكتمل عملية "مراكز الأحداث"، في كل محاولة.
clientRetryOptions/delay	00:00:00.80	عامل التأخير أو التراجع المراد تطبيقه بين محاولات إعادة المحاولة.
clientRetryOptions/maximumDelay	00:00:01	الحد الأقصى للتأخير للسماح بين محاولات إعادة المحاولة.
clientRetryOptions/maximumRetries	3	الحد الأقصى لعدد محاولات إعادة المحاولة قبل اعتبار العملية المقترنة قد فشلت.

¹ استخدام minEventBatchSize maxWaitTime ويتطلب الإصدار 5.3.0 من الحزمة Microsoft.Azure.WebJobs.Extensions.EventHubs ، أو إصدارا أحدث.

² تم تغيير الافتراضي maxEventBatchSize في الإصدار 6.0.0 من الحزمة Microsoft.Azure.WebJobs.Extensions.EventHubs . في الإصدارات السابقة، كان هذا 10.

clientRetryOptions يتم استخدام لإعادة محاولة العمليات بين مضيف الوظائف ومراكز الأحداث (مثل إحضار الأحداث وإرسال الأحداث). راجع إرشادات حول معالجة أخطاء Azure Functions وإعادة المحاولة للحصول على معلومات حول تطبيق نهج إعادة المحاولة على الوظائف الفردية.

للحصول على مرجع لـ host.json في Azure Functions 2.x وما بعدها، راجع مرجع host.json لـ Azure Functions.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 1,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            },
            "initialOffsetOptions": {
                "type": "fromStart",
                "enqueuedTimeUtc": ""
            }
        }
    }
}

الخاصية	Default	‏‏الوصف
batchCheckpointFrequency	1	عدد دفعات الأحداث التي يجب معالجتها قبل إنشاء نقطة تحقق مؤشر مراكز الأحداث.
eventProcessorOptions/maxBatchSize	10	تم تلقي الحد الأقصى لعدد الأحداث لكل حلقة استقبال.
eventProcessorOptions/prefetchCount	300	عدد الجلب المسبق الافتراضي المستخدم بواسطة `EventProcessorHost`الأساسي. أدنى قيمة مسموح بها هي 10.
initialOffsetOptions/type¹	fromStart	الموقع في دفق الأحداث الذي تبدأ منه المعالجة عند عدم وجود نقطة فحص في التخزين. الخيارات هي `fromStart` أو `fromEnd` أو `fromEnqueuedTime`. يعالج `fromEnd` الأحداث الجديدة التي تم وضعها في قائمة الانتظار بعد بدء تشغيل Function App. ينطبق على كافة الأقسام. لمزيد من المعلومات، راجع وثائق EventProcessorOptions.
initialOffsetOptions/enqueuedTimeUtc¹	قيمة فارغة	يحدد الوقت في قائمة الانتظار للحدث في الدفق الذي تبدأ منه المعالجة. عندما يتم تكوين `initialOffsetOptions/type` على أنه `fromEnqueuedTime`، يكون هذا الإعداد إلزامياً. يدعم الوقت بأي تنسيق يدعمه DateTime.Parse ()، مثل `2020-10-26T20:31Z`. للتوضيح، يجب عليك أيضاً تحديد منطقة زمنية. عندما لا يتم تحديد المنطقة الزمنية، تفترض الوظائف المنطقة الزمنية المحلية للجهاز الذي يقوم بتشغيل Function App، وهو UTC عند التشغيل على Azure. لمزيد من المعلومات، راجع وثائق EventProcessorOptions.

¹ يبدأ دعم initialOffsetOptions بـ EventHubs v4.2.0.

للحصول على مرجع لـ host.json في Azure Functions 2.x وما بعدها، راجع مرجع host.json لـ Azure Functions.

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}

الخاصية	Default	‏‏الوصف
maxBatchSize	64	تم تلقي الحد الأقصى لعدد الأحداث لكل حلقة استقبال.
prefetchCount	300	الجلب المسبق الافتراضي الذي سيتم استخدامه بواسطة `EventProcessorHost`الأساسي.
batchCheckpointFrequency	1	عدد دفعات الأحداث التي يجب معالجتها قبل إنشاء نقطة تحقق مؤشر مراكز الأحداث.

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

مشاركة عبر

مشغل مراكز الأحداث في Azure وعمليات ربط لوظائف Azure

تثبيت الملحق

تثبيت الحزمة

أنواع الربط

إعدادات host.json

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

الملاحظات

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