موقع تخزين قائمة انتظار Azure لوظائف Azure

موقع تخزين قائمة الانتظار بتشغيل وظيفة كما تتم إضافة رسائل إلى تخزين قائمة انتظار Azure.

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

هام

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

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

يُظهر المثال التالي دالة C#‎ التي تنفذ استطلاعات input-queue قائمة الانتظار وكتابة عدة رسائل إلى قوائم انتظار الإخراج في كل مرة تتم فيها معالجة عنصر قائمة انتظار.

[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.ToString()}"};

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

    // Queue Output messages
    return messages;
}

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

يُظهر المثال التالي دالة C#‎ التي تقوم باستطلاعات myqueue-items قائمة الانتظار وكتابة سجل في كل مرة تتم فيها معالجة عنصر قائمة انتظار.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

يُظهر المثال Java التالي دالة مشغل قائمة انتظار التخزين، والتي تسجل الرسالة التي تم تشغيلها في قائمة الانتظارmyqueuename.

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

الطراز v4

يوضح المثال التالي دالة TypeScript لمشغل قائمة الانتظار. دالة استطلاعات قائمة الانتظار myqueue-items وتكتب سجل في كل مرة تتم معالجة عنصر قائمة انتظار.

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

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

يشرح queueItemقسم الاستخدام . يوضح قسم بيانات التعريف للرسالة كافة المتغيرات الأخرى المعروضة.

الطراز v3

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

الطراز v4

يوضح المثال التالي دالة JavaScript لمشغل قائمة الانتظار. دالة استطلاعات قائمة الانتظار myqueue-items وتكتب سجل في كل مرة تتم معالجة عنصر قائمة انتظار.

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

يشرح queueItemقسم الاستخدام . يوضح قسم بيانات التعريف للرسالة كافة المتغيرات الأخرى المعروضة.

الطراز v3

يُظهر المثال التالي ربط مشغل قائمة الانتظار فيالدالة json وملف دالة JavaScript التي تستخدم الربط. دالة استطلاعات قائمة الانتظار myqueue-items وتكتب سجل في كل مرة تتم معالجة عنصر قائمة انتظار.

إليك الملف function.json:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

قسم التكوين يشرح هذه الخصائص.

إشعار

تعكس معلمة الاسم كما context.bindings.<name> في التعليمات البرمجية JavaScript التي تحتوي على عنصر البيانات الأساسية لقائمة الانتظار. يتم تمرير البيانات الأساسية أيضًا كمعلمة ثانية إلى الدالة.

ها هي كود JavaScript:

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

يوضح قسم الاستخدامmyQueueItem، الذي تم تسميته من قبل الخاصية name في دالة json. يوضح قسم بيانات التعريف للرسالة كافة المتغيرات الأخرى المعروضة.

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

يتم تعريف مشغل قائمة انتظار التخزين في دالة.json الملف حيث يتم تعيينه type إلى مجموعةqueueTrigger.

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

التعليمة برمجية في ملفتشغيل.ps1 بتعريف معلمة كما$QueueItem، والذي يسمح لك بقراءة رسالة قائمة الانتظار في الدالة الخاصة بك.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

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

الإصدار 2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

v1

يتم تعريف مشغل قائمة انتظار التخزين في دالة.json الملف حيث يتم تعيينه النوع إلى المجموعةqueueTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

تعلن التعليمة البرمجية _init_.py عن المعلمة كfunc.QueueMessage والتي تسمح بإمكانية قراءة رسالة قائمة الانتظار في الدالة لديك.

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

السمات

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

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

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

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

يوضح هذا المثال أيضا تعيين إعداد سلسلة الاتصال في السمة نفسها.

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

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

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

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

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

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

QueueTriggerيمنح التعليق التوضيحي حق الوصول إلى قائمة الانتظار التي تقوم بتشغيل الدالة. يجعل المثال التالي رسالة قائمة الانتظار متوفرة للدالة عبرmessage المعلمة.

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

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}

الخاصية	‏‏الوصف
name	يُعلن اسم المعلمة في توقيع الدالة. عندما يتم تشغيل الدالة، تحتوي قيمة هذه المعلمة على محتويات رسالة قائمة الانتظار.
queueName	يعلن اسم قائمة الانتظار في موقع التخزين.
connection	يشير إلى سلسلة اتصال موقع التخزين.

الديكور

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

بالنسبة لوظائف Python v2 المعرفة باستخدام المحسنات، تحدد الخصائص التالية على queue_trigger مصمم الديكور مشغل تخزين قائمة الانتظار:

الخاصية	‏‏الوصف
arg_name	يُعلن اسم المعلمة في توقيع الدالة. عندما يتم تشغيل الدالة، تحتوي قيمة هذه المعلمة على محتويات رسالة قائمة الانتظار.
queue_name	يعلن اسم قائمة الانتظار في موقع التخزين.
connection	يشير إلى سلسلة اتصال موقع التخزين.

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

