يوضّح لك هذا الدليل السريع كيفية إعداد إصدار Enterprise من Cloud Firestore، ثم إضافة البيانات، ثم استخدام عمليات Core أو عمليات Pipeline للاستعلام عن البيانات التي أضفتها للتو في وحدة تحكّم Firebase.
تتوافق Cloud Firestore مع حِزم تطوير البرامج (SDK) للأجهزة الجوّالة أو الويب ومكتبات برامج الخادم والعميل:
يتوافق Cloud Firestore مع حِزم تطوير البرامج (SDK) لنظام التشغيل Android وiOS والويب وغير ذلك. بالإضافة إلى Cloud Firestore Security Rules وFirebase Authentication، تتيح حِزم تطوير البرامج (SDK) للويب والأجهزة الجوّالة بنية تطبيقات بدون خادم، حيث تتصل البرامج مباشرةً بقاعدة بيانات Cloud Firestore.
تتيح Cloud Firestore استخدام مكتبات برامج الخادم للغات Java وNode.js وPython. استخدِم مكتبات البرامج هذه لإعداد بيئات خادم ذات امتيازات خاصة تتيح الوصول الكامل إلى قاعدة البيانات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه المكتبات في دليل البدء السريع لمكتبات برامج الخادم.
إنشاء قاعدة بيانات إصدار Enterprise من Cloud Firestore
إذا لم يسبق لك إنشاء مشروع على Firebase، يمكنك إنشاء مشروع باتّباع الخطوات التالية: في Firebaseوحدة التحكّم، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروع على Firebase أو لإضافة خدمات Firebase إلى مشروع Google Cloud حالي.
افتح مشروعك في وحدة تحكّم Firebase. في اللوحة اليمنى، وسِّع إنشاء، ثم اختَر قاعدة بيانات Firestore.
انقر على إنشاء قاعدة بيانات.
اختَر المؤسسة لوضع قاعدة البيانات.
اختَر Firestore في الوضع الأصلي لوضع التشغيل الذي يتيح عمليات Core وPipeline.
اختَر موقعًا جغرافيًا لقاعدة البيانات.
اختَر وضعًا لبدء Cloud Firestore Security Rules:
- وضع الاختبار
هذه الطريقة مناسبة للبدء باستخدام مكتبات البرامج للعملاء على الأجهزة الجوّالة والويب، ولكنّها تتيح لأي مستخدم قراءة بياناتك واستبدالها. بعد إجراء الاختبار، احرص على مراجعة قسم تأمين بياناتك.
لبدء استخدام حزمة تطوير البرامج (SDK) على الويب أو على منصات Apple أو Android، اختَر وضع الاختبار.
- وضع الإنتاج
يتم رفض جميع عمليات القراءة والكتابة من تطبيقات الأجهزة الجوّالة وعملاء الويب. ستظل خوادم التطبيقات التي تم إثبات ملكيتها (Python) قادرة على الوصول إلى قاعدة البيانات.
سيتم تطبيق مجموعة Cloud Firestore Security Rules الأولية على قاعدة بيانات Cloud Firestore التلقائية. إذا أنشأت قواعد بيانات متعددة لمشروعك، يمكنك نشر Cloud Firestore Security Rules لكل قاعدة بيانات.
انقر على إنشاء.
عند تفعيل إصدار Cloud Firestore Enterprise، يتم أيضًا تفعيل واجهة برمجة التطبيقات في Cloud API Manager.
إعداد بيئة التطوير
أضِف التبعيات ومكتبات البرامج المطلوبة إلى تطبيقك.
Web
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
-
تتوفّر حزمة تطوير البرامج (SDK) Cloud Firestore كحزمة npm.
يجب استيراد كلّ من Firebase وCloud Firestore.npm install firebase@12.9.0 --save
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
iOS+
اتّبِع التعليمات لإضافة Firebase إلى تطبيق Apple.
استخدِم Swift Package Manager لتثبيت ملحقات Firebase وإدارتها.
- في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف (File) > حِزم Swift (Swift Packages) > إضافة موارد الاعتمادية للحزمة (Add Package Dependency).
- عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple على Firebase:
- اختَر مكتبة Firestore.
- بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.
https://github.com/firebase/firebase-ios-sdk
Android
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق Android.
- باستخدام حزمة إدارة مواد Firebase لنظام التشغيل Android، حدِّد الاعتمادية لمكتبة Cloud Firestore لنظام التشغيل Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً
app/build.gradle.ktsأوapp/build.gradle).dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:34.8.0")) // Declare the dependency for the Cloud Firestore library // When using the BoM, you don't specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore") }
باستخدام قائمة مواد Firebase لنظام التشغيل Android، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.
(بديل) عليك تحديد تبعيات مكتبة Firebase بدون استخدام BoM
إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية.
يُرجى العِلم أنّه في حال استخدام عدّة مكتبات Firebase في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبات، ما يضمن توافق جميع الإصدارات.
dependencies { // Declare the dependency for the Cloud Firestore library // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore:26.1.0") }
هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ بدءًا من إصدار تشرين الأول (أكتوبر) 2023، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للحصول على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).
إعداد Cloud Firestore
إعداد مثيل من Cloud Firestore:
Web
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore"; // TODO: Replace the following with your app's Firebase project configuration // See: https://support.google.com/firebase/answer/7015592 const firebaseConfig = { FIREBASE_CONFIGURATION }; // Initialize Firebase const app = initializeApp(firebaseConfig); // When initializing Firestore, remember to use the name of the database you created earlier: const db = initializeFirestore(app, {}, 'your-new-enterprise-database');
استبدِل FIREBASE_CONFIGURATION بـ
firebaseConfig لتطبيق الويب.
للاحتفاظ بالبيانات عندما يفقد الجهاز اتصاله، اطّلِع على مستندات تفعيل البيانات بلا إنترنت.
Swift
import FirebaseCore import FirebaseFirestore FirebaseApp.configure() // When initializing Firestore, remember to use the name of the database you created earlier: let db = Firestore.firestore(database: "your-new-enterprise-database")
Kotlin
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: val firestore = FirebaseFirestore.getInstance("your-new-enterprise-database")
Java
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: FirebaseFirestore firestore = FirebaseFirestore.getInstance("your-new-enterprise-database");
إضافة البيانات باستخدام العمليات الأساسية
لاستكشاف عمليات Core وعمليات Pipeline للاستعلام عن البيانات، أضِف بيانات إلى قاعدة البيانات باستخدام عمليات Core.
تخزّن Cloud Firestore البيانات في مستندات، ويتم تخزين هذه المستندات في مجموعات. تنشئ Cloud Firestore المجموعات والمستندات ضمنيًا في المرة الأولى التي تضيف فيها بيانات إلى المستند. ليس عليك إنشاء مجموعات أو مستندات بشكل صريح.
أنشئ مجموعة ومستندًا جديدَين باستخدام نموذج الرمز التالي.
Web
import { collection, addDoc } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Ada", last: "Lovelace", born: 1815 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
db.collection("users").add({ first: "Ada", last: "Lovelace", born: 1815 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Swift
// Add a new document with a generated ID do { let ref = try await db.collection("users").addDocument(data: [ "first": "Ada", "last": "Lovelace", "born": 1815 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Kotlin
// Create a new user with a first and last name val user = hashMapOf( "first" to "Ada", "last" to "Lovelace", "born" to 1815, ) // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Java
// Create a new user with a first and last name Map<String, Object> user = new HashMap<>(); user.put("first", "Ada"); user.put("last", "Lovelace"); user.put("born", 1815); // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
الآن أضِف مستندًا آخر إلى المجموعة users. لاحظ أنّ هذا المستند يتضمّن زوجًا من المفتاح والقيمة (الاسم الأوسط) لا يظهر في المستند الأول. يمكن أن تحتوي المستندات في مجموعة على مجموعات مختلفة من المعلومات.
Web
// Add a second document with a generated ID. import { addDoc, collection } from "firebase/firestore"; try { const docRef = await addDoc(collection(db, "users"), { first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }); console.log("Document written with ID: ", docRef.id); } catch (e) { console.error("Error adding document: ", e); }
Web
// Add a second document with a generated ID. db.collection("users").add({ first: "Alan", middle: "Mathison", last: "Turing", born: 1912 }) .then((docRef) => { console.log("Document written with ID: ", docRef.id); }) .catch((error) => { console.error("Error adding document: ", error); });
Swift
// Add a second document with a generated ID. do { let ref = try await db.collection("users").addDocument(data: [ "first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912 ]) print("Document added with ID: \(ref.documentID)") } catch { print("Error adding document: \(error)") }
Kotlin
// Create a new user with a first, middle, and last name val user = hashMapOf( "first" to "Alan", "middle" to "Mathison", "last" to "Turing", "born" to 1912, ) // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener { documentReference -> Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}") } .addOnFailureListener { e -> Log.w(TAG, "Error adding document", e) }
Java
// Create a new user with a first, middle, and last name Map<String, Object> user = new HashMap<>(); user.put("first", "Alan"); user.put("middle", "Mathison"); user.put("last", "Turing"); user.put("born", 1912); // Add a new document with a generated ID db.collection("users") .add(user) .addOnSuccessListener(new OnSuccessListener<DocumentReference>() { @Override public void onSuccess(DocumentReference documentReference) { Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId()); } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "Error adding document", e); } });
قراءة البيانات باستخدام العمليات الأساسية
استخدِم أداة عرض البيانات في وحدة تحكّم Firebase للتأكّد بسرعة من أنّك أضفت بيانات إلى Cloud Firestore.
يمكنك أيضًا استخدام طريقة "get" لاسترداد المجموعة بأكملها.
Web
import { collection, getDocs } from "firebase/firestore"; const querySnapshot = await getDocs(collection(db, "users")); querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); });
Web
db.collection("users").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); }); });
Swift
do { let snapshot = try await db.collection("users").getDocuments() for document in snapshot.documents { print("\(document.documentID) => \(document.data())") } } catch { print("Error getting documents: \(error)") }
Kotlin
db.collection("users") .get() .addOnSuccessListener { result -> for (document in result) { Log.d(TAG, "${document.id} => ${document.data}") } } .addOnFailureListener { exception -> Log.w(TAG, "Error getting documents.", exception) }
Java
db.collection("users") .get() .addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() { @Override public void onComplete(@NonNull Task<QuerySnapshot> task) { if (task.isSuccessful()) { for (QueryDocumentSnapshot document : task.getResult()) { Log.d(TAG, document.getId() + " => " + document.getData()); } } else { Log.w(TAG, "Error getting documents.", task.getException()); } } });
قراءة البيانات باستخدام عمليات Pipeline
يمكنك الآن مقارنة تجربة طلب البحث في "المسار" بتجربة طلب البحث في "الوضع الأساسي".
Web
// The import/require of "firebase/firestore/pipelines" has a side-effect // of extending the Firestore class with the `.pipeline()` method. // Without this import/require, you will not be able to create a Pipeline. // import { execute } from "firebase/firestore/pipelines"; const readDataPipeline = db.pipeline() .collection("users"); // Execute the pipeline and handle the result try { const querySnapshot = await execute(readDataPipeline); querySnapshot.results.forEach((result) => { console.log(`${result.id} => ${result.data()}`); }); } catch (error) { console.error("Error getting documents: ", error); }
Swift
do { // Initialize a Firestore Pipeline instance and specify the "users" collection as the // input stage. let snapshot = try await db.pipeline() .collection("users") .execute() // Execute the pipeline to retrieve documents. // Iterate through the documents in the pipeline results, similar to a regular query // snapshot. for result in snapshot.results { print("\(result.id ?? "no ID") => \(result.data)") } } catch { print("Error getting documents with pipeline: \(error)") }
Kotlin
val readDataPipeline = db.pipeline() .collection("users") // Execute the pipeline and handle the result readDataPipeline.execute() .addOnSuccessListener { result -> for (document in result) { println("${document.getId()} => ${document.getData()}") } } .addOnFailureListener { exception -> println("Error getting documents: $exception") }
Java
Pipeline readDataPipeline = db.pipeline() .collection("users"); readDataPipeline.execute() .addOnSuccessListener(new OnSuccessListener<Pipeline.Snapshot>() { @Override public void onSuccess(Pipeline.Snapshot snapshot) { for (PipelineResult result : snapshot.getResults()) { System.out.println(result.getId() + " => " + result.getData()); } } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { System.out.println("Error getting documents: " + e); } });
تأمين بياناتك لحِزم تطوير البرامج (SDK) على الأجهزة الجوّالة والويب
إذا كنت تستخدم حزمة تطوير البرامج (SDK) لمنصات الويب أو Android أو Apple، استخدِم Firebase Authentication و Cloud Firestore Security Rules لتأمين بياناتك في Cloud Firestore.
في ما يلي بعض مجموعات القواعد الأساسية التي يمكنك استخدامها للبدء. يمكنك تعديل قواعد الأمان في علامة التبويب القواعد في وحدة التحكّم.
يجب إكمال عملية المصادقة
// Allow read/write access to a document keyed by the user's UID
service cloud.firestore {
match /databases/{database}/documents {
match /users/{uid} {
allow read, write: if request.auth != null && request.auth.uid == uid;
}
}
}
وضع الإنتاج
// Deny read/write access to all users under any conditions
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
قبل نشر تطبيق الويب أو تطبيق Android أو iOS في مرحلة الإنتاج، اتّخِذ أيضًا خطوات لضمان أنّ عملاء تطبيقك فقط يمكنهم الوصول إلى بيانات Cloud Firestore. راجِع مستندات App Check.
إذا كنت تستخدم إحدى حِزم تطوير البرامج (SDK) الخاصة بالخادم، استخدِم إدارة الهوية والوصول (IAM) لتأمين بياناتك في Cloud Firestore.
الخطوات التالية
يمكنك تعميق معرفتك بعمليات Core وPipeline من خلال المواضيع التالية:
- مزيد من المعلومات عن تنفيذ طلبات البحث باستخدام العمليات الأساسية
- مزيد من المعلومات عن الاستعلام باستخدام عمليات Pipeline