مشغل ناقل خدمة Azure لوظائف Azure

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

استخدم مشغل ناقل الخدمة للرد على الرسائل من قائمة انتظار أو موضوع ناقل الخدمة. بدءًا من إصدار الامتداد 3.1.0، يمكنك تشغيل قائمة انتظار أو موضوع تم تمكينه للجلسة.

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

مثال

يمكن إنشاء الدالة C # باستخدام أحد أوضاع C # التالية:

يوضح المثال التالي وظيفة C # التي تقرأ البيانات الوصفية للرسالة وتسجل رسالة قائمة انتظار ناقل الخدمة:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

تستخدم الدالة Java التالية @ServiceBusQueueTrigger التعليق التوضيحي من مكتبة وقت تشغيل وظائف Java لوصف التكوين الخاص بتشغيل قائمة انتظار ناقل الخدمة. تلتقط الوظيفة الرسالة الموضوعة في قائمة الانتظار وتضيفها إلى السجلات.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

يمكن أيضًا تشغيل وظائف Java عند إضافة رسالة إلى موضوع ناقل الخدمة. يستخدم المثال التالي التعليق التوضيحي @ServiceBusTopicTrigger لوصف التكوين لربط بيانات الناتج.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

يوضح المثال التالي ربط بيانات ناتج ناقل خدمة Azure في ملف function.json ودالة برنامج #C النصي التي تستخدم ربط البيانات. تقرأ الدالة بيانات تعريف الرسالةوتسجل رسالة قائمة انتظار ناقل الخدمة.

فيما يلي بيانات الربط في ملفfunction.json:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

فيما يلي التعليمة البرمجية للبرنامج الأساسي لـ JavaScript:

module.exports = async function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
};

يُظهر المثال التالي ربط بيانات ناتج ناقل خدمة Azure في ملف function.json ودالة PowerShell التي تستخدم ربط البيانات.

فيما يلي بيانات الربط في ملفfunction.json:

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

إليك الدالة التي تعمل عند إرسال رسالة ناقل الخدمة.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

يوضح المثال التالي كيفية قراءة رسالة قائمة انتظار ناقل الخدمة عبر مشغل.

يُعرف ربط بيانات ناقل خدمة Azure في function.js حيث يُعين type إلى serviceBusTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

تعلن التعليمة البرمجية الموجودة في _init_.py معلمة على أنها func.ServiceBusMessage، مما يسمح لك بقراءة رسالة قائمة الانتظار في وظيفتك.

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
        'metadata' : msg.metadata
    }, default=str)

    logging.info(result)

السمات

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

يشرح الجدول التالي الخصائص التي يمكنك تعيينها باستخدام سمة المشغل هذه:

الخاصية الوصف
QueueName اسم قائمة الانتظار لمراقبة. تعيين فقط في حالة مراقبة قائمة انتظار، وليس لموضوع.
TopicName اسم الموضوع الذي يجب مراقبته. تعيين فقط إذا كان يراقب موضوعًا، وليس لقائمة انتظار.
اسم الاشتراك اسم الاشتراك للمراقبة. تعيين فقط إذا كان يراقب موضوعًا، وليس لقائمة انتظار.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.
Access حقوق الوصول لسلسلة الاتصال. القيم المتوفرة هي manage وlisten. الافتراضي هو manage، الذي يشير إلى أن connection لديه إذن الإدارة. إذا كنت تستخدم سلسلة اتصال ليس لديها إذن الإدارة، قم بتعيين accessRights إلى "الاستماع". وإلا، قد تفشل وقت تشغيل الدالات في محاولة القيام بعمليات تتطلب إدارة الحقوق. في Azure Functions الإصدار 2.x وأعلى، هذه الخاصية غير متوفرة لأن الإصدار الأخير من SDK لا يعتمد ناقل الخدمة إدارة العمليات.
إيسباتشيد يتم تسليم الرسائل على دفعات. يتطلب صفيفا أو نوع مجموعة.
IsSessionsEnabled trueإذا كان الاتصال بقائمة انتظار أو اشتراك على علم بجلسة العمل. falseخلاف ذلك، وهي القيمة الافتراضية.
AutoComplete trueما إذا كان يجب على المشغل استدعاء مكتمل تلقائيًا بعد المعالجة، أو إذا كان رمز الوظيفة سيتصل يدويًا بإكمال.

في حالة الضبط علىtrue، يكمل المشغل الرسالة تلقائيًا إذا اكتمل تنفيذ الوظيفة بنجاح، ويتخلى عن الرسالة بخلاف ذلك.

