مشغل Azure IoT Hub لـAzure Functions

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

توضح هذه المقالة كيفية العمل مع روابط Azure Functions من أجل IoT Hub. يعتمد دعم IoT Hub على Azure Event Hubs Binding.

للمزيد من المعلومات حول تفاصيل الإعداد والتهيئة، راجع النبذة العامة.

هام

بينما تستخدم نماذج التعليمات البرمجية التالية واجهة برمجة التطبيقات لمركز الحدث، يُطبق بناء الجملة المُعطى لدالات مركز IoT Hub.

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

مثال

يوضح المثال التالي الدالة 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 التي تستخدم الربط. تقرأ الدالة بيانات تعريف الحدث وتسجل الرسالة.

يوضح المثال التالي بيانات ربط Event Hubs في ملف 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 الكاملة معلقة.

يوضح المثال التالي ربط مشغل Event Hubs في ملف 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.
⁧⁩الاسم⁧⁩ اسم المتغير الذي يمثل عنصر الحدث في التعليمات البرمجية للدالة.
الحدثHubName اسم مركز الحدث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل. يمكن الرجوع إليها عبر إعدادات التطبيق%eventHubName%
مجموعة المستهلكين خاصية اختيارية تحدد مجموعة المستهلكين المستخدمة للاشتراك في الأحداث في المركز. إذا تم حذفها، يتم استخدام مجموعة المستهلكين $Default .
اصل اضبط على many لتمكين الدفع. إذا تم حذفها أو تعيينها إلى ، يتم تمرير رسالة واحدة إلى oneالدالة.
اتصال اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. راجع Connections.

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

الاستخدام

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

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

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

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

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

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

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

البيانات الوصفية للحدث

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

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

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

الاتصالات

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

يجب أن تحتوي سلسلة الاتصال على أذونات "قراءة" على الأقل لتنشيط الوظيفة.

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

ملاحظة

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

خصائص host.json

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

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