أنماط تعبير ربط Azure Functions

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

يتم تعريف معظم التعبيرات عن طريق وضعها بين أقواس متعرجة. على سبيل المثال، في وظيف مشغل قائمة انتظار، يتم حل {queueTrigger} إلى نص رسالة قائمة الانتظار. إذا كانت الخاصية path لربط إخراج blob بالقيمة container/{queueTrigger} ويتم تشغيل الوظيفة بواسطة رسالة قائمة الانتظار HelloWorld، يتم إنشاء blob بالاسم HelloWorld.

أنواع تعبيرات الرابط

• إعدادات التطبيق
• اسم ملف المشغل
• بيانات تعريف المشغل
• حمولات «JSON»
• المعرّف الفريد العمومي الجديد
• التاريخ والوقت الحاليان

تعبيرات الربط - إعدادات التطبيق

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

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

يتم تعريف تعبيرات ربط إعداد التطبيق بشكل مختلف عن تعبيرات الربط الأخرى: حيث تحيط بها علامات النسبة المئوية بدلاً من الأقواس المجعدة. على سبيل المثال إذا كان مسار ربط إخراج blob بالقيمة %Environment%/newblob.txt وقيمة إعداد التطبيق Environment هي Development، سيتم إنشاء blob في الحاوية Development.

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

ملاحظة

تعتبر الخاصية connection للمشغلات والروابط حالة خاصة وتحل القيم تلقائيًا كإعدادات للتطبيق، دون علامات النسبة المئوية.

المثال التالي هو مشغل Azure Queue Storage يستخدم إعداد تطبيق %input_queue_name% لتعريف قائمة الانتظار المطلوب تشغيله عليها.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input_queue_name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

يمكنك استخدام نفس الأسلوب في مكتبات الفئات:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input_queue_name%")]string myQueueItem, 
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

اسم ملف المشغل

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

على سبيل المثال، في ربط مشغل Blob التالي، يكون نمط path بالقيمة sample-images/{filename}، الذي ينشئ تعبير ربط بالاسم filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

يمكن استخدام التعبير filename في ربط إخراج لتحديد اسم blob الذي يتم إنشاؤه:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

تتوفر لدى تعليمة الوظيفة البرمجية إمكانية الوصول إلى هذه القيمة نفسها باستخدام filename كاسم معلمة:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)  
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
} 

تنطبق نفس القدرة على استخدام تعبيرات الربط والأنماط على السمات في مكتبات الفئات. في المثال التالي، تمثل معلمات منشئ السمة نفس قيم path كما في أمثلة function.json السابقة:

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger log)
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
}

يمكنك أيضًا إنشاء تعبيرات لأجزاء من اسم الملف. في المثال التالي، يتم تشغيل الوظيفة فقط على أسماء الملفات التي تطابق نمط ما: anyname-anyfile.csv

{
    "name": "myBlob",
    "type": "blobTrigger",
    "direction": "in",
    "path": "testContainerName/{date}-{filetype}.csv",
    "connection": "OrderStorageConnection"
}

لمزيد من المعلومات حول كيفية استخدام التعبيرات والأنماط في سلسلة مسار Blob، راجع مرجع ربط Blob التخزين.

بيانات تعريف المشغل

بالإضافة إلى حمولة البيانات التي يوفرها المشغل (مثل محتوى رسالة قائمة الانتظار التي أدت إلى تشغيل وظيفة)، توفر العديد من المشغلات قيم بيانات تعريف إضافية. يمكن استخدام هذه القيم كمعلمات إدخال في C# وF# أو خصائص على كائن context.bindings في JavaScript.

على سبيل المثال، يدعم مشغل Azure Queue storag الخصائص التالية:

• QueueTrigger - يعمل على تشغيل محتوى الرسالة إذا كانت سلسلة صالحة
• DequeueCount
• ExpirationTime
• المعرّف
• InsertionTime
• NextVisibleTime
• PopReceipt

يمكن الوصول إلى قيم بيانات التعريف هذه في خصائص الملف function.json. على سبيل المثال، افترض أنك تستخدم مشغل قائمة انتظار وتحتوي رسالة قائمة الانتظار على اسم blob ترغب في قراءته. في الملف function.json، يمكنك استخدام خاصية بيانات التعريف queueTrigger في خاصية blob path، كما هو موضح في المثال التالي:

{
  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]
}

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

حمولات «JSON»

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

يوضح المثال التالي الملف function.json لوظيفة إخطار على الويب تتلقى اسم blob في JSON: {"BlobName":"HelloWorld.txt"}. ربط إدخال Blob يقرأ blob، ويرجع ربط إخراج HTTP محتويات blob في استجابة HTTP. لاحظ أن ربط إدخال Blob يحصل على اسم blob بالإشارة مباشرةً إلى الخاصية BlobName ("path": "strings/{BlobName}")

{
  "bindings": [
    {
      "name": "info",
      "type": "httpTrigger",
      "direction": "in",
      "webHookType": "genericJson"
    },
    {
      "name": "blobContents",
      "type": "blob",
      "direction": "in",
      "path": "strings/{BlobName}",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ]
}

لكي يعمل هذا في C# و#F، تحتاج إلى فئة تعرف الحقول إلى سيتم إلغاء تسلسلها، كما في المثال التالي:

using System.Net;
using Microsoft.Extensions.Logging;

public class BlobInfo
{
    public string BlobName { get; set; }
}
  
public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents, ILogger log)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    log.LogInformation($"Processing: {info.BlobName}");

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

في JavaScript، يتم إجراء إلغاء تسلسل JSON تلقائيًا.

module.exports = async function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
}

رمز النقاط

إذا كانت بعض الخصائص في حمولة JSON لديك عبارة عن كائنات ذات خصائص، يمكنك الرجوع إليها مباشرةً باستخدام رمز النقطة (.). لا يعمل هذا التضمين مع روابط تخزين Azure Cosmos DB أو Table .

على سبيل المثال، افترض أن JSON الخاص بك يبدو كما يلي:

{
  "BlobName": {
    "FileName":"HelloWorld",
    "Extension":"txt"
  }
}

يمكنك الرجوع مباشرةً إلى FileName بالشكل BlobName.FileName. مع تنسيق JSON هذا، إليك شكل الخاصية path في المثال السابق:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

في C#، ستحتاج إلى فئتين:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

إنشاء المعرفات الفريدة

يتم من خلال تعبير الربط {rand-guid} إنشاء GUID. ينشئ مسار blob التالي في الملف function.json blob باسم مثل 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}.txt"
}

الوقت الحالي

يتم حل تعبير الربط DateTime إلى DateTime.UtcNow. ينشئ مسار blob التالي في الملف function.json blob باسم مثل 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}.txt"
}

الربط في وقت التشغيل

في C#‎ ولغات ‎.NET الأخرى، يمكنك استخدام نمط ربط إلزامي، بدلاً من الارتباطات التعريفية في function.json والسمات. الربط الحتمي مفيد عندما تحتاج معلمات الربط إلى حسابها في وقت التشغيل بدلاً من وقت التصميم. لمعرفة المزيد، راجع مرجع المطور C#‎ أو مرجع مطور برنامج C# النصي.

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

استخدام قيمة إرجاع Azure Function