مشغل تخزين Azure Blob لـ Azure Functions

يبدأ مشغل تخزين Blob في تشغيل الوظيفة عند اكتشاف كائن ثنائي كبير الحجم جديد أو محدث. يتم توفير محتويات كائن ثنائي كبير الحجم كمدخل إلى الوظيفة.

تلميح

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

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

هام

تستخدم هذه المقالة علامات التبويب لدعم إصدارات متعددة من نموذج البرمجة 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# التي تعمل في عملية عامل معزولة وتستخدم مشغل كائن ثنائي كبير الحجم مع كل من إدخال الكائن الثنائي كبير الحجم وروابط blob الناتجة. يتم تشغيل الوظيفة من خلال إنشاء كائن ثنائي كبير الحجم في حاوية test-sample-trigger. يقرأ ملفا نصيا من حاوية test-samples-input وينشئ ملفا نصيا جديدا في حاوية إخراج استنادًا إلى اسم الملف الذي تم تشغيله.

public static class BlobFunction
{
    [Function(nameof(BlobFunction))]
    [BlobOutput("test-samples-output/{name}-output.txt")]
    public static string Run(
        [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
        [BlobInput("test-samples-input/sample1.txt")] string myBlob,
        FunctionContext context)
    {
        var logger = context.GetLogger("BlobFunction");
        logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
        logger.LogInformation("Input Item = {myBlob}", myBlob);

        // Blob Output
        return "blob-output content";
    }
}

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

يظهر المثال التالي الوظيفة C#‎ الذي يكتب سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في الحاوية samples-workitems.

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

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

لمزيد من المعلومات حول السمة BlobTrigger، راجع السمات.

تقوم الوظيفة بكتابة سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في الحاويةmyblob.

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

الطراز v4

يوضح المثال التالي رمز TypeScript لمشغل كائن ثنائي كبير الحجم. تقوم الوظيفة بكتابة سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في الحاوية samples-workitems.

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

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

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

الطراز v3

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

الطراز v4

يوضح المثال التالي رمز JavaScript لمشغل كائن ثنائي كبير الحجم. تقوم الوظيفة بكتابة سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في الحاوية samples-workitems.

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

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

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

الطراز v3

يُظهر المثال التالي ربط مشغل كائن ثنائي كبير الحجم في الملفfunction.json وتعليمة JavaScript البرمجية التي تستخدم عملية ربط البيانات. تقوم الوظيفة بكتابة سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في الحاوية samples-workitems.

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

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

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

لمزيد من المعلومات حول خصائص الملف function.js، راجع قسم التكوين الذي يشرح هذه الخصائص.

ها هي كود JavaScript:

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

يوضح المثال التالي كيفية إنشاء وظيفة تعمل عند إضافة ملف إلى حاوية تخزين كائن ثنائي كبير الحجمsource.

يتضمن ملف تكوين الوظيفة (function.json) عملية ربط مع تعيين type لـ blobTrigger وdirection إلى in.

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

فيما يلي التعليمة البرمجية المرتبطة بملف run.ps1.

param([byte[]] $InputBlob, $TriggerMetadata)

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

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

الإصدار 2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

v1

تقوم الوظيفة بكتابة سجل عند إضافة كائن ثنائي كبير الحجم أو تحديثه في samples-workitemsالحاوية. إليك الملف function.json:

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

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

لمزيد من المعلومات حول خصائص الملف function.js، راجع قسم التكوين الذي يشرح هذه الخصائص.

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

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

---

السمات

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

تأخذ الدالة الإنشائية سمة المعلمات التالية:

المعلمة	‏‏الوصف‬
BlobPath	المسار إلى كائن ثنائي كبير الحجم.
Connection	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع الاتصالات.
الوصول	يشير إلى ما إذا كنت ستقرأ أو تكتب.
Source	تعيين مصدر الحدث المشغل. استخدم BlobTriggerSource.EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو BlobTriggerSource.LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية.

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

فيما يلي سمة BlobTrigger في توقيع أسلوب:

[Function(nameof(BlobFunction))]
[BlobOutput("test-samples-output/{name}-output.txt")]
public static string Run(
    [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
    [BlobInput("test-samples-input/sample1.txt")] string myBlob,
    FunctionContext context)

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

في مكتبات فئة C#‎، يأخذ مُنشئ السمة سلسلة مسار تشير إلى الحاوية للمراقبة واختيارياً نمط اسم كائن ثنائي كبير الحجم. إليك مثال:

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

يمكنك، حيث تأخذ السمة خاصية 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.

الديكور

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

بالنسبة إلى وظائف Python v2 المعرفة باستخدام المحسنات، تحدد الخصائص التالية على blob_trigger مصمم الديكور مشغل Blob Storage:

الخاصية	‏‏الوصف
arg_name	يُعلن اسم المعلمة في توقيع الدالة. عندما يتم تشغيل الدالة، تحتوي قيمة هذه المعلمة على محتويات رسالة قائمة الانتظار.
path	الحاوية المطلوب مراقبتها. قد يكون نمط اسم كائن ثنائي كبير الحجم.
connection	سلسلة الاتصال حساب التخزين.
source	تعيين مصدر الحدث المشغل. استخدم EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية.

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

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

تمنحك السمة @BlobTrigger حق الوصول إلى كائن ثنائي كبير الحجم الذي أدي إلى تشغيل الوظيفة. للحصول على التفاصيل، ارجع إلى مثال على المشغل. استخدم الخاصية source لتعيين مصدر الحدث المشغل. استخدم EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية. |

التكوين

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

الطراز v4

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

الخاصية	‏‏الوصف
المسار	الحاوية المطلوب مراقبتها. قد يكون نمط اسم كائن ثنائي كبير الحجم.
الاتصال	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع الاتصالات.
مصدر	تعيين مصدر الحدث المشغل. استخدم EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية.

الطراز v3

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

الخاصية	الوصف
النوع	يجب تعيينه إلى blobTrigger. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه	يجب تعيينه إلى in. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure. تتم الإشارة إلى الاستثناءات في قسم الاستخدام.
الاسم	اسم المتغير الذي يمثل blob في التعليمات البرمجية الدالة.
المسار	الحاوية المطلوب مراقبتها. قد يكون نمط اسم كائن ثنائي كبير الحجم.
الاتصال	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع الاتصالات.
مصدر	تعيين مصدر الحدث المشغل. استخدم EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية.

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

خاصية function.json	‏‏الوصف
النوع	يجب تعيينه إلى blobTrigger. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure.
الاتجاه	يجب تعيينه إلى in. يتم تعيين هذه الخاصية تلقائيا عند إنشاء المشغل في مدخل Microsoft Azure. تتم الإشارة إلى الاستثناءات في قسم الاستخدام.
الاسم	اسم المتغير الذي يمثل blob في التعليمات البرمجية الدالة.
المسار	الحاوية المطلوب مراقبتها. قد يكون نمط اسم كائن ثنائي كبير الحجم.
الاتصال	اسم إعداد تطبيق أو مجموعة إعداد تحدد كيفية الاتصال بـ Azure Blobs. راجع الاتصالات.
مصدر	تعيين مصدر الحدث المشغل. استخدم EventGrid لمشغل كائن ثنائي كبير الحجم قائم على شبكة الأحداث، والذي يوفر زمن انتقال أقل بكثير. الافتراضي هو LogsAndContainerScan، الذي يستخدم آلية الاستقصاء القياسية للكشف عن التغييرات في الحاوية.

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

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

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

الخاصية	نوع	‏‏الوصف
BlobTrigger	string	المسار إلى الكائنات الثنائية كبيرة الحجم المشغلة.
Uri	System.Uri	معرّف الموارد المنتظم (URI) الخاص بالكائنات الثنائية كبيرة الحجم للموقع الأساسي.
Properties	BlobProperties	خصائص نظام الكائنات الثنائية كبيرة الحجم.
Metadata	IDictionary<string,string>	بيانات التعريف المعرفة من قبل المستخدم للكائنات الثنائية كبيرة الحجم.

يُسجِّل المثال التالي المسار إلى الكائنات الثنائية كبيرة الحجم المشغِّلة، بما في ذلك الحاوية:

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

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

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

الخاصية	‏‏الوصف
blobTrigger	المسار إلى الكائنات الثنائية كبيرة الحجم المشغلة.
uri	معرّف الموارد المنتظم (URI) الخاص بالكائنات الثنائية كبيرة الحجم للموقع الأساسي.
properties	خصائص نظام الكائنات الثنائية كبيرة الحجم.
metadata	بيانات التعريف المعرفة من قبل المستخدم للكائنات الثنائية كبيرة الحجم.

الطراز v4

يمكن الحصول على بيانات التعريف من الخاصية triggerMetadata للكائن context المقدم، كما هو موضح في المثال التالي، والذي يسجل المسار إلى الكائنات الثنائية كبيرة الحجم المشغلة (blobTrigger)، بما في ذلك الحاوية:

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

الطراز v3

يمكن الحصول على بيانات التعريف من الخاصية bindingData للكائن context المقدم، كما هو موضح في المثال التالي، والذي يسجل المسار إلى الكائنات الثنائية كبيرة الحجم المشغلة (blobTrigger)، بما في ذلك الحاوية:

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

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

بيانات التعريف متوفرة من خلال المعلمة $TriggerMetadata.

الاستخدام

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

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

يمكن ربط مشغل الكائن الثنائي كبير الحجم بالأنواع التالية:

النوع	‏‏الوصف
string	محتوى الكائن الثنائي كبير الحجم كسلسلة. استخدم عندما يكون محتوى الكائن الثنائي كبير الحجم نصا بسيطا.
byte[]	وحدات البايت لمحتوى الكائن الثنائي كبير الحجم.
‏‏أنواع قابلة للتسلسل إلى JSON	عندما يحتوي كائن ثنائي كبير الحجم على بيانات JSON، تحاول الدالات إلغاء تسلسل بيانات JSON إلى نوع كائن CLR (POCO) قديم عادي.
دفق1	دفق إدخال لمحتوى الكائن الثنائي كبير الحجم.
BlobClient1، BlockBlobClient1، PageBlobClient1، AppendBlobClient1، BlobBaseClient1	عميل متصل بالكائن الثنائي كبير الحجم. توفر هذه المجموعة من الأنواع أكبر قدر من التحكم لمعالجة الكائن الثنائي كبير الحجم ويمكن استخدامها للكتابة مرة أخرى إلى الكائن الثنائي كبير الحجم إذا كان الاتصال لديه إذن كاف.

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

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

راجع أنواع الربط للحصول على قائمة بالأنواع المدعومة.

يُوصى بالربط بـ stringأو Byte[] فقط عندما يكون حجم الكائن الثنائي كبير الحجم صغيرًا. ويُوصى بذلك نظرًا لتحميل محتويات الكائن الثنائي كبير الحجم بالكامل في الذاكرة. بالنسبة إلى معظم الكائنات الثنائية كبيرة الحجم، استخدم نوع Stream أو BlobClient. لمزيد من المعلومات، راجع استخدام التزامن والذاكرة.

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

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

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

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

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

تمنحك السمة @BlobTrigger حق الوصول إلى كائن ثنائي كبير الحجم الذي أدي إلى تشغيل الوظيفة. للحصول على التفاصيل، ارجع إلى مثال على المشغل.

الطراز v4

الوصول إلى بيانات الكائن الثنائي كبير الحجم كوسيطة أولى للدالة الخاصة بك.

الطراز v3

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

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

يمكنك الوصول إلى بيانات كائن ثنائي كبير الحجم عبر المعلمة المكتوبة على أنها InputStream. للحصول على التفاصيل، ارجع إلى مثال على المشغل.

الاتصالات

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

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

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

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

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

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

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

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

إذا كنت تستخدم الإصدار 5.x أو أعلى من الملحق (الحزمة 3.x أو أعلى لمكدسات اللغات non-.NET)، فبدلا من استخدام سلسلة الاتصال مع سر، يمكنك أن يكون التطبيق يستخدم هوية Microsoft Entra. لاستخدام هوية، يمكنك تعريف الإعدادات ضمن بادئة شائعة تعين إلى الخاصية connection في تكوين المشغل والربط.

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

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

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

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

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

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

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

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

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

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

هام

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

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

نوع الربط	مثال على الأدوار المضمنة
المشغِّل	مالك بيانات تخزين كائن ثنائي كبير الحجمومساهم بيانات قائمة انتظار التخزين 1 يجب أيضا منح أذونات إضافية لاتصال AzureWebJobsStorage.2
ربط بيانات الإدخال	قارئ بيانات للبيانات الثنائية الكبيرة للتخزين
ربط بيانات الإخراج	مالك بيانات للبيانات الثنائية الكبيرة للتخزين

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

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

أنماط اسم كائن ثنائي كبير الحجم

يمكنك تحديد نمط اسم كائن ثنائي كبير الحجم في الخاصية path في function.json أو في الدالة الإنشائية للسمة BlobTrigger. يمكن أن يكون نمط الاسم تعبير عامل تصفية أو ربط. توفر الأقسام التالية أمثلة.

تلميح

لا يمكن أن يحتوي اسم الحاوية على محلل في نمط الاسم.

الحصول على اسم الملف والملحق

يوضح المثال التالي كيفية ربط اسم ملف كائن ثنائي كبير الحجم والملحق بشكل منفصل:

"path": "input/{blobname}.{blobextension}",

إذا تمت تسمية كائن ثنائي كبير الحجم original-Blob1.txt، فإن قيم المتغيرين blobname وblobextension في التعليمة البرمجية للوظيفة هي original-Blob1 وtxt.

تصفية على اسم كائن ثنائي كبير الحجم

يتم تشغيل المثال التالي فقط على الكائنات الثنائية كبيرة الحجم في الحاوية input التي تبدأ بالسلسلة "original-":

"path": "input/original-{name}",

إذا كان اسم كائن ثنائي كبير الحجم original-Blob1.txt، فإن قيمة المتغير name في التعليمة البرمجية للوظيفة هي Blob1.txt.

تصفية على نوع الملف

يتم تشغيل المثال التالي فقط على ملفات .png:

"path": "samples/{name}.png",

تصفية على الأقواس المتعرجة في أسماء الملفات

للبحث عن الأقواس المتعرجة في أسماء الملفات، تخلص الأقواس باستخدام قوسين. يقوم المثال التالي بتصفية الكائنات الثنائية كبيرة الحجم التي تحتوي على أقواس متعرجة في الاسم:

"path": "images/{{20140101}}-{name}",

إذا تمت تسمية كائن ثنائي كبير الحجم بالاسم {20140101}-soundfile.mp3، فإن nameقيمة المتغير في التعليمة البرمجية للوظيفة هي soundfile.mp3.

الاستقصاء وزمن الانتقال

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

تحذير

تُنشأ سجلات التخزين على أساس "أفضل جهد". ليس هناك ما يضمن أن يتم تسجيل جميع الأحداث. في بعض الحالات، قد يتم فقد السجلات.

إذا كنت تحتاج إلى معالجة blob أسرع أو أكثر موثوقية، يجب أن تفكر في تبديل الاستضافة لاستخدام خطة App Service مع تمكين Always On، ما قد يؤدي إلى زيادة التكاليف. قد تفكر أيضا في استخدام مشغل آخر غير مشغل كائن ثنائي كبير الحجم للاستقصاء الكلاسيكي. لمزيد من المعلومات ومقارنة خيارات التشغيل المختلفة لحاويات تخزين الكائن الثنائي كبير الحجم، راجع المشغل على حاوية كائن ثنائي كبير الحجم.

إيصالات كائن ثنائي كبير الحجم

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

تخزن Azure Functions إيصالات الكائنات الثنائية كبيرة الحجم في حاوية باسم azure-webjobs-hosts في حساب تخزين Azure لتطبيق الوظائف الخاص بك (المعرف من خلال إعداد التطبيق AzureWebJobsStorage). يحتوي إيصال كائن ثنائي كبير الحجم على المعلومات التالية:

• الوظيفة المشغلة (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>، على سبيل المثال: MyFunctionApp.Functions.CopyBlob)
• اسم الحاوية
• نوع الكائن الثنائي كبير الحجم (BlockBlob أو PageBlob)
• اسم كائن ثنائي كبير الحجم
• ETag (معرف إصدار كائن ثنائي كبير الحجم، على سبيل المثال: 0x8D1DC6E70A277EF)

لفرض إعادة معالجة كائن ثنائي كبير الحجم، قم بحذف إيصال لكائن ثنائي كبير الحجم من الحاوية azure-webjobs-hosts يدوياً. في حين أن إعادة المعالجة قد لا تحدث على الفور، فمن المؤكد أن تحدث في وقت لاحق. لإعادة المعالجة فوراً، يمكن تحديث كائن ثنائي كبير الحجم scaninfo في azure-webjobs-hosts/blobscaninfo. سيتم مسح أي كائنات ثنائية كبيرة الحجم ضوئياً بطابع زمني تم تعديله مؤخراً بعد الخاصية LatestScan مرة أخرى.

كائنات ثنائية كبيرة الحجم غير قابلة للمعالجة

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

إذا فشلت جميع المحاولات الخمس، تضيف Azure Functions رسالة إلى قائمة انتظار التخزين المسماة webjobs-blobtrigger-poison. الحد الأقصى لعدد مرات إعادة المحاولة قابل للتكوين. يتم استخدام نفس إعداد MaxDequeueCount لمعالجة كائن ثنائي كبير الحجم غير قابل للمعالجة ومعالجة رسالة قائمة انتظار غير قابلة للمعالجة. رسالة قائمة الانتظار للكائنات الثنائية كبيرة الحجم غير القابلة للمعالجة هي عنصر JSON الذي يحتوي على الخصائص التالية:

• FunctionId (بالتنسيق<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob أو PageBlob)
• ContainerName
• BlobName
• ETag (معرف إصدار كائن ثنائي كبير الحجم، على سبيل المثال: 0x8D1DC6E70A277EF)

استخدام الذاكرة والتزامن

عند الربط بنوع إخراج لا يدعم تبخير، مثل string، أو Byte[]، يجب أن يقوم وقت التشغيل بتحميل الكائن الثنائي كبير الحجم بأكمله في الذاكرة أكثر من مرة واحدة أثناء المعالجة. يمكن أن يؤدي هذا إلى استخدام ذاكرة أعلى من المتوقع عند معالجة الكائنات الثنائية كبيرة الحجم. عندما يكون ذلك ممكنا، استخدم نوع دعم الدفق. يعتمد دعم النوع على وضع C# وإصدار الملحق. لمزيد من المعلومات، راجع أنواع الربط.

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

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

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

الملحق 5.x وما أعلى

عند استخدام الإصدار 5.0.0 من ملحق التخزين أو إصدار أحدث، يمكنك التحكم في تشغيل التزامن باستخدام maxDegreeOfParallelism الإعداد في تكوين الكائنات الثنائية كبيرة الحجم في host.json.

ما قبل الملحق 5.x

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

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

خصائص مضيف.json

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

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

• قراءة بيانات تخزين كائن ثنائي كبير الحجم عند تشغيل وظيفة
• كتابة بيانات تخزين كائن ثنائي كبير الحجم من وظيفة