Share via

ربط بيانات ناتج ناقل خدمة Microsoft Azure لوظائف Azure

  • مقالة

استخدام ربط بيانات ناتج ناقل خدمة Microsoft Azure لإرسال رسائل قائمة الانتظار أو الموضوع.

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

هام

تستخدم هذه المقالة علامات التبويب لدعم إصدارات متعددة من نموذج البرمجة Node.js. يتوفر نموذج v4 بشكل عام وتم تصميمه للحصول على تجربة أكثر مرونة وبديهية لمطوري JavaScript وTypeScript. لمزيد من التفاصيل حول كيفية عمل نموذج v4، راجع دليل مطور Azure Functions Node.js. لمعرفة المزيد حول الاختلافات بين v3 وv4، راجع دليل الترحيل.

تدعم Azure Functions نموذجي برمجة ل Python. تعتمد الطريقة التي تحدد بها روابطك على نموذج البرمجة الذي اخترته.

يتيح لك نموذج برمجة Python v2 تحديد الروابط باستخدام المحسنات مباشرة في التعليمات البرمجية لدالة Python. لمزيد من المعلومات، راجع دليل مطور Python.

تدعم هذه المقالة كلا نموذجي البرمجة.

مثال

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

  • نموذج العامل المعزول: دالة C# المترجمة التي يتم تشغيلها في عملية عامل معزولة عن وقت التشغيل. عملية العامل المعزولة مطلوبة لدعم وظائف C# التي تعمل على إصدارات LTS وغير LTS .NET و.NET Framework. تستخدم Microsoft.Azure.Functions.Worker.Extensions.* ملحقات دالات عملية العامل المعزولة مساحات الأسماء.
  • نموذج قيد المعالجة: دالة C# المحولة برمجيا التي تعمل في نفس العملية مثل وقت تشغيل الوظائف. في تباين هذا النموذج، يمكن تشغيل الدالات باستخدام البرمجة النصية C#، والتي يتم دعمها بشكل أساسي لتحرير مدخل C#. تستخدم Microsoft.Azure.WebJobs.Extensions.* ملحقات الوظائف قيد المعالجة مساحات الأسماء.

هام

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

تحدد هذه التعليمة البرمجية وتهيئ ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

يظهر هذا المثال دالة C# التي تتلقى رسالة وتكتبها في قائمة انتظار ثانية:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

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

 

يستخدم هذا المثال مشغل HTTP مع كائن OutputType لإرسال استجابة HTTP وكتابة رسالة الإخراج.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

تعرف هذه التعليمة البرمجية نوع OutputTypeالإخراج المتعدد ، والذي يتضمن تعريف ربط إخراج ناقل خدمة Microsoft Azure على OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

يُظهر المثال التالي دالة Java التي ترسل رسالة إلى قائمة انتظار "ناقل خدمة Azure" myqueue عند تشغيلها بواسطة طلب HTTP.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

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

كما يمكن كتابة دوال Java إلى موضوع "ناقل خدمة Azure". يستخدم المثال التالي التعليق التوضيحي @ServiceBusTopicOutput لوصف التكوين لربط بيانات الناتج.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

يوضح المثال التالي دالة TypeScript التي تم تشغيلها من خلال المؤقت ترسل رسالة قائمة انتظار كل 5 دقائق.

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

يوضح المثال التالي دالة JavaScript التي تم تشغيلها من قبل المؤقت ترسل رسالة قائمة انتظار كل 5 دقائق.

const { app, output } = require('@azure/functions');

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

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

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

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

إليك PowerShell الذي يقوم بإنشاء رسالة كناتج للدالة.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

يوضح المثال التالي كيفية الكتابة إلى قائمة انتظار "ناقل خدمة Azure" في Python. يعتمد المثال على ما إذا كنت تستخدم نموذج برمجة v1 أو v2 Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

السمات

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

في مكتبات فئات C#‎، استخدم ServiceBusOutputClassute لتحديد قائمة الانتظار أو الموضوع المكتوب عليه بواسطة الإخراج.

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

الخاصية ‏‏الوصف
نوع الكيان حدد نوع الكيان إما Queue لإرسال الرسائل إلى قائمة الانتظار أو Topic عند إرسال الرسائل إلى موضوع.
QueueOrTopicName اسم الموضوع أو قائمة انتظار لإرسال الرسائل إليها. قم باستخدام EntityType لتعيين نوع الوجهة.
Connection اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.

الديكور

ينطبق فقط على نموذج برمجة Python v2.

بالنسبة لوظائف Python v2 المعرفة باستخدام مصمم الديكور، الخصائص التالية على service_bus_topic_output:

الخاصية ‏‏الوصف
arg_name اسم المتغير الذي يُمثل قائمة الانتظار أو رسالة الموضوع في التعليمات البرمجية للدالة.
queue_name اسم قائمة الانتظار. لا تقم بتعيينه إلا في حالة إرسال رسائل قائمة الانتظار، وليس لموضوع.
topic_name اسم الموضوع. لا تقم بتعيينه إلا في حالة إرسال الموضوع، وليس قائمة الانتظار.
connection اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.

للحصول على وظائف Python المعرفة باستخدام function.json، راجع قسم التكوين.

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

