شروع به کار با نسخه Firestore Enterprise

این شروع سریع به شما نشان می‌دهد که چگونه نسخه 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

  1. اگر قبلاً این کار را نکرده‌اید، پروژه Firebase ایجاد کنید: در کنسول Firebase، روی افزودن پروژه کلیک کنید، سپس دستورالعمل‌های روی صفحه را دنبال کنید تا پروژه Firebase ایجاد کنید یا سرویس‌های Firebase را به پروژه Google Cloud موجود اضافه کنید.

  2. در پانل سمت راست، به پایگاه‌های داده و فضای ذخیره‌سازی > Firestore بروید.

  3. روی ایجاد پایگاه داده کلیک کنید.

  4. Enterprise را برای حالت پایگاه داده انتخاب کنید.

  5. Firestore در حالت بومی را برای حالت عملیات انتخاب کنید که از عملیات‌های Core و Pipeline پشتیبانی می‌کند.

  6. مکانی برای پایگاه داده‌تان انتخاب کنید.

  7. حالت شروع را برای Cloud Firestore Security Rules انتخاب کنید:

    حالت آزمایشی

    برای شروع کار با کتابخانه‌های کارخواه وب و تلفن همراه مناسب است، اما به همه اجازه می‌دهد داده‌هایتان را بخوانند و بازنویسی کنند. پس‌از آزمایش، حتماً بخش ایمن‌سازی داده‌ها را مرور کنید.

    برای شروع به کار با وب، پلاتفرم‌های Apple، یا کیت توسعه نرم‌افزار Android، حالت آزمایش را انتخاب کنید.

    حالت تولید

    همه خواندن‌ها و نوشتن‌ها را از کلاینت‌های وب و تلفن همراه رد می‌کند. سرورهای برنامه اصالت‌سنجی‌شده شما (Python) همچنان می‌توانند به پایگاه داده شما دسترسی داشته باشند.

    مجموعه اولیه Cloud Firestore Security Rules برای پایگاه داده پیش‌فرض Cloud Firestore شما اعمال خواهد شد. اگر چندین پایگاه داده برای پروژه‌تان ایجاد کنید، می‌توانید برای هر پایگاه داده Cloud Firestore Security Rules مستقر کنید.

  8. روی ایجاد کردن کلیک کنید.

وقتی Firestore Enterprise edition را فعال می‌کنید، API نیز در Cloud API Manager فعال می‌شود.

راه‌اندازی محیط توسعه نرم‌افزار

وابستگی‌های لازم و کتابخانه‌های مشتری را به برنامه‌تان اضافه کنید.

Web

  1. دستورالعمل‌ها را برای افزودن Firebase به برنامه وب دنبال کنید.
  2. کیت توسعه نرم‌افزار Cloud Firestore به‌عنوان بسته npm دردسترس است.
    npm install firebase@13.0.0 --save
    باید هم Firebase و هم Cloud Firestore را وارد کنید.
    import { initializeApp } from "firebase/app";
    import { getFirestore } from "firebase/firestore";
iOS+‎

دستورالعمل‌های افزودن Firebase به برنامه Apple را دنبال کنید.

از Swift Package Manager برای نصب و مدیریت وابستگی‌های Firebase استفاده کنید.

  1. در Xcode، درحالی‌که پروژه برنامه‌تان باز است، به File > Swift Packages > Add Package Dependency بروید.
  2. وقتی خواسته شد، مخزن کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple را اضافه کنید:
  3.   https://github.com/firebase/firebase-ios-sdk
      
  4. کتابخانه Firestore را انتخاب کنید.
  5. پس‌از اتمام، Xcode به‌طور خودکار شروع به حل و بارگیری وابستگی‌های شما در پس‌زمینه می‌کند.
Android
  1. دستورالعمل‌های افزودن Firebase به برنامه Android را دنبال کنید.
  2. بااستفاده از 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
توجه: این محصول در watchOS و App Clip دردسترس نیست.
// 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
توجه: این محصول در watchOS و App Clip دردسترس نیست.
// 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
توجه: این محصول در watchOS و App Clip دردسترس نیست.
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) آشنا شوید.