تنزيل كائن ثنائي كبير الحجم باستخدام .NET
توضح هذه المقالة كيفية تنزيل كائن ثنائي كبير الحجم باستخدام مكتبة عميل Azure Storage ل .NET. يمكنك تنزيل بيانات الكائن الثنائي كبير الحجم إلى وجهات مختلفة، بما في ذلك مسار ملف محلي أو دفق أو سلسلة نصية. يمكنك أيضا فتح دفق كائن ثنائي كبير الحجم والقراءة منه.
المتطلبات الأساسية
- تفترض هذه المقالة أن لديك بالفعل مشروعا تم إعداده للعمل مع مكتبة عميل Azure Blob Storage ل .NET. للتعرف على إعداد مشروعك، بما في ذلك تثبيت الحزمة وإضافة
using
التوجيهات وإنشاء كائن عميل معتمد، راجع بدء استخدام Azure Blob Storage و.NET. - يجب أن يكون لآلية التخويل أذونات لتنفيذ عملية تنزيل. لمعرفة المزيد، راجع إرشادات التخويل لعملية 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 التالية:
- Get Blob (REST API)