مشغّل مراكز أحداث Azure من أجل دالات Azure

  • مقالة
  • قراءة خلال 11 دقائق

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

لمزيد من المعلومات حول تفاصيل الإعداد والتكوين، راجع نظرة عامة.

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

مثال

يوضح المثال التالي دالة C#‎ التي تسجل نص الرسالة لمشغل مراكز الأحداث.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

للوصول إلى بيانات تعريف الحدث في التعليمات البرمجية للدالة، قم بالربط بكائن EventData . يمكنك أيضا الوصول إلى نفس الخصائص باستخدام تعبيرات الربط في توقيع الأسلوب. يوضح المثال التالي كلا الطريقتين للحصول على نفس البيانات:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

لتلقي الأحداث في دفعة، قم بإنشاء string أو EventData صفيف.

ملاحظة

عند الاستلام في دفعة، لا يمكنك الربط بمعلمات الأسلوب كما هو الحال في المثال أعلاه مع DateTime enqueuedTimeUtc ويجب أن تتلقى هذه من كل EventData كائن

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

يظهر المثال التالي ربط مشغل مراكز الأحداث في ملف function.jsonودالة JavaScript التي تستخدم الربط. تقرأ الدالة بيانات تعريف الحدث وتسجل الرسالة.

يوضح المثال التالي بيانات ربط مراكز الأحداث في ملف function.json ، والذي يختلف عن الإصدار 1.x من وقت تشغيل الوظائف مقارنة بالإصدارات الأحدث.

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

هنا تعليمة برمجية JavaScript:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

لتلقي الأحداث في دفعة، قم بتعيين cardinality إلى many في ملف function.json ، كما هو موضح في الأمثلة التالية.

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

هنا تعليمة برمجية JavaScript:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

أمثلة PowerShell الكاملة معلقة.

يوضح المثال التالي ربط مشغل مراكز الأحداث في ملف function.jsonودالة Python التي تستخدم الربط. تقرأ الدالة بيانات تعريف الحدث وتسجل الرسالة.

تظهر الأمثلة التالية بيانات ربط مراكز الأحداث في ملف function.json .

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

إليك التعليمة البرمجية لـ Python:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

يوضح المثال التالي ربط مشغل مراكز الأحداث الذي يسجل نص الرسالة لمشغل مراكز الأحداث.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي EventHubTrigger على المعلمات التي تأتي قيمتها من مركز الأحداث. تؤدي المعلمات مع هذه التعليقات التوضيحية إلى تشغيل الدالة عند وصول حدث. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو عناصر POJO أو القيم الفارغة باستخدام Optional<T>.

السمات

تستخدم كل من مكتبات C# العملية قيد المعالجةوالعزلة السمة لتكوين المشغل. يستخدم البرنامج النصي C# بدلا من ذلك ملف تكوين function.json.

في مكتبات الفئة C#‎، استخدم EventHubTriggerAttribute، الذي يدعم الخصائص التالية.

المعلمات الوصف
eventHubName اسم مركز الأحداث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل. يمكن الرجوع إليها في إعدادات التطبيق، مثل %eventHubName%
مجموعة المستهلكين خاصية اختيارية تعين مجموعة المستهلكين المستخدمة للاشتراك في الأحداث في المركز. عند حذفها، يتم استخدام مجموعة المستهلكين $Default .
الاتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. لمعرفة المزيد، راجع الاتصالات.

تعليقات توضيحية

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي EventHubTrigger ، الذي يدعم الإعدادات التالية:

تهيئة

يشرح الجدول التالي خصائص تكوين المشغل التي قمت بتعيينها في ملف function.json ، والذي يختلف حسب إصدار وقت التشغيل.

خاصية function.json الوصف
النوع يجب تعيينه إلى eventHubTrigger. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
⁧⁩direction⁧⁩ يجب تعيينه إلى in. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
⁧⁩الاسم⁧⁩ اسم المتغير الذي يمثل عنصر الحدث في التعليمات البرمجية للدالة.
eventHubName اسم مركز الأحداث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل. يمكن الرجوع إليها عبر إعدادات التطبيق%eventHubName%
مجموعة المستهلكين خاصية اختيارية تعين مجموعة المستهلكين المستخدمة للاشتراك في الأحداث في المركز. إذا تم حذفها، يتم استخدام مجموعة المستهلكين $Default .
اصل قم بتعيين إلى many لتمكين الإرسال في دفعات. إذا تم حذفها أو تعيينها إلى one، يتم تمرير رسالة واحدة إلى الدالة .
اتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. راجع Connections.