عند التعيين علىfalse، تكون مسؤولاً عن استدعاء طرق MessageReceiver لإكمال الرسالة أو التخلي عنها أو إتمامها. إذا تم طرح استثناء (ولم يتم استدعاء أيMessageReceiver من الطرق)، فسيظل القفل. بمجرد انتهاء صلاحية القفل، يتم إعادة وضع الرسالةDeliveryCount في قائمة الانتظار مع الزيادة ويتم تجديد القفل تلقائيًا.

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

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

يسمحServiceBusQueueTriggerلك التعليق التوضيحي بإنشاء وظيفة يتم تشغيلها عند إنشاء رسالة قائمة انتظار "ناقل الخدمة". تتضمن خيارات التكوين المتوفرة الخصائص التالية:

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

يسمحServiceBusTopicTriggerلك التعليق التوضيحي بتعيين موضوع واشتراك لاستهداف البيانات التي تؤدي إلى تشغيل الوظيفة.

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

راجع المُشّغل المثال لمزيد من التفاصيل.

التكوين

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

خاصية function.json الوصف
النوع يجب تعيينه إلى serviceBusTrigger. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
⁧⁩direction⁧⁩ يجب تعيين إلى "في". تُعيَّن هذه الخاصية تلقائياً عندما تُنشئ المشغل في مدخل Azure.
⁧⁩الاسم⁧⁩ اسم المتغير الذي يمثل قائمة الانتظار أو رسالة الموضوع في كود الوظيفة.
queueName اسم قائمة الانتظار لمراقبة. تعيين فقط في حالة مراقبة قائمة انتظار، وليس لموضوع.
topicName اسم الموضوع الذي يجب مراقبته. تعيين فقط إذا كان يراقب موضوعًا، وليس لقائمة انتظار.
اسم الاشتراك اسم الاشتراك للمراقبة. تعيين فقط إذا كان يراقب موضوعًا، وليس لقائمة انتظار.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.
accessRights حقوق الوصول لسلسلة الاتصال. القيم المتوفرة هي manage وlisten. الافتراضي هو manage، الذي يشير إلى أن connection لديه إذن الإدارة. إذا كنت تستخدم سلسلة اتصال ليس لديها إذن الإدارة، قم بتعيين accessRights إلى "الاستماع". وإلا، قد تفشل وقت تشغيل الدالات في محاولة القيام بعمليات تتطلب إدارة الحقوق. في Azure Functions الإصدار 2.x وأعلى، هذه الخاصية غير متوفرة لأن الإصدار الأخير من SDK لا يعتمد ناقل الخدمة إدارة العمليات.
isSessionsEnabled trueإذا كان الاتصال بقائمة انتظار أو اشتراك على علم بجلسة العمل. falseخلاف ذلك، وهي القيمة الافتراضية.
autoComplete يجب أن يكون true للوظائف غير C # ، مما يعني أن المشغل يجب أن يتصل تلقائيا بالكامل بعد المعالجة ، أو أن رمز الوظيفة يستدعي يدويا مكتملا.

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

تؤدي الاستثناءات في الدالة إلى استدعاءات abandonAsync وقت التشغيل في الخلفية. إذا لم يحدث استثناء، فسيتمcompleteAsync استدعاء في الخلفية. هذه الخاصية متاحة فقط في وظائف Azure 2.x والإصدارات الأحدث.

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

راجع قسم المثال للحصول على أمثلة كاملة.

الاستخدام

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

النوع الوصف
System.String استخدمه عندما تكون الرسالة نصا بسيطا.
بايت[] استخدم لرسائل البيانات الثنائية.
عنصر عندما تحتوي رسالة على JSON، تحاول الدالات إلغاء تسلسل بيانات JSON إلى نوع كائن CLR قديم عادي معروف.

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

استخدم نوع ServiceBusReceivedMessage لتلقي بيانات تعريف الرسالة من قوائم انتظار ناقل الخدمة والاشتراكات. لمعرفة المزيد، راجع الرسائل والحمولات والتسلسل.

في مكتبات الفئات C#‎، يأخذ منشئ السمة اسم قائمة الانتظار أو الموضوع والاشتراك.

يمكنك أيضا استخدام السمة ServiceBusAccountAttribute لتحديد حساب ناقل الخدمة المراد استخدامه. يأخذ المنشئ اسم إعداد تطبيق يحتوي على سلسلة اتصال ناقل الخدمة. يمكن تطبيق السمة على المعلمة أو الأسلوب أو مستوى الفئة. يظهر المثال التالي مستوى الفئة ومستوى الأسلوب:

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

يتم تحديد حساب "ناقل الخدمة" لاستخدام بالترتيب التالي:

  • خاصية ServiceBusTriggerالسمةConnection.
  • ServiceBusAccountالسمة المطبقة على نفس المعلمة المماثلة لهاServiceBusTrigger.
  • السمة ServiceBusAccount المطبقة على الوظيفة.
  • السمة ServiceBusAccount المطبقة على الفئة.
  • AzureWebJobsServiceBus إعداد التطبيق.

