بدء استخدام Azure Blob Storage و.NET

مقالة
10/02/2024

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

إذا كنت تبحث عن البدء بمثال كامل، فشاهد التشغيل السريع: مكتبة عميل Azure Blob Storage ل .NET.

حزمة التعليمات البرمجية | المصدر للمكتبة المرجعية | لواجهة برمجة التطبيقات (NuGet) | عينات | تقديم الملاحظات

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

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

إعداد مشروعك

يرشدك هذا المقطع خلال إعداد مشروع للعمل مع مكتبة عميل تخزين Blob Azure ل .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 Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

معلومات مكتبة عميل Blob:

Azure.Storage.Blobs: يحتوي على الفئات الأساسية (كائنات العميل) التي يمكنك استخدامها للعمل على الخدمة والحاويات والكائنات الثنائية كبيرة الحجم.
Azure.Storage.Blobs.Specialized: يحتوي على فئات يمكنك استخدامها لتنفيذ عمليات خاصة بنوع كائن ثنائي كبير الحجم، مثل الكائنات الثنائية كبيرة الحجم للكتلة.
Azure.Storage.Blobs.Models: جميع فئات الأدوات المساعدة والهياكل وأنواع التعداد الأخرى.

تخويل الوصول والاتصال ب Blob Storage

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

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

يمكنك تخويل كائن BlobServiceClient باستخدام رمز تخويل Microsoft Entra المميز أو مفتاح الوصول إلى الحساب أو توقيع وصول مشترك (SAS). للحصول على الأمان الأمثل، توصي Microsoft باستخدام معرف Microsoft Entra مع الهويات المدارة لتخويل الطلبات مقابل بيانات الكائن الثنائي كبير الحجم. لمزيد من المعلومات، راجع تخويل الوصول إلى الكائنات الثنائية كبيرة الحجم باستخدام معرف Microsoft Entra.

للتخويل باستخدام معرف Microsoft Entra، ستحتاج إلى استخدام أساس أمان. يعتمد نوع أساس الأمان الذي تحتاجه على مكان تشغيل تطبيقك. استخدم هذا الجدول كدليل.

مكان تشغيل التطبيق	أساس الأمان	الإرشاد
جهاز محلي (تطوير واختبار)	كيان الخدمة	لمعرفة كيفية تسجيل التطبيق وإعداد مجموعة Microsoft Entra وتعيين الأدوار وتكوين متغيرات البيئة، راجع تخويل الوصول باستخدام أساسيات خدمة المطور
جهاز محلي (تطوير واختبار)	هوية المستخدم	لمعرفة كيفية إعداد مجموعة Microsoft Entra وتعيين الأدوار وتسجيل الدخول إلى Azure، راجع تخويل الوصول باستخدام بيانات اعتماد المطور
مستضاف في Azure	الهوية المُدارة	لمعرفة كيفية تمكين الهوية المدارة وتعيين الأدوار، راجع تخويل الوصول من التطبيقات المستضافة من Azure باستخدام هوية مدارة
مستضاف خارج Azure (على سبيل المثال، التطبيقات المحلية)	كيان الخدمة	لمعرفة كيفية تسجيل التطبيق وتعيين الأدوار وتكوين متغيرات البيئة، راجع تخويل الوصول من التطبيقات المحلية باستخدام كيان خدمة التطبيق

تخويل الوصول باستخدام DefaultAzureCredential

طريقة سهلة وآمنة لتخويل الوصول والاتصال ب Blob Storage هي الحصول على رمز OAuth المميز عن طريق إنشاء مثيل DefaultAzureCredential . يمكنك بعد ذلك استخدام بيانات الاعتماد هذه لإنشاء كائن BlobServiceClient .

ينشئ المثال التالي كائنا معتمدا BlobServiceClient باستخدام DefaultAzureCredential:

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

    return client;
}

إذا كنت تعرف بالضبط نوع بيانات الاعتماد الذي ستستخدمه لمصادقة المستخدمين، يمكنك الحصول على رمز OAuth المميز باستخدام فئات أخرى في مكتبة عميل Azure Identity ل .NET. هذه الفئات مشتقة من فئة TokenCredential .

قم بإنشاء Uri باستخدام نقطة نهاية خدمة كائن ثنائي كبير الحجم ورمز SAS. ثم قم بإنشاء BlobServiceClient باستخدام عنوان Uri.

public static void GetBlobServiceClientSAS(ref BlobServiceClient blobServiceClient,
    string accountName, string sasToken)
{
    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
    (new Uri($"{blobUri}?{sasToken}"), null);
}

لمعرفة المزيد حول إنشاء رموز SAS المميزة وإدارتها، راجع المقالات التالية:

إشعار

بالنسبة للسيناريوهات التي يتم فيها استخدام توقيعات الوصول المشترك (SAS)، توصي Microsoft باستخدام SAS لتفويض المستخدم. يتم تأمين SAS لتفويض المستخدم باستخدام بيانات اعتماد Microsoft Entra بدلا من مفتاح الحساب.

إنشاء StorageSharedKeyCredential باستخدام اسم حساب التخزين ومفتاح الحساب. ثم استخدم هذا الكائن لتهيئة BlobServiceClient.

public static void GetBlobServiceClient(ref BlobServiceClient blobServiceClient,
    string accountName, string accountKey)
{
    Azure.Storage.StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
        (new Uri(blobUri), sharedKeyCredential);
}

يمكنك أيضًا إنشاء BlobServiceClient باستخدام سلسلة اتصال.

BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

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

هام

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

لمعرفة المزيد حول كل آلية من آليات التخويل هذه، راجع تفويض الوصول إلى البيانات في Azure Storage.

بناء تطبيقك

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

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

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

مشاركة عبر