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

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

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

هام

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

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

الإصدار 2

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

v1

يتطلب منك نموذج برمجة Python v1 تعريف الروابط في ملف function.json منفصل في مجلد الدالة. لمزيد من المعلومات، راجع دليل مطور 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; }
}

نموذج قيد المعالجة

يُظهر المثال التالي دالة #C ترسل رسالة قائمة انتظار "ناقل خدمة Azure":

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, ILogger log)
{
    log.LogInformation($"C# function processed: {input.Text}");
    return input.Text;
}

 

---

بدلا من استخدام عبارة الإرجاع لإرسال الرسالة، ترجع دالة مشغل HTTP هذه استجابة HTTP مختلفة عن رسالة الإخراج.

[FunctionName("HttpTrigger1")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req, 
[ServiceBus("TopicOrQueueName", Connection = "ServiceBusConnection")] IAsyncCollector<string> message, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    await message.AddAsync("MyMessage");
    await message.AddAsync("MyMessage2");

    string responseMessage = "This HTTP triggered sent a message to Service Bus.";

    return new OkObjectResult(responseMessage);
}

يُظهر المثال التالي دالة 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();

    }

الطراز v4

يوضح المثال التالي دالة 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}`];

الطراز v3

عينات TypeScript غير موثقة للنموذج v3.

الطراز v4

يوضح المثال التالي دالة 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}`];

الطراز v3

يُظهر المثال التالي ربط بيانات ناتج ناقل خدمة Azure في ملف function.json ودالة JavaScript التي تستخدم ربط البيانات. تستخدم الدالة مشغل مُؤقت لإرسال رسالة قائمة الانتظار كل 15 ثانية.

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

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

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

module.exports = async function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
};

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

module.exports = async function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = [];
    context.bindings.outputSbQueue.push("1 " + message);
    context.bindings.outputSbQueue.push("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.

الإصدار 2

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'

v1

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

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "msg",
      "queueName": "outqueue"
    }
  ]
}

في _init_.py، يمكنك كتابة رسالة إلى قائمة الانتظار عن طريق تمرير قيمة إلى أسلوب set.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

السمات

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

نموذج عامل معزول

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

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

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

نموذج قيد المعالجة

في مكتبات الفئة #C، استخدم ServiceBusAttribute.

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

الخاصية	‏‏الوصف
QueueName	اسم قائمة الانتظار. لا تقم بتعيينه إلا في حالة إرسال رسائل قائمة الانتظار، وليس لموضوع.
اسم الموضوع	اسم الموضوع. لا تقم بتعيينه إلا في حالة إرسال الموضوع، وليس قائمة الانتظار.
Connection	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بخدمة الناقل. راجع الاتصالات.
الوصول	حقوق الوصول لسلسلة الاتصال. القيم المتوفرة هي manage وlisten. الافتراضي هو manage، الذي يشير إلى أن connection لديه إذن الإدارة. إذا كنت تستخدم سلسلة اتصال ليس لديها إذن الإدارة، قم بتعيين accessRights إلى "الاستماع". وإلا، قد تفشل وقت تشغيل الدالات في محاولة القيام بعمليات تتطلب إدارة الحقوق. في Azure Functions الإصدار 2.x والإصدارات الأحدث، هذه الخاصية غير متوفرة لأن الإصدار الأحدث من عدة تطوير البرامج لناقل خدمة Azure لا تدعم إدارة العمليات.

فيما يلي مثال يوضح السمة المُطبقة على القيمة المرجعة للدالة:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

يمكنك تعيين الخاصية Connection لتحديد اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال ناقل خدمة Azure لاستخدامها، كما هو موضح في المثال التالي:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

للحصول على مثال كامل، انظر المثال.

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

الديكور

ينطبق فقط على نموذج برمجة 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.

الطراز v4

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

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

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

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

الطراز v3

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

الخاصية	الوصف
النوع	يجب تعيينه إلى "serviceBus". يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه	يجب تعيينه إلى "خارج". يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاسم	اسم المتغير الذي يُمثل قائمة الانتظار أو رسالة الموضوع في التعليمات البرمجية للدالة. قم بتعيينه إلى "$return" للإشارة إلى القيمة المرجعة للدالة.
queueName	اسم قائمة الانتظار. لا تقم بتعيينه إلا في حالة إرسال رسائل قائمة الانتظار، وليس لموضوع.
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# المستخدمة.

الملحق v5.x

استخدم النوع ServiceBusMessage عند إرسال الرسائل مع بيانات التعريف. يتم تعريف المعلمات على أنها سمات نوع return. استخدم ICollector<T> أو IAsyncCollector<T> لكتابة رسائل متعددة. يتم إنشاء رسالة عند استدعاء الأسلوب Add.

عندما تكون قيمة المعلمة خالية عندما تخرج الدالة، فإن Functions لا تنشئ رسالة.

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

[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.

الدالات 2.x وأعلى

استخدم النوع الرسالة عند إرسال الرسائل مع بيانات التعريف. يتم تعريف المعلمات على أنها سمات نوع return. استخدم ICollector<T> أو IAsyncCollector<T> لكتابة رسائل متعددة. يتم إنشاء رسالة عند استدعاء الأسلوب Add.

في 30 سبتمبر 2026، سنتقاعد مكتبات SDK ناقل خدمة Azure WindowsAzure.ServiceBus وMicrosoft.Azure.ServiceBus و com.microsoft.azure.servicebus، والتي لا تتوافق مع إرشادات Azure SDK. سننهي أيضا دعم بروتوكول SBMP، لذلك لن تتمكن من استخدام هذا البروتوكول بعد 30 سبتمبر 2026. قم بالترحيل إلى أحدث مكتبات Azure SDK، والتي توفر تحديثات أمان هامة وقدرات محسنة، قبل ذلك التاريخ.

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

عندما تكون قيمة المعلمة خالية عندما تخرج الدالة، فإن Functions لا تنشئ رسالة.

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

[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.

الدالات 1.x

استخدم النوع BrokeredMessage عند إرسال الرسائل مع بيانات التعريف. يتم تعريف المعلمات على أنها سمات نوع return. عندما تكون قيمة المعلمة خالية عندما تخرج الدالة، فإن Functions لا تنشئ رسالة.

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

[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.

الملحق 5.x وما أعلى

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

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

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

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

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

الدالات 2.x وأعلى

تدعم الإصدارات السابقة من هذا الملحق في عملية العامل المعزولة الربط فقط بالأنواع الخاصة بالمراسلة. تتوفر خيارات إضافية للملحق 5.x والإضافات

الدالات 1.x

لا يدعم الإصدار 1.x من الدالات عملية العامل المعزولة. لاستخدام نموذج العامل المعزول، قم بترقية التطبيق الخاص بك إلى Functions 4.x.

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

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

الطراز v4

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

الطراز v3

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

الناتج إلى "ناقل خدمة 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

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

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

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

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

• قم بتشغيل وظيفة عند إنشاء قائمة انتظار أو رسالة موضوع( المشغل)