تتوفر التعليقات التوضيحية ServiceBusQueueOutput وServiceBusTopicOutput لكتابة رسالة كناتج دالة. يجب تعريف المعلمة التي تم تزيينها بهذه التعليقات التوضيحية كـOutputBinding<T> حيث T هو المكان الذي يكون فيه النوع المطابق لنوع الرسالة.

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

التكوين

ينطبق فقط على نموذج برمجة Python v1.

يوضح الجدول التالي الخصائص التي يمكنك تعيينها على الكائن الذي options تم تمريره output.serviceBusQueue() إلى الأسلوب .

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

يوضح الجدول التالي الخصائص التي يمكنك تعيينها على الكائن الذي options تم تمريره output.serviceBusTopic() إلى الأسلوب .

الخاصية ‏‏الوصف
topicName اسم الموضوع.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.

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

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

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى "serviceBus". يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه يجب تعيينه إلى "خارج". يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاسم اسم المتغير الذي يُمثل قائمة الانتظار أو رسالة الموضوع في التعليمات البرمجية للدالة. قم بتعيينه إلى "$return" للإشارة إلى القيمة المرجعة للدالة.
queueName اسم قائمة الانتظار. لا تقم بتعيينه إلا في حالة إرسال رسائل قائمة الانتظار، وليس لموضوع.
topicName اسم الموضوع. لا تقم بتعيينه إلا في حالة إرسال الموضوع، وليس قائمة الانتظار.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.
حقوق الوصول (v1 فقط) حقوق الوصول لسلسلة الاتصال. القيم المتوفرة هي manage وlisten. الافتراضي هو manage، الذي يشير إلى أن connection لديه إذن الإدارة. إذا كنت تستخدم سلسلة اتصال ليس لديها إذن الإدارة، قم بتعيين accessRights إلى "الاستماع". وإلا، قد تفشل وقت تشغيل الدالات في محاولة القيام بعمليات تتطلب إدارة الحقوق. في Azure Functions الإصدار 2.x والإصدارات الأحدث، هذه الخاصية غير متوفرة لأن الإصدار الأحدث من عدة تطوير البرامج لناقل خدمة Azure لا تدعم إدارة العمليات.

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

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

الاستخدام

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

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

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

عندما تريد أن تكتب الدالة رسالة واحدة، يمكن ربط إخراج ناقل خدمة Microsoft Azure بالأنواع التالية:

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

عندما تريد أن تكتب الدالة رسائل متعددة، يمكن ربط إخراج ناقل خدمة Microsoft Azure بالأنواع التالية:

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

بالنسبة لسيناريوهات الإخراج الأخرى، قم بإنشاء واستخدام أنواع من Azure.Messaging.ServiceBus مباشرة.

في إصدار Azure Functions 1.x، يقوم وقت التشغيل بإنشاء قائمة الانتظار إذا لم تكن موجودة، ويتعين عليك تعيين accessRights إلى manage. في Azure Functions الإصدار 2.x والإصدارات الأحدث، يجب أن تكون قائمة الانتظار أو الموضوع موجودة بالفعل؛ إذا قمت بتحديد قائمة انتظار أو موضوع غير موجود، تفشل الدالة.

استخدم عدة تطوير البرامج لناقل خدمة Microsoft Azure بدلاً من ربط الناتج المُضمن.

الوصول إلى رسالة الإخراج عن طريق إرجاع القيمة مباشرة أو باستخدام context.extraOutputs.set().

الناتج إلى "ناقل خدمة Azure" متوفر عبر cmdlet Push-OutputBinding حيث يمكنك تمرير الوسائط التي تُطابق الاسم المُعين بواسطة معلمة اسم الربط في ملف function.json.

استخدم عدة تطوير البرامج لناقل خدمة Microsoft Azure بدلاً من ربط الناتج المُضمن.

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

الاتصالات

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

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

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

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

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

إذا بدأ اسم إعداد التطبيق بـ «AzureWebJobs»، يمكنك تحديد ما تبقى من الاسم فقط. على سبيل المثال، إذا قمت بتعيين connection على «MyServiceBus»، فإن وقت تشغيل Functions يبحث عن إعداد تطبيق يسمى «AzureWebJobsMyServiceBus». إذا تركت connection فارغًا، فإن وقت تشغيل Functions يستخدم سلسلة اتصال Service Bus الافتراضية في إعداد التطبيق المسمى «AzureWebJobsServiceBus».

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

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

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

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

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

إشعار

عند استخدام Azure App Configuration أو Key Vault لتوفير إعدادات لاتصالات الهوية المُدارة، يجب أن تستخدم أسماء الإعداد فاصل مفاتيح صالح مثل : أو / بدلاً من __ لضمان حل الأسماء بشكل صحيح.

على سبيل المثال، <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace

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

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

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

هام

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

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

نوع الربط مثال على الأدوار المضمنة
المشغل1 Azure Service Bus Data Receiver، وAzure Service Bus Data Owner
ربط بيانات الإخراج مرسل بيانات ناقل خدمة Azure

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

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

Binding ‏‏المرجع
ناقل الخدمة رموز خطأ ناقل خدمة Azure
ناقل الخدمة حدود ناقل خدمة Azure

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