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

مقالة
01/19/2024

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

API reference | Package (Maven) | Library source code | Samples | Give feedback

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

اشتراك Azure - إنشاء اشتراك مجاني
حساب تخزين Azure - إنشاء حساب تخزين
الإصدار 8 أو أحدث من Java Development Kit (JDK)
يتم استخدام Apache Maven لإدارة المشاريع في هذا المثال

إعداد مشروعك

إشعار

تستخدم هذه المقالة أداة بناء Maven لإنشاء وتشغيل نموذج التعليمات البرمجية. تعمل أدوات البناء الأخرى، مثل Gradle، أيضا مع Azure SDK ل Java.

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

تثبيت الحزم

افتح الملف pom.xml في محرر النصوص الخاص بك. قم بتثبيت الحزم عن طريق تضمين ملف BOM، أو تضمين تبعية مباشرة.

تضمين ملف BOM

أضف azure-sdk-bom للحصول على تبعية على أحدث إصدار من المكتبة. في القصاصة البرمجية التالية، استبدل {bom_version_to_target} العنصر النائب برقم الإصدار. استخدام azure-sdk-bom يمنعك من الاضطرار إلى تحديد إصدار كل تبعية فردية. لمعرفة المزيد حول قائمة مكونات الصنف، راجع README ل Azure SDK BOM.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

أضف عناصر التبعية التالية إلى مجموعة التبعيات. تبعية azure-identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

تضمين تبعية مباشرة

للحصول على تبعية على إصدار معين من المكتبة، أضف التبعية المباشرة إلى مشروعك:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

تضمين توجيهات الاستيراد

ثم افتح ملف التعليمات البرمجية وأضف التوجيهات الضرورية import . في هذا المثال، نضيف التوجيهات التالية في ملف App.java :

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

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

com.azure.storage.blob: يحتوي على الفئات الأساسية (كائنات العميل) التي يمكنك استخدامها للعمل على الخدمة والحاويات والكائنات الثنائية كبيرة الحجم.
com.azure.storage.blob.models: يحتوي على فئات الأدوات المساعدة والبنيات وأنواع التعداد.
com.azure.storage.blob.specialized: يحتوي على فئات يمكنك استخدامها لتنفيذ عمليات خاصة بنوع كائن ثنائي كبير الحجم (على سبيل المثال: إلحاق الكائنات الثنائية كبيرة الحجم).

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

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

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

يمكنك تخويل كائن 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 .

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

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

public static BlobServiceClient GetBlobServiceClientTokenCredential() {
    TokenCredential credential = new DefaultAzureCredentialBuilder().build();

    // Azure SDK client builders accept the credential as a parameter
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .credential(credential)
            .buildClient();

    return blobServiceClient;
}

استخدم BlobServiceClientBuilder لإنشاء كائن BlobServiceClient باستخدام رمز SAS المميز:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

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

إشعار

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

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

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

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

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // Azure SDK client builders accept the credential as a parameter
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

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

هام

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

إنشاء التطبيق الخاص بك

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

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

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

مشاركة عبر