مشاركة عبر

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

  • مقالة

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

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

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

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

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

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

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

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

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، راجع الموارد التالية.

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

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

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

(راجع أيضًا )