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

  • مقالة
  • قراءة خلال 16 دقائق

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

مثال

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

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

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

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

إليك ملف دالة.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)"

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

يتم تعريف مشغل قائمة انتظار التخزين في دالة.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# قيد المعالجة والعملية المعزولةالسمة QueueTriggerAttribute لتحديد الدالة. يستخدم البرنامج النصي C # بدلا من ذلك ملف تكوين function.json.

في مكتبات الفئات 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 يشير إلى سلسلة اتصال موقع التخزين.

التكوين

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

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

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

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

الاستخدام

ملاحظة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الخصائص أعضاء في رسالة قائمة انتظار السحابة الفئة.

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

الاتصالات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

هام

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

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

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

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

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

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

تأمين التحرير سريعًا

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

عند بدء تشغيل الدالة، تبدأ معالجة الرسالة تحت الشروط التالية.

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

يتم معالجة كافة آليات الرؤية بواسطة خدمة موقع التخزين، وليس وقت تشغيل الدالات.

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

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

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

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

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

ملاحظة

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

التزامن

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

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

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

خصائص مضيف.json

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

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