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

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

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

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

مثال

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

يعرض المثال التالي دالة C#‎ التي تنشئ رسالة قائمة انتظار لكل طلب HTTP يتم استلامه.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

يوضح المثال التالي دالة 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.

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

إليك ملف دالة.json:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

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

ها هي كود JavaScript:

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

يمكنك إرسال رسائل متعددة في وقت واحد عن طريق تعريف صفيف رسالة لربط مخرجات myQueueItem. ترسل التعليمات البرمجية JavaScript التالية رسالتي قائمة انتظار مع قيم تعليمات برمجية مضمّنة لكل طلب HTTP تم استلامه.

module.exports = async function(context) {
    context.bindings.myQueueItem = ["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 هو نفسه في كلتا الحالتين.

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

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

لتعيين رسالة فردية في قائمة الانتظار، يمكنك تمرير قيمة مفردة إلى أسلوب 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'

لإنشاء رسائل متعددة في قائمة الانتظار، أعلن عن معلمة كنوع القائمة المناسب ومرر صفيف من القيم (التي تطابق نوع القائمة) إلى أسلوب set.

import azure.functions as func
import typing

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

    msg.set(['one', 'two'])

    return 'OK'

السمات

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

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

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

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

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

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

يمكنك استخدام StorageAccount السمة لتحديد حساب التخزين في مستوى الفئة أو الأسلوب أو مستوى معاملة. وللاطلاع على المزيد من المعلومات، راجع المشغل - السمات.

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

يسمح لك التعليق التوضيحي 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 كمثيل OutputBindingT<>.

التكوين

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

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

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

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

الاستخدام

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

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

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

اكتب رسالة قائمة انتظار واحدة باستخدام معلمة أسلوب مثل out T paramName. يمكنك استخدام نوع إرجاع الأسلوب بدلاً من معلمة out، وT يمكن أن تكون أي من الأنواع التالية:

للحصول على أمثلة باستخدام هذه الأنواع، انظر إلي مستودع GitHub لملحق البرنامج.

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

للحصول على أمثلة باستخدام QueueMessageوQueueClient، راجع مستودع GitHub للملحق.

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

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

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

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

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

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

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

يتوفر عنصر قائمة انتظار المخرجات عبر context.bindings.<NAME> حيث <NAME> يتطابق مع الاسم المحدد في function.json. يمكنك استخدام سلسلة أو كائن JSON قابل للتسلسل لحمولة عنصر قائمة الانتظار.

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

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

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

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

الاتصالات

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

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

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

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

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

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

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

إذا كنت تستخدم الإصدار 5.x أو أعلى من الملحق، فبدلا من استخدام سلسلة اتصال مع سر، يمكنك أن يكون التطبيق يستخدم هوية Azure Active Directory. للقيام بذلك، يمكنك تعريف الإعدادات ضمن بادئة شائعة تعين إلى الخاصية 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 RBAC، باستخدام أدوار مضمنة أو مخصصة توفر هذه الأذونات.

هام

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

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

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

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

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

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