تحميل كائن ثنائي كبير الحجم باستخدام .NET

• NET.
• Java
• JavaScript
• Python
• ذهب

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

المتطلبات الأساسية

• اشتراك Azure - إنشاء اشتراك مجاني
• حساب تخزين Azure - إنشاء حساب تخزين
• أحدث .NET SDK لنظام التشغيل الخاص بك. تأكد من الحصول على SDK وليس وقت التشغيل.

إعداد بيئتك

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

تثبيت الحزم

من دليل المشروع الخاص بك، قم بتثبيت حزم Azure Blob Storage ومكتبات عميل Azure Identity باستخدام dotnet add package الأمر . حزمة Azure.Identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

أضف توجيهات using

أضف هذه using التوجيهات إلى أعلى ملف التعليمات البرمجية:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

قد تتطلب بعض أمثلة التعليمات البرمجية في هذه المقالة توجيهات إضافية using .

إنشاء كائن عميل

لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل BlobServiceClient. يوضح المثال التالي كيفية إنشاء كائن عميل باستخدام DefaultAzureCredential للتخويل:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

يمكنك تسجيل عميل خدمة لإدخال التبعية في تطبيق .NET.

يمكنك أيضا إنشاء كائنات العميل لحاويات أو كائنات ثنائية كبيرة الحجم معينة. لمعرفة المزيد حول إنشاء كائنات العميل وإدارتها، راجع إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها.

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لتحميل كائن ثنائي كبير الحجم. للحصول على تخويل باستخدام معرف Microsoft Entra (مستحسن)، تحتاج إلى دور Azure RBAC المضمن في Storage Blob Data Contributor أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل ل Put Blob (REST API) و Put Block (REST API).

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

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

• رفع
• رفع تزامن

عند استخدام أساليب التحميل هذه، قد تستدعي مكتبة العميل إما Put Blob أو سلسلة من استدعاءات Put Block متبوعة ب Put Block List. يعتمد هذا السلوك على الحجم الإجمالي للكائن وكيفية تعيين خيارات نقل البيانات.

لفتح دفق في Blob Storage والكتابة إلى هذا الدفق، استخدم أي من الطرق التالية:

• OpenWrite
• OpenWriteAsync

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

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

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

تحميل كائن ثنائي كبير الحجم للكتلة من دفق

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة عن طريق إنشاء كائن Stream وتحميل الدفق.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

تحميل كائن ثنائي كبير الحجم للكتلة من كائن BinaryData

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة من كائن BinaryData .

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

تحميل كائن ثنائي كبير الحجم للكتلة من سلسلة

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة من سلسلة:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

تحميل إلى دفق في مخزن البيانات الثنائية الكبيرة

يمكنك فتح دفق في Blob Storage والكتابة إليه. ينشئ المثال التالي ملف مضغوط في Blob Storage ويكتب الملفات إليه. بدلاً من إنشاء ملف مضغوط في الذاكرة المحلية، يوجد ملف واحد فقط في كل مرة في الذاكرة.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

تحميل كائن ثنائي كبير الحجم للكتلة مع خيارات التكوين

يمكنك تحديد خيارات تكوين مكتبة العميل عند تحميل كائن ثنائي كبير الحجم. يمكن ضبط هذه الخيارات لتحسين الأداء وتحسين الموثوقية وتحسين التكاليف. توضح أمثلة التعليمات البرمجية التالية كيفية استخدام BlobUploadOptions لتحديد خيارات التكوين عند استدعاء أسلوب تحميل.

تحديد خيارات نقل البيانات عند التحميل

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

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

لمعرفة المزيد حول خيارات ضبط نقل البيانات، راجع ضبط الأداء للتحميلات والتنزيلات باستخدام .NET.

تحديد خيارات التحقق من صحة النقل عند التحميل

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

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

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

يعرض الجدول التالي الخيارات المتوفرة لخوارزمية المجموع الاختباري، كما هو محدد بواسطة StorageChecksumAlgorithm:

الاسم	قيمة	‏‏الوصف
تلقائي	0	الطريقة المستحسنة. يسمح للمكتبة باختيار خوارزمية. قد تختار إصدارات المكتبة المختلفة خوارزميات مختلفة.
بلا	1	لا توجد خوارزمية محددة. لا تحسب أو تطلب المجموع الاختباري.
MD5	2	خوارزمية تجزئة MD5 القياسية.
StorageCrc64	3	Azure Storage مخصص 64 بت CRC.

إشعار

إذا لم يتطابق المجموع الاختباري المحدد في الطلب مع المجموع الاختباري المحسوب بواسطة الخدمة، تفشل عملية التحميل. لا تتم إعادة محاولة العملية عند استخدام نهج إعادة المحاولة الافتراضي. في .NET، RequestFailedException يتم طرح مع رمز الحالة 400 ورمز Md5Mismatch الخطأ أو Crc64Mismatch، اعتمادا على الخوارزمية التي يتم استخدامها.

تحميل بعلامات الفهرس

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

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة مع علامات الفهرس:

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

تعيين طبقة وصول كائن ثنائي كبير الحجم عند التحميل

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

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

يسمح بتعيين طبقة الوصول فقط لكتل الكائنات الثنائية كبيرة الحجم. يمكنك تعيين طبقة الوصول لكتلة كائن ثنائي كبير الحجم إلى Hotأو CoolColdأو أو Archive. لتعيين مستوى الوصول إلى Cold، يجب استخدام الحد الأدنى لإصدار مكتبة العميل من 12.15.0.

لمعرفة المزيد حول مستويات الوصول، راجع نظرة عامة على مستويات الوصول.

تحميل كائن ثنائي كبير الحجم للكتلة عن طريق التقسيم المرحلي والتزم

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

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

الموارد

لمعرفة المزيد حول تحميل الكائنات الثنائية كبيرة الحجم باستخدام مكتبة عميل Azure Blob Storage ل .NET، راجع الموارد التالية.

نماذج التعليمات البرمجية

• عرض نماذج التعليمات البرمجية من هذه المقالة (GitHub)

عمليات واجهة برمجة تطبيقات REST

يحتوي Azure SDK ل .NET على مكتبات تستند إلى واجهة برمجة تطبيقات AZURE REST، مما يسمح لك بالتفاعل مع عمليات REST API من خلال نماذج .NET المألوفة. تستخدم أساليب مكتبة العميل لتحميل الكائنات الثنائية كبيرة الحجم عمليات واجهة برمجة تطبيقات REST التالية:

• وضع كائن ثنائي كبير الحجم (واجهة برمجة تطبيقات REST)
• وضع كتلة (واجهة برمجة تطبيقات REST)

(راجع أيضًا )

• ضبط الأداء للتحميلات والتنزيلات.
• إدارة بيانات Azure Blob والعثور عليها باستخدام علامات فهرس كائن ثنائي كبير الحجم
• استخدام علامات فهرسة الكائنات الثنائية كبيرة الحجم لإدارة البيانات والعثور عليها في مساحة تخزين Azure Blob

المحتوى ذو الصلة

• هذه المقالة هي جزء من دليل مطور Blob Storage ل .NET. لمعرفة المزيد، راجع القائمة الكاملة لمقالات دليل المطور في إنشاء تطبيق .NET الخاص بك.