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

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

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

هام

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

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

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

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

مثال

دعم Go غير متوفر حاليا لهذا الربط.

يمكن إنشاء دالة 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(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([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(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([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() إلى الأسلوب .

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

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

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

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

يجب تعريف معلمة دالة الإخراج على أنها func.Out[func.QueueMessage]أو func.Out[str]أو func.Out[bytes]. راجع مثال الإخراج للحصول على التفاصيل.

الاتصالات

يتم تعيين connection الخاصية على مفتاح في إعدادات التطبيق يعيد قيمة مستخدمة في وقت تشغيل الدوال للاتصال بحساب التخزين المستخدم من قبل الامتداد. تعتمد قيمة إعداد خاصية الاتصال على نوع الاتصال:

  • اتصال الهوية المدارة: connection الخاصية مشتركة <CONNECTION_NAME_PREFIX> بين مجموعة من الإعدادات التي تحدد معا اتصالا قائما على الهوية مع حساب التخزين. لمزيد من المعلومات، انظر تعريف الروابط الهوية.
  • Key Vault reference: connection إعداد الخاصية يعيد مرجع Azure Key Vault إلى الموقع الذي يتم فيه صيانة سلسلة الاتصال بشكل مركزي. لمزيد من المعلومات، راجع تعريف اتصالات Key Vault.
  • مرجع App Configuration: connection إعداد الخاصية يعيد مرجع تكوين Azure App يعيد سلسلة سلسلة الاتصال أو مرجع Key Vault. لمزيد من المعلومات، راجع تكوين Azure App في مقالة الاتصالات.
  • Connection string: connection إعداد الخاصية يعيد سلسلة حساب التخزين الفعلية سلسلة الاتصال. نظرا لأن سلسلة الاتصال تحتوي على مفاتيح سرية مشتركة، يجب أن تفكر في استخدام اتصال هوية مدار، عندما يكون ذلك ممكنا. لمزيد من المعلومات، راجع تعريف الروابط.

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

عندما تعدين connection إلى بادئة مفتاح أو مفتاح مسمى AzureWebJobsStorage أو إلى سلسلة فارغة، يستخدم امتداد الربط حساب التخزين الافتراضي للمضيف. لمزيد من المعلومات، راجع تحسين أداء التخزين.

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

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

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

  • Last updated on