التكوين

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

الطراز v4

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

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

الطراز v3

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

الخاصية	الوصف
النوع	يجب تعيينه إلى queueTrigger. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه	فيدالة.jsonملف فقط. يجب تعيينه إلى in. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاسم	اسم المتغير الذي يحتوي على عنصر البيانات الأساسية في قائمة الانتظار في رمز الدالة.
queueName	اسم قائمة انتظار الاستطلاع.
الاتصال	اسم إعداد التطبيق أو مجموعة إعداد تحدد كيفية الاتصال بقوائم انتظار Azure. راجع الاتصالات.

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

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

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

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

الاستخدام

إشعار

تتوقع الدالات base64 سلسلة ترميز. ترميز أي تعديلات على نوع الترميز (لإعداد البيانات base64سلسلة مشفرة ) تحتاج إلى تنفيذها في خدمة الاتصال.

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

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

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

مكتبة الصف قيد المعالجة

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

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

الملحق 5.x+

الوصول إلى بيانات الرسالة باستخدام معلمة أسلوب مثل string paramName. paramName هو القيمة المحددة في QueueTriggerAttribute. يمكن الربط إلى أي من الأنواع التالية:

• كائن .NET CLR قديم عادي (POCO)
• string
• byte[]
• رسالة قائمة الانتظار

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

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

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

يتم تحديد حساب التخزين للاستخدام بالترتيب التالي:

• خاصية المشغل أو خاصية Connection لسمة الربط.
• تُطبَّق السمة StorageAccount على المعلمة نفسها الخاصة بسمة المشغّل أو الربط.
• السمة StorageAccount المطبقة على الوظيفة.
• StorageAccountالسمة التي تم تطبيقها على الفئة.
• حساب التخزين الافتراضي لتطبيق الدوال المُعرَّف في إعداد التطبيق AzureWebJobsStorage.

الملحق 2.x+

الوصول إلى بيانات الرسالة باستخدام معلمة أسلوب مثل string paramName. paramName هو القيمة المحددة في QueueTriggerAttribute. يمكن الربط إلى أي من الأنواع التالية:

• عنصر CLR القديم (POCO)
• string
• byte[]
• رسالة قائمة انتظار السحابة

يحاول وقت تشغيل «الوظائف»، عند الارتباط بكائن، إلغاء تسلسل حمولة JSON في مثيل فئة عشوائية تم تحديدها في التعليمات البرمجية لديك. إذا حاولتَ الارتباط بـ CloudQueueMessage وظهرت لك رسالة خطأ، فتأكد من أن لديك مرجعًا إلى إصدار Storage SDK الصحيح.

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

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

يتم تحديد حساب التخزين للاستخدام بالترتيب التالي:

• خاصية المشغل أو خاصية Connection لسمة الربط.
• تُطبَّق السمة StorageAccount على المعلمة نفسها الخاصة بسمة المشغّل أو الربط.
• السمة StorageAccount المطبقة على الوظيفة.
• StorageAccountالسمة التي تم تطبيقها على الفئة.
• حساب التخزين الافتراضي لتطبيق الدوال المُعرَّف في إعداد التطبيق AzureWebJobsStorage.

الملحق 5.x+

يمكن ربط مشغل قائمة الانتظار بالأنواع التالية:

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

¹ لاستخدام هذه الأنواع، تحتاج إلى الرجوع إلى Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 أو أحدث والتبعيات الشائعة لروابط نوع SDK.

الملحق 2.x+

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

قائمة الانتظار يتيح لك التعليق التوضيحي الوصول إلى رسالة قائمة الانتظار التي أدت إلى الدالة.

الطراز v4

الوصول إلى عنصر قائمة الانتظار كوسيطة أولى لدالتك. إذا كانت البيانات الأساسية JavaScript Object Notation، يتم إلغاء تسلسل القيمة في العنصر.

الطراز v3

الوصول إلى عنصر قائمة الانتظار باستخدام context.bindings.<NAME> المكان <NAME> الذي يطابق القيمة المعرفة في function.json. إذا كانت البيانات الأساسية JavaScript Object Notation، يتم إلغاء تسلسل القيمة في العنصر.

قم بالوصول إلى رسالة قائمة الانتظار عبر معلمة السلسلة التي تطابق الاسم المعين بواسطة nameمعلمة الربط في ملف دالة.json.

الوصول إلى رسالة قائمة الانتظار عبر المعلمة المكتوبة كقائمة انتظار.

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

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

خصائص بيانات تعريف الرسالة هي أعضاء في فئة CloudQueueMessage .

يمكن الوصول إلى خصائص بيانات تعريف الرسالة من context.triggerMetadata.

يمكن الوصول إلى خصائص بيانات تعريف الرسالة من المعلمة التي تم تمريرها $TriggerMetadata .

