ربط بيانات إدخال تخزين Azure Blob لوظائف Azure

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

يسمح لك ربط الإدخال بقراءة بيانات تخزين blob كإدخال إلى دالة Azure.

للمزيد من المعلومات حول تفاصيل الإعداد والتكوين، راجع «overview».

مثال

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


The following example is a [C# function](functions-dotnet-class-library.md) that uses a queue trigger and an input blob binding. The queue message contains the name of the blob, and the function logs the size of the blob.

[FunctionName("BlobInput")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

يحتوي هذا القسم على الأمثلة التالية:

مشغل HTTP، والبحث عن اسم blob من سلسلة الاستعلام

يظهر المثال التالي دالة Java التى تستخدم HttpTrigger التعليق التوضيحي لتلقي معلمة تحتوي على اسم ملف في blob storage container. BlobInputثم يقرأ التعليق التوضيحي الملف ويمرر محتوياته إلى الدالة باسم abyte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

مشغل قائمة الانتظار، تلقي اسم blob من رسالة قائمة الانتظار

يظهر المثال التالي دالة Java التي تستخدمQueueTrigger التعليق التوضيحي لتلقي رسالة تحتوي على اسم ملف في blob storage container. BlobInputثم يقرأ التعليق التوضيحي الملف ويمرر محتوياته إلى الدالة باسم abyte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

من مكتبة وقت تشغيل دوال Java، استخدم تعليق @BlobInput التوضيحي على معلمات الدالة التي تأتي قيمتها من blob. يمكن استخدام هذا التعليق التوضيحي مع أنواع Java الأصلية أو عناصر POJO أو القيم بدون قيمة باستخدام Optional<T>.

يظهر المثال التالي ارتباطات إدخال وإخراج blob في ملفfunction.json والتعليمة البرمجية JavaScript التي تستخدم الارتباطات. تقوم الدالة بنسخ blob. يتم تشغيل الدالة بواسطة رسالة قائمة انتظار تحتوي على blob للنسخ. تُسمى blob الجديدة {originalblobname}-Copy.

في ملفfunction.json، queueTriggerتُستخدم خاصية بيانات التعريف لتحديد اسم blob في path الخصائص:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

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

هنا رمز JavaScript:

module.exports = async function(context) {
    context.log('Node.js Queue trigger function processed', context.bindings.myQueueItem);
    context.bindings.myOutputBlob = context.bindings.myInputBlob;
};

يوضح المثال التالي ربط إدخال نقطة، معرف في ملف function.json ، مما يجعل بيانات النقطة الواردة متوفرة للدالة PowerShell .

وإليك تكوين json :

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

إليك رمز الدالة:

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

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

يظهر المثال التالي ارتباطات الإدخال والإخراج blob في function.json الملف ورمز Python التعليمات البرمجية التي تستخدم الارتباطات. تقوم الدالة بنسخ blob. يتم تشغيل الدالة بواسطة رسالة قائمة انتظار تحتوي على blob للنسخ. تُسمى blob الجديدة {originalblobname}-Copy.

في ملفfunction.json، queueTriggerتُستخدم خاصية بيانات التعريف لتحديد اسم blob في path الخصائص:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "queuemsg",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "inputblob",
      "type": "blob",
      "dataType": "binary",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "$return",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

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

dataTypeتحدد الخاصية الربط المستخدم. تتوفر القيم التالية لدعم استراتيجيات الربط المختلفة:

قيمة الربط افتراضي الوصف مثال
string -N يستخدم الربط العام ويحول نوع الإدخال كـstring def main(input: str)
binary -N يستخدم الربط العام ويحول نوع الإدخال كـbytesPython object def main(input: bytes)

إذا dataTypeلم يتم تعريف الخاصية في function.json، تكون القيمة الافتراضية string.

فيما يلي التعليمة البرمجية لـ Python:

import logging
import azure.functions as func


# The input binding field inputblob can either be 'bytes' or 'str' depends
# on dataType in function.json, 'binary' or 'string'.
def main(queuemsg: func.QueueMessage, inputblob: bytes) -> bytes:
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    return inputblob

السمات

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

في مكتبات الفئات C # ، استخدم BlobAttribute ، الذي يأخذ المعلمات التالية:

المعلمة الوصف
BlobPath الطريق إلى blob.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع الاتصالات.
Access يشير إلى ما إذا كنت ستقرأ أو تكتب.

يوضح المثال التالي كيف يأخذ منشئ السمة المسار إلى النقطة ومعلمة FileAccess تشير إلى قراءة لربط الإدخال:

[FunctionName("BlobInput")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

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

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

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

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

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

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

@BlobInputتمنحك السمة حق الوصول إلى blob الذي أدي إلى تشغيل الدالة. إذا كنت تستخدم byte array مع السمة، قم بتعيين dataType إلى binary. الإشارة إلىمثال الإدخال للحصول على التفاصيل.

التكوين

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

خاصية function.json الوصف
النوع يجب تعيينها إلى blob.
⁧⁩direction⁧⁩ يجب تعيينها إلى in. تتم الإشارة إلى الاستثناءات في قسم الاستخدام.
⁧⁩الاسم⁧⁩ اسم المتغير الذي يمثل كائن ثنائي كبير الحجم في التعليمات البرمجية للوظيفة.
المسار الطريق إلى blob.
الاتصال اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع «Connections».
dataType بالنسبة للغات المكتوبة ديناميكيا، يحدد نوع البيانات الأساسي. القيم المُحتملة هي string وbinary أو stream. لمزيد من التفاصيل، راجع مفاهيم المشغلات والروابط.

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

الاستخدام

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

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

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

يتم دعم أنواع المعلمات التالية لكافة الإصدارات:

  • Stream
  • TextReader
  • string
  • Byte[]

أنواع المعلمات التالية خاصة بإصدار الإضافة وتتطلب FileAccess.ReadWrite في مكتبة فئة C # الخاصة بك:

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

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

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

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

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

الارتباط ب string، أو Byte[] يوصى به فقط عندما يكون حجم الفقاعة صغيرا. يوصى بذلك لأنه يتم تحميل محتويات blob بالكامل في الذاكرة. بالنسبة لمعظم النقط، استخدم علامة Stream أو CloudBlockBlob نوعا. لمزيد من المعلومات، راجع التزامن واستخدام الذاكرة.

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

@BlobInputتمنحك السمة حق الوصول إلى blob الذي أدي إلى تشغيل الدالة. إذا كنت تستخدم byte array مع السمة، قم بتعيين dataType إلى binary. الإشارة إلىمثال الإدخال للحصول على التفاصيل.

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

يمكنك الوصول إلى بيانات كائن ثنائي كبير الحجم عبر معلمة تطابق الاسم المعين بواسطة معلمة اسم الربط في ملفfunction.json.

الوصول إلى بيانات blob عبر المعلمة المكتوبة ك InputStream. الإشارة إلىمثال الإدخال للحصول على التفاصيل.

الاتصالات

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

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

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

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

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

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

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

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

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

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

<CONNECTION_NAME_PREFIX>__blobServiceUri 1 يمكن استخدامها كاسم مستعار. إذا كان سيتم استخدام تكوين الاتصال بواسطة مشغل نقطة ، blobServiceUri فيجب أن يكون مصحوبا queueServiceUriأيضا ب . انظر أدناه.

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

الخاصية قالب متغير البيئة الوصف قيمة المثال
Blob Service URI <CONNECTION_NAME_PREFIX>__blobServiceUri مستوى البيانات URI لخدمة blob التي تتصل بها ، باستخدام مخطط HTTPS. https://< storage_account_name.blob.core.windows.net>
URI لخدمة قائمة الانتظار (مطلوب لمشغلات blob2) <CONNECTION_NAME_PREFIX>__queueServiceUri مستوى البيانات URI لخدمة قائمة انتظار، باستخدام مخطط HTTPS. هذه القيمة مطلوبة فقط لمشغلات blob. https://< storage_account_name.queue.core.windows.net>

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

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

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

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

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

هام

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

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

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

يجب أيضا منح أذونات إضافية لاتصال AzureWebJobsStorage. 2
ربط بيانات الإدخال قارئ بيانات للبيانات الثنائية الكبيرة للتخزين
ربط بيانات الإخراج ⁧⁩مالك بيانات كائن ثنائي كبير الحجم للتخزين⁧⁩

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

2 يتم استخدام اتصال AzureWebJobsStorage داخليا للنقاط وقوائم الانتظار التي تمكن المشغل. إذا تم تكوينه لاستخدام اتصال يستند إلى الهوية، فستحتاج إلى أذونات إضافية تتجاوز المتطلبات الافتراضية. يتم تغطية هذه الأدوار من خلال أدوار مالك بيانات Storage Blob و Storage Queue Data Contributor و Storage Account Contributor . لمعرفة المزيد، راجع الاتصال بمساحة تخزين المضيف باستخدام هوية.

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