مشاركة عبر

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

  • مقالة

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

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

إعداد بيئتك

إذا لم يكن لديك مشروع موجود، يوضح لك هذا القسم كيفية إعداد مشروع للعمل مع مكتبة عميل 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 Reader أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل للحصول على Blob (REST API).

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

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

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

تنزيل إلى مسار ملف

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

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

تنزيل إلى دفق

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

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

تنزيل إلى سلسلة

يفترض المثال التالي أن الكائن الثنائي كبير الحجم هو ملف نصي، وينزل الكائن الثنائي كبير الحجم إلى سلسلة:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

تنزيل من بث

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم عن طريق القراءة من دفق:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

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

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

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

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

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    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
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

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

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

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

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

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

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

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

الموارد

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

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

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

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

موارد مكتبة العميل

(راجع أيضًا )

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

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