مشاركة عبر

روابط مخرجات التخزين Azure Queue لوظائف Azure

  • مقالة

بإمكان Azure Functions إنشاء رسائل تخزين Azure Queue جديدة بإعداد ربط المخرجات.

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

هام

تستخدم هذه المقالة علامات التبويب لدعم إصدارات متعددة من نموذج البرمجة 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. نوصي بشدة بترحيل تطبيقاتك إلى نموذج العامل المعزول للحصول على الدعم الكامل.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

للحصول على مثال شامل حول كيفية تكوين ربط إخراج لتخزين قائمة الانتظار، راجع إحدى هذه المقالات:

يعرض المثال التالي دالة Java التي تنشئ رسالة قائمة انتظار عند تشغيلها بواسطة طلب HTTP.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

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

للحصول على مثال شامل حول كيفية تكوين ربط إخراج لتخزين قائمة الانتظار، راجع إحدى هذه المقالات:

يوضح المثال التالي دالة TypeScript التي تم تشغيلها من قبل HTTP والتي تنشئ عنصر قائمة انتظار لكل طلب HTTP تم تلقيه.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

يوضح المثال التالي دالة JavaScript التي تم تشغيلها من قبل HTTP والتي تنشئ عنصر قائمة انتظار لكل طلب HTTP تم تلقيه.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

للحصول على مثال شامل حول كيفية تكوين ربط إخراج لتخزين قائمة الانتظار، راجع إحدى هذه المقالات:

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

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

باستخدام تكوين الربط هذا، يمكن لدالة PowerShell إنشاء رسالة قائمة انتظار باستخدام Push-OutputBinding. في هذا المثال، يتم إنشاء رسالة من سلسلة استعلام أو معلمة نص.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

لإرسال رسائل متعددة مرة واحدة، عرّف صفيف رسالة واستخدم Push-OutputBinding لإرسال الرسائل إلى ربط مخرجات Queue.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

للحصول على مثال شامل حول كيفية تكوين ربط إخراج لتخزين قائمة الانتظار، راجع إحدى هذه المقالات:

يوضح المثال التالي كيفية إخراج قيم مفردة ومتعددة إلى قوائم انتظار التخزين. التكوين المطلوب لـ function.json هو نفسه في كلتا الحالتين. يعتمد المثال على ما إذا كنت تستخدم نموذج برمجة v1 أو v2 Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

للحصول على مثال شامل حول كيفية تكوين ربط إخراج لتخزين قائمة الانتظار، راجع إحدى هذه المقالات:

السمات

تعتمد السمة التي تحدد ارتباط الإخراج في مكتبات C# على الوضع الذي تعمل فيه مكتبة فئة C#‎.

عند التشغيل في عملية عامل معزولة، يمكنك استخدام QueueOutputAttribute، الذي يأخذ اسم قائمة الانتظار، كما هو موضح في المثال التالي:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

يتم دعم المتغيرات التي تم إرجاعها فقط عند التشغيل في عملية عامل معزولة. لا يمكن استخدام معلمات الإخراج.

الديكور

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

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

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

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

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

يسمح لك التعليق التوضيحي QueueOutput بكتابة رسالة كمخرجات دالة. يعرض المثال التالي دالة مشغلة بواسطة HTTP تُنشئ رسالة قائمة انتظار.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
الخاصية ‏‏الوصف
name يُعلن اسم المعلمة في توقيع الدالة. عندما يتم تشغيل الدالة، تحتوي قيمة هذه المعلمة على محتويات رسالة قائمة الانتظار.
queueName يعلن اسم قائمة الانتظار في موقع التخزين.
connection يشير إلى سلسلة اتصال موقع التخزين.

تتم كتابة المعلمة المرتبطة بالتعليق التوضيحي QueueOutput كمثيل OutputBinding<T>.

التكوين

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

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

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

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

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

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى queue. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه يجب تعيينه إلى out. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاسم اسم المتغير الذي يمثل قائمة الانتظار في التعليمة البرمجية للدالة. تعيين $return إلى مرجع القيمة المرجعة للدالة.
queueName اسم الصف.
الاتصال اسم إعداد التطبيق أو مجموعة إعداد تحدد كيفية الاتصال بقوائم انتظار Azure. راجع الاتصالات.

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

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

