ربط مُخرج مراكز الأحداث Azure لوظائف Azure

مقالة
05/09/2022
قراءة خلال 10 دقائق

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

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

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

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

مثال

يوضح المثال التالي دالة C#‎ التي تكتب رسالة إلى مركز أحداث، باستخدام قيمة إرجاع الأسلوب كإخراج:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

يوضح المثال التالي كيفية استخدام واجهة IAsyncCollector لإرسال دفعة من الرسائل. هذا السيناريو شائع عند معالجة الرسائل الواردة من Event Hub وإرسال النتيجة إلى Event Hub آخر.

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<string> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // do some processing:
        var myProcessedEvent = DoSomething(eventData);

        // then send the message
        await outputEvents.AddAsync(JsonConvert.SerializeObject(myProcessedEvent));
    }
}

يوضح المثال التالي دالة C#‎ التي تكتب سلسلة رسالة إلى مركز أحداث، باستخدام قيمة إرجاع الأسلوب كإخراج:

[Function("EventHubsFunction")]
[EventHubOutput("dest", Connection = "EventHubConnectionAppSetting")]
public static string Run([EventHubTrigger("src", Connection = "EventHubConnectionAppSetting")] string[] input,
    FunctionContext context)
{
    var logger = context.GetLogger("EventHubsFunction");

    logger.LogInformation($"First Event Hubs triggered message: {input[0]}");

    var message = $"Output message created at {DateTime.Now}";
    return message;
}

يوضح المثال التالي ربط مشغل مركز الأحداث في ملف function.jsonودالة برنامج نصي C#‎ التي تستخدم الربط. تكتب الدالة رسالة إلى مركز أحداث.

تظهر الأمثلة التالية بيانات ربط مراكز الأحداث في ملف function.json للإصدار 2.x من وقت تشغيل الوظائف والإصدارات الأحدث.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

إليك التعليمات البرمجية للبرنامج النصي C# التي تنشئ رسالة واحدة:

using System;
using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, out string outputEventHubMessage, ILogger log)
{
    String msg = $"TimerTriggerCSharp1 executed at: {DateTime.Now}";
    log.LogInformation(msg);   
    outputEventHubMessage = msg;
}

إليك التعليمات البرمجية لبرنامج #C النصي الذي ينشئ عدة رسائل:

public static void Run(TimerInfo myTimer, ICollector<string> outputEventHubMessage, ILogger log)
{
    string message = $"Message created at: {DateTime.Now}";
    log.LogInformation(message);
    outputEventHubMessage.Add("1 " + message);
    outputEventHubMessage.Add("2 " + message);
}

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

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

الدالات 2.x+
دالات 1.x

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "path": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

إليك تعليمات JavaScript البرمجية التي ترسل رسالة واحدة:

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();
    context.log('Message created at: ', timeStamp);   
    context.bindings.outputEventHubMessage = "Message created at: " + timeStamp;
    context.done();
};

إليك تعليمات JavaScript البرمجية التي ترسل رسائل متعددة:

module.exports = function(context) {
    var timeStamp = new Date().toISOString();
    var message = 'Message created at: ' + timeStamp;

    context.bindings.outputEventHubMessage = [];

    context.bindings.outputEventHubMessage.push("1 " + message);
    context.bindings.outputEventHubMessage.push("2 " + message);
    context.done();
};

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

يظهر المثال التالي ربط مشغل مركز الأحداث في ملف function.jsonودالة Python التي تستخدم الربط. تكتب الدالة رسالة إلى مركز أحداث.

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