Connection عندما لا يتم تعريف الخاصية، تبحث الوظائف عن إعداد تطبيق باسم AzureWebJobsServiceBus، وهو الاسم الافتراضي لسلسلة اتصال Service Bus. يمكنك أيضا تعيين Connection الخاصية لتحديد اسم إعداد تطبيق يحتوي على سلسلة اتصال ناقل الخدمة لاستخدامها.

تتوفر رسالة "ناقل الخدمة" الواردة عبر ServiceBusQueueMessageأوServiceBusTopicMessageمعلمة.

الوصول إلى قائمة الانتظار أو الموضوع باستخدامcontext.bindings.<name from function.json>. يتم تمرير رسالة "ناقل الخدمة" إلى الدالة كسلسلة أو كائن JSON.

يتوفر مثيل ناقل الخدمة عبر المعلمة التي تم تكوينها فيخاصية اسم الملف function.json.

تتوفر رسالة قائمة الانتظار للوظيفة عبر معلمة مكتوبة كـfunc.ServiceBusMessage. يتم تمرير رسالة "ناقل الخدمة" إلى الدالة كسلسلة أو كائن JSON.

للحصول على مثال كامل، راجع قسم الأمثلة.

الاتصالات

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

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

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

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

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

إذا كان اسم إعداد التطبيق يبدأ ب "AzureWebJobs"، فيمكنك تحديد ما تبقى من الاسم فقط. على سبيل المثال، إذا قمت بتعيين connection إلى "MyServiceBus"، يبحث وقت تشغيل الوظائف عن إعداد تطبيق يسمى "AzureWebJobsMyServiceBus". إذا تركت connection فارغا، يستخدم وقت تشغيل الدالات سلسلة اتصال "ناقل الخدمة" الافتراضية في إعداد التطبيق المسمى "AzureWebJobsServiceBus".

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

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

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

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

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

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

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

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

هام

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

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

نوع الربط مثال على الأدوار المضمنة
الزناد1 ناقل خدمة Azure مستقبل البيانات، مالك بيانات ناقل خدمة Azure
ربط بيانات الإخراج مرسل بيانات ناقل خدمة Azure

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

رسالة غير قابلة للمعالجة

لا يمكن التحكم في معالجة الرسائل الغير قابلة للمعالجة أو تكوينها في وظائف Azure. يتعامل ناقل الخدمة مع الرسائل الغير قابلة للمعالجة نفسها.

سلوك PeekLock

يتلقى وقت تشغيل الدالات رسالة في وضع PeekLock. فإنه يستدعي Complete الرسالة إذا انتهت الدالة بنجاح أو Abandon استدعاءات إذا فشلت الدالة. إذا كانت الدالة تعمل لفترة أطول منPeekLockالمهلة، يتم تجديد القفل تلقائيًا طالما كانت الوظيفة قيد التشغيل.

maxAutoRenewDurationيمكن تكوينه في host.json، الذي يعيّنOnMessageOptions.MaxAutoRenewDuration. الحد الأقصى المسموح به لهذا الإعداد هو 5 دقائق وفقًا لمستندات ناقل الخدمة، بينما يمكنك زيادة حد وقت الوظائف من الافتراضي وهو 5 دقائق إلى 10 دقائق. بالنسبة لوظائف ناقل الخدمة، لن ترغب في القيام بذلك بعد ذلك، لأنك ستتجاوز حد تجديد حافلة الخدمة.

بيانات تعريف الرسالة

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

هذه الخصائص هي أعضاء في فئة ServiceBusReceivedMessage.

الخاصية النوع الوصف
ApplicationProperties ApplicationProperties الخصائص التي تم تعيينها بواسطة المرسل.
ContentType string معرّف نوع المحتوى يستخدمه المرسل والمتلقي لمنطق خاص بالتطبيق.
CorrelationId string معرف الارتباط.
DeliveryCount Int32 عدد عمليات التسليم.
EnqueuedTime DateTime الوقت المحدد في UTC.
ScheduledEnqueueTimeUtc DateTime الوقت المجدول في قائمة الانتظار بالتوقيت العالمي المنسق.
ExpiresAt DateTime وقت انتهاء الصلاحية في UTC.
MessageId string قيمة معرّفة من قبل المستخدم يمكن لناقل الخدمة استخدامها لتحديد الرسائل المكررة، إذا تم تمكينها.
ReplyTo string الرد على عنوان قائمة الانتظار.
Subject string التسمية الخاصة بالتطبيق والتي يمكن استخدامها بدلًا من خاصيةLabelالبيانات الوصفية.
To string إرسال إلى العنوان.

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