بدء استخدام Cloud Storage على Android

Cloud Storage for Firebase تتيح لك تحميل المحتوى الذي ينشئه المستخدمون ومشاركته، مثل الصور والفيديوهات، ما يسمح لك بإنشاء محتوى وسائط تفاعلية متقدّمة في تطبيقاتك. يتم تخزين بياناتك في مجموعة تخزين في Google Cloud Storage، وهي حل لتخزين الكائنات على نطاق إكسا بايت يتسم بالتوفّر العالي والنسخ الاحتياطي العالمي. Cloud Storage for Firebase تتيح لك تحميل هذه الملفات بأمان مباشرةً من الأجهزة الجوّالة ومتصفّحات الويب، ما يسهّل التعامل مع الشبكات غير المستقرة.

قبل البدء

  1. تأكَّد من إكمال دليل البدء للتطبيقات المتوافقة مع Android، إذا لم يسبق لك إجراء ذلك. ويشمل ذلك ما يلي:

    • إنشاء مشروع Firebase

    • تسجيل تطبيق Android في المشروع وربط تطبيقك بمنصة Firebase من خلال إضافة تبعيات Firebase والمكوّن الإضافي لخدمات Google وملف إعداد Firebase (google-services.json) إلى تطبيقك

  2. تأكَّد من أنّ مشروع Firebase الخاص بك يستخدم خطة التسعير Blaze المَرِنة، وهو شرط بدأ تطبيقه في أكتوبر 2024 (اطّلِع على الأسئلة الشائعة). إذا كنت جديدًا على Firebase وGoogle Cloud، تحقَّق مما إذا كنت مؤهلاً للحصول على رصيد بقيمة 300 دولار أمريكي.

إنشاء مجموعة تخزين تلقائية Cloud Storage

  1. في وحدة تحكُّم Firebase، انتقِل إلى قواعد البيانات ومساحة التخزين > مساحة التخزين.

    إذا لم يكن مشروعك بعد على خطة Blaze المَرِنة للدفع حسب الاستخدام، سيُطلب منك ترقية مشروعك.

  2. انقر على البدء.

  3. اختَر موقعًا لمجموعة التخزين التلقائية.

  4. اضبط Firebase Security Rules لمجموعة التخزين التلقائية. أثناء التطوير، ننصحك بـ إعداد قواعد الوصول العلني.

  5. انقر على تم.

يمكنك الآن عرض مجموعة التخزين في وحدة تحكُّم Firebase (انتقِل إلى قواعد البيانات ومساحة التخزين > مساحة التخزين > علامة التبويب الملفات). يكون تنسيق اسم مجموعة التخزين التلقائية PROJECT_ID.firebasestorage.app.

إعداد الوصول العلني

Cloud Storage for Firebase توفّر لغة قواعد إعلانية تتيح لك تحديد كيفية تنظيم بياناتك وفهرستها ومتى يمكن قراءتها وكتابتها. يكون الوصول للقراءة والكتابة في Cloud Storage محدودًا تلقائيًا، لذا لا يمكن للمستخدمين المصادَق عليهم فقط قراءة البيانات أو كتابتها. للبدء بدون إعداد Authentication، يمكنك ضبط قواعد الوصول العلني.

يؤدي ذلك إلى إتاحة Cloud Storage لأي مستخدم، حتى لو لم يكن يستخدم تطبيقك، لذا احرص على تقييد الوصول إلى Cloud Storage مرة أخرى عند إعداد المصادقة.

إضافة حزمة Cloud Storage SDK إلى تطبيقك

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف تبعية مكتبة Cloud Storage لنظام التشغيل Android. ننصحك باستخدام الـ Firebase Android BoM للتحكّم في تحديد إصدار المكتبة. 

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.12.0"))

    // Add the dependency for the Cloud Storage library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-storage")
}

باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

(بديل)  إضافة تبعيات مكتبة Firebase بدون استخدام BoM

إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

يُرجى العِلم أنّه إذا كنت تستخدم مكتبات متعددة من Firebase في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبات، ما يضمن توافق جميع الإصدارات. 

dependencies {
    // Add the dependency for the Cloud Storage library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-storage:22.0.1")
}