الاستخدام

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

تعمل مكتبة فئة معالجة عامل معزولة تعمل دالة C# المحولة برمجيا في عملية معزولة عن وقت التشغيل.

حدد إصدارًا للاطلاع على تفاصيل الاستخدام للوضع والإصدار.

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

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

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

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

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

يوجد خياران للكتابة إلى قائمة انتظار من إحدى الدوال باستخدام التعليق التوضيحي QueueOutput:

  • قيمة الإرجاع: بتطبيق التعليق التوضيحي على الدالة نفسها، تتم كتابة القيمة المرجعة للدالة في قائمة الانتظار.

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

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

الناتج لرسالة قائمة الانتظار متوفر عبر Push-OutputBinding حيث يمكنك تمرير الوسائط التي تُطابق الاسم المُعين بواسطة معلمة name للربط في ملف function.json.

يوجد خياران للكتابة من دالتك إلى قائمة الانتظار المكونة:

  • القيمة المرجعة: تعيين الخاصية name في function.json إلى $return. مع هذا التكوين، تستمر القيمة المرجعة للدالة باعتبارها رسالة تخزين Queue.

  • أمر حتمي: تمرير قيمة إلى الأسلوب المُحدد الخاص بالمعلمة التي أُعلن عنها باعتبارها نوع Out. تستمر القيمة التي تم تمريرها إلى set باعتبارها رسالة تخزين Queue.

الاتصالات

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

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

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

للحصول على سلسلة اتصال، اتبع الخطوات الموضحة في إدارة مفاتيح الوصول إلى حسابات التخزين.

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

إذا كان اسم إعداد التطبيق يبدأ بـ "AzureWebJobs"، يمكنك تحديد باقي الاسم هنا فقط. على سبيل المثال، إذا قمت بتعيين connection إلى "MyStorage"، فإن وقت تشغيل الدوال يبحث عن إعداد تطبيق يسمى "AzureWebJobsMyStorage". إذا تركت connection فارغًا، فسيستخدم وقت تشغيل الدوال سلسلة اتصال التخزين الافتراضية في إعداد التطبيق المسمى AzureWebJobsStorage.

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

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

إذا كنت تقوم بإعداد connection إلى "AzureWebJobsStorage"، فشاهد الاتصال باستضافة التخزين بهوية. لجميع الاتصالات الأخرى، يتطلب الملحق الخصائص التالية:

الخاصية قالب متغير البيئة ‏‏الوصف مثال للقيمة
URI لخدمة قائمة الانتظار <CONNECTION_NAME_PREFIX>__queueServiceUri1 عنوان URI لمستوى البيانات لخدمة قائمة الانتظار التي تتصل بها، باستخدام نظام HTTPS. https://<storage_account_name>.queue.core.windows.net

يمكن استخدام 1 <CONNECTION_NAME_PREFIX>__serviceUri ك اسم مستعار. إذا تم توفير كلا النموذجين، queueServiceUri يتم استخدام النموذج. serviceUri لا يمكن استخدام النموذج عند استخدام تكوين الاتصال الكلي عبر الكائنات الثنائية كبيرة الحجم وقوائم الانتظار و/أو الجداول.

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

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

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

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

هام

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

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

نوع الربط مثال على الأدوار المضمنة
المشغِّل قارئ بيانات قائمة انتظار التخزين، معالج رسائل بيانات قائمة انتظار التخزين
ربط بيانات الإخراج مساهم بيانات قائمة انتظار التخزين، مرسل رسالة بيانات قائمة انتظار التخزين

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

Binding المرجع
Queue رموز خطأ قائمة الانتظار
كائن ثنائي كبير الحجم، جدول، قائمة الانتظار رموز خطأ Storage
كائن ثنائي كبير الحجم، جدول، قائمة الانتظار استكشاف الأخطاء وإصلاحها

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