الخاصية	نوع	‏‏الوصف
QueueTrigger	string	البيانات الأساسية لقائمة الانتظار (إذا كانت سلسلة صحيحة). إذا كانت رسالة البيانات الأساسية لقائمة الانتظار سلسلة، QueueTrigger يكون لها نفس قيمة المتغير المسمى من قبلnameالخاصية فيدلالة.json.
DequeueCount	long	عدد المرات التي آلغي فيها حذف هذه الرسالة.
ExpirationTime	DateTimeOffset	الوقت الذي تنتهي فيه سريان الرسالة.
Id	string	معرّف رسالة قائمة الانتظار.
InsertionTime	DateTimeOffset	الوقت الذي أُضيفت فيه الرسالة إلى قائمة الانتظار.
NextVisibleTime	DateTimeOffset	الوقت الذي تكون فيه الرسالة مرئية بعد ذلك.
PopReceipt	string	إيصال الرسالة بوب.

يمكن الوصول إلى خصائص بيانات تعريف الرسالة التالية من معلمة الربط التي تم تمريرها (msgفي الأمثلة السابقة).

الخاصية	‏‏الوصف
body	حمولة قائمة الانتظار كسلسلة.
dequeue_count	عدد المرات التي آلغي فيها حذف هذه الرسالة.
expiration_time	الوقت الذي تنتهي فيه سريان الرسالة.
id	معرّف رسالة قائمة الانتظار.
insertion_time	الوقت الذي أُضيفت فيه الرسالة إلى قائمة الانتظار.
time_next_visible	الوقت الذي تكون فيه الرسالة مرئية بعد ذلك.
pop_receipt	إيصال الرسالة بوب.

الاتصالات

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

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

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

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

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

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

هام

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

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

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

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

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

لمعالجة رسائل غير قابلة للمعالجة يدويا، تحقق عدد قائمة الانتظار من رسالة قائمة الانتظار.

نظرة خاطفة ثم قفل

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

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

تحقق الخوارزمية

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

الخوارزمية تستخدم المنطق التالي:

• عند العثور على رسالة، ينتظر وقت التشغيل 100 مللي ثانية ثم يتحقق من وجود رسالة أخرى.
• عند العثور على أية رسالة، ينتظر حوالي 200 مللي ثانية قبل المحاولة مرة أخرى.
• بعد محاولات الفشل اللاحقة للحصول على رسالة قائمة انتظار، يستمر وقت الانتظار لزيادة حتى يصل إلى الحد الأقصى لوقت الانتظار، الذي الافتراضي إلى دقيقة واحدة.
• يكون الحد الأقصى لوقت الانتظار قابل للتكوين عبر maxPollingInterval الخاصية في مضيف ملف json .

أثناء التطوير المحلي، يكون الحد الأقصى للفاصل الزمني للاستقصاء افتراضيا إلى ثانيتين.

إشعار

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

التزامن

عند وجود عدة رسائل قائمة انتظار الانتظار، يسترد مشغل قائمة الانتظار دفعة من الرسائل واستدعاء مثيلات الدالة بشكل متزامن لمعالجتها. حجم الدُفعة افتراضيًا هو 16. في حين ان يحصل على عدد تتم معالجتها وصولًا إلي 8 وقت التشغيل يحصل على دفعة أخرى ويبدأ معالجة تلك الرسائل. لذا فإن الحد الأقصى لعدد الرسائل المتزامنة التي تتم معالجتها لكل وظيفة على جهاز VM (VM) هو 24. ينطبق هذا الحد بشكل منفصل على كل دالة في قائمة انتظار التشغيل على كل VM. إذا كان تطبيق الوظائف الخاص بك يتوسع إلى أجهزة ظاهرية متعددة، ينتظر كل جهاز ظاهري المشغلات ويحاول تشغيل الوظائف. على سبيل المثال، في حالة تطبيق دالة مقياس إلى 3 VMs، الحد الأقصى الافتراضي لعدد المثيلات المتزامنة من دالة قائمة انتظار واحدة التي تم تشغيلها هو 72.

حجم الدُفعة والحد للحصول على دفعة جديدة قابلة للتكوين فيمضيف ملف .json. إذا كنت تريد تصغير التنفيذ المتوازي للدلالات التي يتم تشغيلها في قائمة الانتظار في تطبيق دالة، يمكنك تعيين حجم المجموعة إلى 1. يلغي هذا الإعداد التزامن فقط طالما يعمل تطبيق الدالة على جهاز ظاهري واحد (VM).

يمنع مشغل قائمة الانتظار تلقائيا دالة من معالجة رسالة قائمة انتظار عدة مرات في نفس الوقت.

خصائص مضيف.json

يحتوي مضيف.jsonملف إعدادات تتحكم في سلوك مشغل قائمة الانتظار. راجع إعدادات مضيف.json قسم للحصول على تفاصيل حول الإعدادات المتوفرة.

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

• كتابة رسائل تخزين قائمة الانتظار (ربط الإخراج)