يوضّح لك دليل البدء السريع هذا كيفية إعداد إصدار Firestore Enterprise وإضافة البيانات، ثم استخدام عمليات 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. استخدِم مكتبات العملاء هذه لإعداد بيئات خوادم مميّزة مع إمكانية الوصول الكامل إلى قاعدة بياناتك. يمكنك الاطّلاع على مزيد من المعلومات حول هذه المكتبات في دليل البدء السريع لمكتبات برامج الخادم.
طلب إلى الذكاء الاصطناعي للحصول على مساعدة مستندة إليه
للحصول على مساعدة من الذكاء الاصطناعي، انسخ الطلب أدناه إلى وكيل الترميز بالذكاء الاصطناعي (مثل Gemini في "استوديو Android" وAntigravity وClaude Code وCodex وCursor). يمكنك تخصيص الطلب وتكراره مع الوكيل. انتقِل إلى مهارات وكلاء Firebase للحصول على معلومات مفصّلة عن التثبيت.
Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up and use Firebase for the backend of my app. Set up Firestore database in **Enterprise edition**. Help me to choose the best location for my database instance.
إنشاء قاعدة بيانات في إصدار Firestore Enterprise
إذا لم يسبق لك إنشاء مشروع على Firebase، يمكنك إنشاء مشروع من خلال وحدة تحكُّم Firebase بالنقر على إضافة مشروع، ثم اتّباع التعليمات الظاهرة على الشاشة لإنشاء مشروع على Firebase أو إضافة خدمات Firebase إلى مشروع Google Cloud حالي.
في اللوحة اليمنى، انتقِل إلى قواعد البيانات ومساحة التخزين > Firestore.
انقر على إنشاء قاعدة بيانات.
اختَر Enterprise لوضع قاعدة البيانات.
اختَر Firestore in Native Mode لوضع التشغيل الذي يتيح عمليات Core وPipeline.
اختَر موقعًا جغرافيًا لقاعدة بياناتك.
اختَر وضع بدء لجهاز Cloud Firestore Security Rules:
- الوضع التجريبي
هذه القواعد مناسبة للبدء في استخدام مكتبات برامج الأجهزة الجوّالة والويب، ولكنّها تسمح لأي شخص بقراءة بياناتك والكتابة فوقها. بعد الاختبار، احرص على مراجعة قسم تأمين بياناتك.
للبدء باستخدام حزمة تطوير البرامج (SDK) للويب أو أنظمة Apple الأساسية أو Android، اختَر وضع الاختبار.
- وضع الإنتاج
يتم رفض جميع عمليات القراءة والكتابة من عملاء الأجهزة الجوّالة والويب. سيظل بإمكان خوادم التطبيقات التي تمت مصادقتها (Python) الوصول إلى قاعدة بياناتك.
سيتم تطبيق المجموعة الأولية من Cloud Firestore Security Rules على قاعدة بيانات Cloud Firestore التلقائية. إذا أنشأت قواعد بيانات متعددة لمشروعك، يمكنك نشر Cloud Firestore Security Rules لكل قاعدة بيانات.
انقر على إنشاء.
عند تفعيل إصدار Firestore Enterprise، يتم أيضًا تفعيل واجهة برمجة التطبيقات في مدير Cloud API.
إعداد بيئة التطوير
أضِف التبعيات ومكتبات البرامج المطلوبة إلى تطبيقك.
Web
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
-
تتوفّر حزمة تطوير البرامج (SDK) لـ Cloud Firestore كحزمة npm.
يجب استيراد كل من Firebase وCloud Firestore.npm install firebase@13.0.0 --save
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
iOS+
اتّبِع التعليمات من أجل إضافة Firebase إلى تطبيق Apple.
استخدِم أداة Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.
- في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > حِزم Swift > إضافة تبعية الحزمة.
- عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (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:35.0.1")) // 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:27.0.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); } });
قراءة البيانات باستخدام عمليات Core
استخدِم عارض البيانات في وحدة تحكّم 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
يمكنك الآن مقارنة تجربة طلب البحث في Pipeline مع تجربة طلب البحث في Core.
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 وCloud Firestore Security Rules لتأمين بياناتك في Cloud Firestore.
في ما يلي بعض مجموعات القواعد الأساسية التي يمكنك استخدامها للبدء. يمكنك تعديل قواعد الأمان من وحدة تحكُّم Firebase في قواعد البيانات ومساحة التخزين > 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.
الخطوات التالية
يمكنك تعميق معرفتك بعمليات Core وPipeline من خلال المواضيع التالية:
- مزيد من المعلومات عن تنفيذ طلبات البحث باستخدام العمليات الأساسية
- مزيد من المعلومات عن الاستعلام باستخدام عمليات Pipeline
- تعرَّف على كيفية تحسين أدوات المطوّرين المستندة إلى الذكاء الاصطناعي لتنفيذ المهام بفعالية أكبر واستخدام أفضل ممارسات Cloud Firestore (مثل كتابة Cloud Firestore Security Rules) من خلال مهارات وكلاء Firebase.