إعداد Cloud Storage في تطبيقك

  1. تأكَّد من تعديل ملف إعداد Firebase (google-services.json) في قاعدة رموز تطبيقك باسم مجموعة التخزين التلقائية Cloud Storage

    1. احصل على ملف الإعداد المعدَّل..

    2. استخدِم ملف الإعداد الذي تم تنزيله لاستبدال ملف google-services.json الحالي في دليل الوحدة (على مستوى التطبيق) في تطبيقك.

      تأكَّد من أنّ لديك ملف الإعداد الأخير الذي تم تنزيله فقط في تطبيقك وأنّه لا يتم إلحاق أحرف إضافية باسم الملف، مثل (2).

    .

  2. يمكنك الوصول إلى مجموعة Cloud Storage من خلال إنشاء مثيل من FirebaseStorage:

    Kotlin 

    storage = Firebase.storage
    StorageActivity.kt
     
    // Alternatively, explicitly specify the bucket name URL.
// val storage = Firebase.storage("gs://BUCKET_NAME")

    Java 

    FirebaseStorage storage = FirebaseStorage.getInstance();
    StorageActivity.java
     
    // Alternatively, explicitly specify the bucket name URL.
// FirebaseStorage storage = FirebaseStorage.getInstance("gs://BUCKET_NAME");

أنت مستعد لبدء استخدام Cloud Storage!

ما هي الخطوة التالية؟ تعرَّف على كيفية إنشاء مرجع Cloud Storage.

عملية الإعداد المتقدّمة

هناك بعض حالات الاستخدام التي تتطلب إعدادًا إضافيًا:

  • استخدام مجموعات تخزين Cloud Storage في مناطق جغرافية متعددة
  • استخدام مجموعات تخزين في Cloud Storage فئات تخزين مختلفة
  • استخدام مجموعات تخزين Cloud Storage مع عدة مستخدمين مصادَق عليهم في التطبيق نفسه

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

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

في أيّ من حالات الاستخدام هذه، عليك استخدام مجموعات تخزين متعددة Cloud Storage.

تكون حالة الاستخدام الثالثة مفيدة إذا كنت تنشئ تطبيقًا، مثل Google Drive، يتيح للمستخدمين تسجيل الدخول باستخدام حسابات متعددة (على سبيل المثال، حساب شخصي وحساب عمل). يمكنك استخدام مثيل مخصّص من Firebase App لمصادقة كل حساب إضافي.

استخدام مجموعات تخزين متعددة في Cloud Storage

إذا أردت استخدام مجموعة تخزين في Cloud Storage غير مجموعة التخزين التلقائية الموضّحة سابقًا في هذا الدليل، أو استخدام مجموعات تخزين متعددة في Cloud Storage في تطبيق واحد، يمكنك إنشاء مثيل من FirebaseStorage يشير إلى مجموعة التخزين المخصّصة:

Kotlin 

// Get a non-default Storage bucket
val storage = Firebase.storage("gs://my-custom-bucket")
StorageActivity.kt

Java 

// Get a non-default Storage bucket
FirebaseStorage storage = FirebaseStorage.getInstance("gs://my-custom-bucket");
StorageActivity.java

العمل مع مجموعات التخزين المستورَدة

عند استيراد مجموعة تخزين حالية Cloud Storage إلى Firebase، عليك منح Firebase إمكانية الوصول إلى هذه الملفات باستخدام أداة gsutil المضمّنة في Google Cloud SDK:

gsutil -m acl ch -r -u service-PROJECT_NUMBER@gcp-sa-firebasestorage.iam.gserviceaccount.com gs://BUCKET_NAME

يمكنك العثور على رقم مشروعك كما هو موضّح في الـ مقدّمة لمشاريع Firebase.

لا يؤثر ذلك في مجموعات التخزين التي تم إنشاؤها حديثًا، لأنّ إعدادات التحكّم التلقائية في الوصول إليها تسمح لمنصة Firebase بالوصول إليها. هذا إجراء مؤقت وسيتم تنفيذه تلقائيًا في المستقبل.

استخدام تطبيق مخصّص على Firebase

إذا كنت تنشئ تطبيقًا أكثر تعقيدًا باستخدام FirebaseApp مخصّص، يمكنك إنشاء مثيل من FirebaseStorage تم إعداده باستخدام هذا التطبيق:

Kotlin 

// Get the default bucket from a custom FirebaseApp
val storage = Firebase.storage(customApp!!)

// Get a non-default bucket from a custom FirebaseApp
val customStorage = Firebase.storage(customApp, "gs://my-custom-bucket")
StorageActivity.kt

Java 

// Get the default bucket from a custom FirebaseApp
FirebaseStorage storage = FirebaseStorage.getInstance(customApp);

// Get a non-default bucket from a custom FirebaseApp
FirebaseStorage customStorage = FirebaseStorage.getInstance(customApp, "gs://my-custom-bucket");
StorageActivity.java

الخطوات التالية