{
    "type": "eventHub",
    "name": "$return",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

إليك تعليمة Python البرمجية التي ترسل رسالة واحدة:

import datetime
import logging
import azure.functions as func


def main(timer: func.TimerRequest) -> str:
    timestamp = datetime.datetime.utcnow()
    logging.info('Message created at: %s', timestamp)
    return 'Message created at: {}'.format(timestamp)

يوضح المثال التالي دالة Java التي تكتب رسالة تحتوي على الوقت الحالي إلى Event Hub.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

في مكتبة وقت تشغيل وظائف Java، استخدم @EventHubOutput التعليق التوضيحي على المعلمات التي سيتم نشر قيمتها في Event Hub. يجب أن تكون المعلمة من النوع OutputBinding<T> ، حيث T هي POJO أو أي نوع Java أصلي.

السمات

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

استخدم EventHubAttribute لتعريف ربط إخراج بمركز حدث، والذي يدعم الخصائص التالية.

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

استخدم [EventHubOutputAttribute] لتعريف ربط إخراج بمركز حدث، والذي يدعم الخصائص التالية.

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

يشرح الجدول الآتي خصائص تكوين ربط البيانات التي عليك تعيينها في ملف function.json.

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `eventHub`.
⁧⁩direction⁧⁩	يجب تعيينها إلى `out`. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم	اسم المتغير المستخدم في التعليمات البرمجية للدالة التي تمثل الحدث.
eventHubName	الدالات 2.x وأعلى. اسم مركز الأحداث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل. في Functions 1.x، تسمى `path`هذه الخاصية .
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. لمعرفة المزيد، راجع الاتصالات.

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

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي EventHubOutput على المعلمات التي سيتم نشر قيمتها في Event Hub. يتم اعتماد الإعدادات التالية في التعليق التوضيحي:

تهيئة

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

الدالات 2.x+
دالات 1.x

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `eventHub`.
⁧⁩direction⁧⁩	يجب تعيينها إلى `out`. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم	اسم المتغير المستخدم في التعليمات البرمجية للدالة التي تمثل الحدث.
eventHubName	الدالات 2.x وأعلى. اسم مركز الأحداث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل.
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. لمعرفة المزيد، راجع الاتصالات.

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `eventHub`.
⁧⁩direction⁧⁩	يجب تعيينها إلى `out`. يتم تعيين هذه المعلمة تلقائيًا عند إنشاء الربط في مدخل Azure.
الاسم	اسم المتغير المستخدم في التعليمات البرمجية للدالة التي تمثل الحدث.
مسار	الدالات 1.x فقط. اسم مركز الأحداث. عندما يكون اسم مركز الحدث موجودا أيضا في سلسلة الاتصال، تتجاوز هذه القيمة هذه الخاصية في وقت التشغيل.
اتصال	اسم إعداد التطبيق أو مجموعة الإعدادات التي تحدد كيفية الاتصال بمراكز الأحداث. لمعرفة المزيد، راجع الاتصالات.

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

الاستخدام

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

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

Azure.Messaging.EventHubs.EventData
سلسلة
صفيف البايت
كائن CLR قديم عادي (POCO)

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

إرسال رسائل باستخدام معلمة أسلوب مثل out string paramName. لكتابة رسائل متعددة، يمكنك استخدام ICollector<string> أو IAsyncCollector<string> بدلاً من out string.

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

Microsoft.Azure.EventHubs.EventData
سلسلة
صفيف البايت
كائن CLR قديم عادي (POCO)

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

Azure.Messaging.EventHubs.EventData
سلسلة
صفيف البايت
كائن CLR قديم عادي (POCO)

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

إرسال الرسائل باستخدام معلمة أسلوب مثل out string paramName، حيث paramName هي القيمة المحددة في name خاصية function.json. لكتابة رسائل متعددة، يمكنك استخدام ICollector<string> أو IAsyncCollector<string> بدلاً من out string.

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

Microsoft.Azure.EventHubs.EventData
سلسلة
صفيف البايت
كائن CLR قديم عادي (POCO)

هناك خياران لإخراج رسالة Event Hub من دالة باستخدام التعليق التوضيحي EventHubOutput :

القيمة المرجعة: من خلال تطبيق التعليق التوضيحي على الدالة نفسها، تستمر القيمة المرجعة للدالة كرسالة Event Hub.
أمر حتمي: لتعيين قيمة الرسالة صراحةً، بادر بتطبيق التعليق التوضيحي على معلمة معينة من النوع OutputBinding<T>، حيث T عبارة عن POJO أو أي نوع Java أصلي. مع هذا التكوين، يؤدي تمرير قيمة إلى الأسلوب إلى setValue استمرار القيمة كرسالة Event Hub.

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

الوصول إلى حدث الإخراج باستخدام context.bindings.<name> حيث <name> هي القيمة المحددة في name خاصية function.json.

هناك خياران لإخراج رسالة Event Hub من دالة:

القيمة المرجعة: تعيين الخاصية name في function.json إلى $return. باستخدام هذا التكوين، تستمر القيمة المرجعة للدالة كرسالة Event Hub.
أمر حتمي: تمرير قيمة إلى الأسلوب المُحدد الخاص بالمعلمة التي أُعلن عنها باعتبارها نوع Out. تستمر القيمة إلى set باعتبارها رسالة Event Hub.

الاتصالات

الخاصية 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 Event Hubs
ربط بيانات الإخراج	مرسل بيانات مراكز أحداث Azure Event Hubs

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

Binding	‏‏المرجع
Event Hub	دليل العمليات

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

الاستجابة للأحداث المرسلة إلى بث حدث مركز الأحداث (المشغل)