این شروع سریع به شما نشان میدهد که چگونه نسخه Firestore Enterprise را راهاندازی کنید، داده اضافه کنید، سپس از عملیات Core یا عملیات Pipeline برای پرسمان دادههایی که بهتازگی در کنسول Firebase اضافه کردهاید استفاده کنید.
Cloud Firestore از کیتهای توسعه نرمافزار وب یا تلفن همراه و کتابخانههای کارخواه سرور پشتیبانی میکند:
Cloud Firestore از کیتهای توسعه نرمافزار برای Android، iOS، و وب و غیره پشتیبانی میکند. کیتهای توسعه نرمافزار وب و تلفن همراه در ترکیب با Cloud Firestore Security Rules و Firebase Authentication از معماریهای برنامه بدون سرور پشتیبانی میکنند که در آن مشتریان مستقیماً به پایگاه داده Cloud Firestore شما متصل میشوند.
Cloud Firestore از کتابخانههای کارخواه سرور برای Java، Node.js، و Python پشتیبانی میکند. از این کتابخانههای مشتری برای راهاندازی محیطهای سرور ممتاز با دسترسی کامل به پایگاه دادهتان استفاده کنید. درباره این کتابخانهها در شروع سریع برای کتابخانههای کارخواه سرور بیشتر بدانید.
پیامواره هوش مصنوعی برای کمک هوش مصنوعی
برای کمک هوش مصنوعی، پیامواره زیر را در عامل کدنویسی هوش مصنوعی خود (مانند Gemini در Android Studio، 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 در حالت بومی را برای حالت عملیات انتخاب کنید که از عملیاتهای Core و Pipeline پشتیبانی میکند.
مکانی برای پایگاه دادهتان انتخاب کنید.
حالت شروع را برای Cloud Firestore Security Rules انتخاب کنید:
- حالت آزمایشی
برای شروع کار با کتابخانههای کارخواه وب و تلفن همراه مناسب است، اما به همه اجازه میدهد دادههایتان را بخوانند و بازنویسی کنند. پساز آزمایش، حتماً بخش ایمنسازی دادهها را مرور کنید.
برای شروع به کار با وب، پلاتفرمهای Apple، یا کیت توسعه نرمافزار Android، حالت آزمایش را انتخاب کنید.
- حالت تولید
همه خواندنها و نوشتنها را از کلاینتهای وب و تلفن همراه رد میکند. سرورهای برنامه اصالتسنجیشده شما (Python) همچنان میتوانند به پایگاه داده شما دسترسی داشته باشند.
مجموعه اولیه Cloud Firestore Security Rules برای پایگاه داده پیشفرض Cloud Firestore شما اعمال خواهد شد. اگر چندین پایگاه داده برای پروژهتان ایجاد کنید، میتوانید برای هر پایگاه داده Cloud Firestore Security Rules مستقر کنید.
روی ایجاد کردن کلیک کنید.
وقتی Firestore Enterprise edition را فعال میکنید، API نیز در Cloud API Manager فعال میشود.
راهاندازی محیط توسعه نرمافزار
وابستگیهای لازم و کتابخانههای مشتری را به برنامهتان اضافه کنید.
Web
- دستورالعملها را برای افزودن Firebase به برنامه وب دنبال کنید.
-
کیت توسعه نرمافزار 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، درحالیکه پروژه برنامهتان باز است، به File > Swift Packages > Add Package Dependency بروید.
- وقتی خواسته شد، مخزن کیت توسعه نرمافزار Firebase برای پلاتفرمهای Apple را اضافه کنید:
- کتابخانه Firestore را انتخاب کنید.
- پساز اتمام، Xcode بهطور خودکار شروع به حل و بارگیری وابستگیهای شما در پسزمینه میکند.
https://github.com/firebase/firebase-ios-sdk
Android
- دستورالعملهای افزودن Firebase به برنامه Android را دنبال کنید.
- بااستفاده از
Firebase Android BoM،
وابستگی کتابخانه 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.2")) // 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.1") }
بهدنبال ماژول کتابخانه مختص Kotlin هستید؟ از نسخه اکتبر ۲۰۲۳، توسعهدهندگان 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
برای کاوش عملیات 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); } });
ایمن کردن دادهها برای کیتهای توسعه نرمافزار تلفن همراه و وب
اگر از کیت توسعه نرمافزار پلاتفرمهای وب، 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 شما دسترسی داشته باشند. سند بررسی برنامه را ببینید.
اگر از یکی از کیتهای توسعه نرمافزار سرور استفاده میکنید، از مدیریت هویت و دسترسیها (IAM) برای ایمن کردن دادههایتان در Cloud Firestore استفاده کنید.
مراحل بعدی
با موضوعات زیر، دانش خود را درباره عملیات Core و Pipeline عمیقتر کنید:
- درباره پُرسمان با عملیات اصلی بیشتر بدانید
- درباره اجرای پُرسمان با عملیات خط لوله بیشتر بدانید.
- بااستفاده از مهارتهای عامل Firebase، با نحوه بهبود ابزارهای توسعه هوش مصنوعی برای اجرای مؤثرتر تکالیف و استفاده از روالهای مطلوب Cloud Firestore (مثل نوشتن Cloud Firestore Security Rules) آشنا شوید.