مقدّمة عن Admin Cloud Storage API

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

تتيح لك السمة Admin SDK أيضًا إنشاء عناوين URL قابلة للمشاركة ليتمكّن المستخدمون من تنزيل العناصر في حِزمك.

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

استخدام حزمة تلقائية

يمكنك تحديد اسم حزمة تلقائي عند إعداد Admin SDK. بعد ذلك، يمكنك استرداد مرجع مصادق لهذا الحزمة.

يجب ألا يحتوي اسم الحزمة على gs:// أو أي بادئات بروتوكول أخرى. على سبيل المثال، إذا كان عنوان URL الخاص بالحزمة المعروض في وحدة تحكّم Firebase هو gs://PROJECT_ID.firebasestorage.app، مرِّر السلسلة PROJECT_ID.firebasestorage.app إلى Admin SDK.

Node.js

const { initializeApp, cert } = require('firebase-admin/app');
const { getStorage } = require('firebase-admin/storage');

const serviceAccount = require('./path/to/serviceAccountKey.json');

initializeApp({
  credential: cert(serviceAccount),
  storageBucket: '<BUCKET_NAME>.appspot.com'
});

const bucket = getStorage().bucket();

// 'bucket' is an object defined in the @google-cloud/storage library.
// See https://googlecloudplatform.github.io/google-cloud-node/#/docs/storage/latest/storage/bucket
// for more details.

Java

FileInputStream serviceAccount = new FileInputStream("path/to/serviceAccountKey.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .setStorageBucket("<BUCKET_NAME>.appspot.com")
    .build();
FirebaseApp.initializeApp(options);

Bucket bucket = StorageClient.getInstance().bucket();

// 'bucket' is an object defined in the google-cloud-storage Java library.
// See https://cloud.google.com/java/docs/reference/google-cloud-storage/latest/com.google.cloud.storage.Bucket
// for more details.

Python

import firebase_admin
from firebase_admin import credentials
from firebase_admin import storage

cred = credentials.Certificate('path/to/serviceAccountKey.json')
firebase_admin.initialize_app(cred, {
    'storageBucket': 'PROJECT_ID.firebasestorage.app'
})

bucket = storage.bucket()

# 'bucket' is an object defined in the google-cloud-storage Python library.
# See https://googlecloudplatform.github.io/google-cloud-python/latest/storage/buckets.html
# for more details.

Go

import (
	"context"
	"log"

	firebase "firebase.google.com/go/v4"
	"firebase.google.com/go/v4/auth"
	"google.golang.org/api/option"
)

config := &firebase.Config{
	StorageBucket: "<BUCKET_NAME>.appspot.com",
}
opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
	log.Fatalln(err)
}

client, err := app.Storage(context.Background())
if err != nil {
	log.Fatalln(err)
}

bucket, err := client.DefaultBucket()
if err != nil {
	log.Fatalln(err)
}
// 'bucket' is an object defined in the cloud.google.com/go/storage package.
// See https://godoc.org/cloud.google.com/go/storage#BucketHandle
// for more details.

يمكنك استخدام مراجع الحِزم التي تعرضها حزمة تطوير البرامج (SDK) للمشرف جنبًا إلى جنب مع Google Cloud Storage مكتبات البرامج الرسمية للعملاء لتحميل المحتوى وتنزيله وتعديله في الحِزم المرتبطة بمشاريعك على Firebase. يُرجى العِلم أنّه ليس عليك إثبات ملكية المكتبات عند استخدام حزمة تطوير البرامج (SDK) للمشرف في Firebase.Google Cloud Storage تكون مراجع الحزمة التي تعرضها حزمة Admin SDK مصادقًا عليها مسبقًا باستخدام بيانات الاعتماد المستخدَمة لتهيئة تطبيق Firebase.

استخدام مجموعات مخصّصة

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

Node.js

const bucket = getStorage().bucket('my-custom-bucket');

Java

Bucket bucket = StorageClient.getInstance().bucket("my-custom-bucket");

Python

bucket = storage.bucket('my-custom-bucket')

Go

 bucket, err := client.Bucket("my-custom-bucket")

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

إذا كنت بصدد إنشاء تطبيق أكثر تعقيدًا يتفاعل مع تطبيقات Firebase متعددة، يمكنك الوصول إلى حِزم Cloud Storage المرتبطة بتطبيق Firebase معيّن على النحو التالي:

Node.js

const bucket = getStorage(customApp).bucket();

Java

Bucket bucket = StorageClient.getInstance(customApp).bucket();

Python

bucket = storage.bucket(app=custom_app)

Go

otherClient, err := otherApp.Storage(context.Background())
bucket, err := otherClient.Bucket("other-app-bucket")

الحصول على عنوان URL قابل للمشاركة للتنزيل

يمكنك استخدام Admin SDK لإنشاء عنوان URL صالح للتنزيل وغير قابل للانتهاء للملفات المخزّنة في حِزمك. يمكن لأي شخص لديه عنوان URL هذا الوصول إلى الملف بشكل دائم.

Node.js

const { getStorage, getDownloadURL } = require('firebase-admin/storage');

const fileRef = getStorage().bucket('my-bucket').file('my-file');
const downloadURL= await getDownloadURL(fileRef);

Google Cloud Storage مكتبات برامج

تعتمد حِزم Firebase Admin SDK على مكتبات عملاء Google Cloud Storage لتوفير إذن الوصول إلى Cloud Storage. إنّ مراجع الحزمة التي تعرضها حزمة تطوير البرامج (SDK) الخاصة بالمشرفين هي عناصر محدّدة في هذه المكتبات. يمكنك الرجوع إلى المستندات ومراجع واجهة برمجة التطبيقات الخاصة بمكتبات برامج Google Cloud Storage لمعرفة كيفية استخدام مراجع الحِزم التي تم إرجاعها في حالات الاستخدام، مثل تحميل الملفات وتنزيلها.