عند التطوير محليا، أضف إعدادات التطبيق في ملف local.settings.json في Values المجموعة.

الاستخدام

لمعرفة المزيد حول كيفية تحجيم مشغل مراكز الأحداث ومشغل IoT Hub، راجع مشغل مراكز الأحداث.

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

تدعم وظائف مكتبة فئات C# قيد المعالجة الأنواع التالية:

هذا الإصدار من EventData يسقط الدعم للنوع القديم Body لصالح EventBody.

يمكن أن يكون نوع المعلمة واحدا مما يلي:

  • أي أنواع Java أصلية مثل int و String و byte[].
  • القيم التي تقبل القيم الخالية باستخدام اختياري.
  • أي نوع POJO.

لمعرفة المزيد، راجع مرجع EventHubTrigger .

بيانات تعريف الحدث

يوفر مشغل مراكز الأحداث العديد من خصائص بيانات التعريف. يمكن استخدام خصائص بيانات التعريف كجزء من تعبيرات الربط في روابط أخرى أو كمعلمات في التعليمات البرمجية الخاصة بك. تأتي الخصائص من فئة EventData .

الخاصية النوع الوصف
PartitionContext نص القسم المثيل PartitionContext .
EnqueuedTimeUtc DateTime الوقت المحدد في UTC.
Offset string إزاحة البيانات المتعلقة بتدفق قسم مركز الحدث. الإزاحة هي علامة أو معرف لحدث داخل دفق مراكز الأحداث. المعرف فريد داخل قسم من دفق مراكز الأحداث.
PartitionKey string القسم الذي يجب إرسال بيانات الحدث إليه.
Properties IDictionary<String,Object> خصائص المستخدم لبيانات الحدث.
SequenceNumber Int64 رقم التسلسل المنطقي للحدث.
SystemProperties IDictionary<String,Object> خصائص النظام، بما في ذلك بيانات الحدث.

راجع أمثلة التعليمات البرمجية التي تستخدم هذه الخصائص في هذه المقالة.

الاتصالات

connection الخاصية هي مرجع إلى تكوين البيئة الذي يحدد كيفية اتصال التطبيق بمراكز الأحداث. قد يحدد ما يلي:

إذا كانت القيمة المكونة تطابقا دقيقا لإعداد واحد ومطابقة بادئة للإعدادات الأخرى، يتم استخدام المطابقة الدقيقة.

سلسلة الاتصال

احصل على سلسلة الاتصال هذه بالنقر فوق الزر معلومات الاتصاللمساحة الاسم، وليس مركز الأحداث نفسه. يجب أن تكون سلسلة الاتصال لمساحة اسم مراكز الأحداث، وليس مركز الأحداث نفسه.

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

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

الاتصالات القائمة على الهوية

إذا كنت تستخدم الإصدار 5.x أو أعلى من الملحق، فبدلا من استخدام سلسلة اتصال مع سر، يمكنك أن يكون التطبيق يستخدم هوية Azure Active Directory. للقيام بذلك، يمكنك تعريف الإعدادات ضمن بادئة شائعة تعين إلى الخاصية connection في تكوين المشغل والربط.

في هذا الوضع، يتطلب الملحق الخصائص التالية:

ملاحظة

يجب أن يكون متغير البيئة المتوفر مسبوقا AzureWebJobs حاليا بالعمل في خطة الاستهلاك. في Premium الخطط، هذه البادئة غير مطلوبة.

الخاصية قالب متغير البيئة الوصف قيمة المثال
مساحة الاسم المؤهلة بالكامل AzureWebJobs<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace مساحة اسم مراكز الأحداث المؤهلة بالكامل. <>event_hubs_namespace.servicebus.windows.net

قد يتم تعيين خصائص إضافية لتخصيص الاتصال. راجع الخصائص الشائعة للاتصالات المستندة إلى الهوية.

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

منح الإذن للهوية

مهما كانت الهوية المستخدمة يجب أن يكون لديك أذونات لتنفيذ الإجراءات المقصودة. ستحتاج إلى تعيين دور في Azure RBAC، باستخدام أدوار مضمنة أو مخصصة توفر هذه الأذونات.

هام

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

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

نوع الربط مثال على الأدوار المضمنة
مشغّل Azure Event Hubs Data Receiver، مالك بيانات مراكز الأحداث Azure
ربط بيانات الإخراج مرسل بيانات مراكز أحداث Azure Event Hubs

إعدادات host.json

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

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