يوضّح لك هذا الدليل السريع كيفية إعداد إصدار Enterprise من Firestore وإضافة البيانات، ثم استخدام العمليات الأساسية أو عمليات سلسلة المعالجة لطلب البيانات التي أضفتها للتو في وحدة تحكّم 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 من Firestore
إذا لم يسبق لك ذلك، أنشئ مشروعًا على Firebase: في الـ Firebase وحدة تحكّم، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروع على Firebase أو إضافة خدمات Firebase إلى مشروع حالي Google Cloud.
افتح مشروعك في وحدة تحكّم Firebase. في اللوحة اليمنى، وسِّع إنشاء، ثم انقر على قاعدة بيانات Firestore.
انقر على إنشاء قاعدة بيانات.
اختَر Enterprise لوضع قاعدة البيانات.
اختَر Firestore في "الوضع الأصلي" لوضع العملية، الذي يتيح العمليات الأساسية وعمليات سلسلة المعالجة.
اختَر موقعًا لقاعدة البيانات.
اختَر وضعًا لبدء استخدام Cloud Firestore Security Rules
- وضع الاختبار
هذا الوضع مناسب للبدء في استخدام مكتبات برامج العميل للأجهزة الجوّالة والويب، ولكنّه يسمح لأي مستخدم بقراءة بياناتك والكتابة فوقها. بعد الاختبار، احرص على مراجعة قسم تأمين بياناتك.
للبدء في استخدام حزمة SDK للويب أو منصات Apple أو Android، اختَر وضع الاختبار.
- وضع الإنتاج
يؤدي هذا الوضع إلى رفض جميع عمليات القراءة والكتابة من عملاء الأجهزة الجوّالة والويب. سيظل بإمكان خوادم التطبيقات التي تم التحقّق من هويتها (Python) الوصول إلى قاعدة البيانات.
ستنطبق مجموعة قواعد أمان Cloud Firestore الأولية على قاعدة بيانات Cloud Firestore التلقائية.Cloud Firestore Security RulesCloud Firestore إذا أنشأت قواعد بيانات متعددة لمشروعك، يمكنك نشر Cloud Firestore Security Rules لكل قاعدة بيانات.
انقر على إنشاء.
عند تفعيل إصدار Enterprise من Firestore، يتم أيضًا تفعيل واجهة برمجة التطبيقات في الـ Cloud API Manager.
إعداد بيئة التطوير
أضِف التبعيات ومكتبات برامج العميل المطلوبة إلى تطبيقك.
Web
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
-
تتوفّر حزمة Cloud Firestore SDK كحزمة npm.
عليك استيراد كل من Firebase وCloud Firestore.npm install firebase@12.12.1 --save
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
iOS+
اتّبِع التعليمات لإضافة Firebase إلى تطبيقك على Apple.
استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.
- في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > حِزم Swift > إضافة تبعية حزمة.
- عندما يُطلب منك ذلك، أضِف مستودع حزمة Firebase SDK لمنصات Apple:
- اختَر مكتبة 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.12.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.2.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");
إضافة البيانات باستخدام العمليات الأساسية
لاستكشاف العمليات الأساسية وعمليات سلسلة المعالجة لطلب البيانات، أضِف بيانات إلى قاعدة البيانات باستخدام العمليات الأساسية.
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()); } } });
قراءة البيانات باستخدام عمليات سلسلة المعالجة
يمكنك الآن مقارنة تجربة طلب البيانات باستخدام سلسلة المعالجة بتجربة طلب البيانات باستخدام العمليات الأساسية.
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. يُرجى الاطّلاع على مستندات فحص التطبيقات.
إذا كنت تستخدم إحدى حِزم SDK للخادم، استخدِم إدارة الهوية والوصول (IAM) لتأمين بياناتك في Cloud Firestore.
الخطوات التالية
تعمَّق في معرفتك بالعمليات الأساسية وعمليات سلسلة المعالجة من خلال المواضيع التالية:
- مزيد من المعلومات عن طلب البيانات باستخدام العمليات الأساسية
- مزيد من المعلومات عن طلب البيانات باستخدام عمليات سلسلة المعالجة.
- تعرَّف على كيفية تحسين أدوات تطوير الذكاء الاصطناعي لتنفيذ المهام بفعالية أكبر واستخدام Cloud Firestoreأفضل الممارسات (مثل كتابة Cloud Firestore Security Rules) من خلال مهارات وكيل Firebase.