با Cloud Firestore شروع کنید

این راهنمای سریع به شما نشان می‌دهد که چگونه Cloud Firestore راه‌اندازی کنید، داده‌ها را اضافه کنید، سپس از عملیات Core یا عملیات Pipeline برای جستجوی داده‌هایی که تازه در کنسول Firebase اضافه کرده‌اید استفاده کنید.

ایجاد یک پایگاه داده Cloud Firestore

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

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

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

  4. برای حالت عملیات، Firestore را در حالت بومی (Native Mode) انتخاب کنید که از عملیات Core و Pipeline پشتیبانی می‌کند.

  5. مکانی را برای پایگاه داده خود انتخاب کنید.

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

    حالت تست

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

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

    حالت تولید

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

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

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

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

محیط توسعه خود را تنظیم کنید

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

Web

  1. برای افزودن Firebase به برنامه وب خود، دستورالعمل‌ها را دنبال کنید.
  2. SDK Cloud Firestore برای پیش‌نمایش خصوصی به صورت یک بسته npm در دسترس است.

    برای نصب Firestore SDK در پروژه npm خود از دستور زیر استفاده کنید.

    npm install --save firebase@eap-firestore-pipelines
آی‌او‌اس+
  1. برای افزودن Firebase به برنامه iOS خود، دستورالعمل‌ها را دنبال کنید.
  2. Firebase SDK را از GitHub کپی کنید و شاخه pipelines را بررسی کنید. مکانی را که آن را کپی می‌کنید یادداشت کنید، زیرا در مرحله بعدی به آن نیاز خواهید داشت:
    git clone https://github.com/firebase/firebase-ios-sdk.git
    # or git clone git@github.com:firebase/firebase-ios-sdk.git
    cd firebase-ios-sdk
    
    # check out pipeline feature branch
    git fetch origin feat/pipeline/private-preview
    git checkout feat/pipeline/private-preview
  3. سپس دایرکتوری (firebase-ios-sdk) را به عنوان یک وابستگی محلی به پروژه Xcode خود اضافه کنید:
    1. از منوی فایل ، گزینه‌ی «افزودن وابستگی‌های بسته» را انتخاب کنید.
    2. روی دکمه‌ی Add Local… کلیک کنید، سپس دایرکتوری firebase-ios-sdk را که شاخه‌ی ویژگی مورد نظر شما در آن قرار دارد، پیدا کنید.
اندروید
  1. برای افزودن Firebase به برنامه اندروید خود، دستورالعمل‌ها را دنبال کنید.
  2. کیت توسعه نرم‌افزار Firebase را از گیت‌هاب کلون کنید، شاخه pipelines را بررسی کنید و آن را در maven محلی منتشر کنید:
    # Prerequisites before you start:
    # Install Java 17
    # Setup Android Development environments (having proper ANDROID_HOME, etc)
    
    git clone https://github.com/firebase/firebase-android-sdk.git
    # or git clone git@github.com:firebase/firebase-android-sdk.git
    cd firebase-android-sdk
    
    # check out pipeline feature branch
    git fetch origin feat/pipeline/private-preview
    git checkout feat/pipeline/private-preview
    
    # publish firebase SDK (without crashlytics) to maven local
    ./gradlew publishToMavenLocal -x :firebase-crashlytics:publishToMavenLocal -x :firebase-crashlytics-ndk:publishToMavenLocal
    
    # Optionally, if you want crashlytics built and published to mavel local
    # Make sure you have Android NDK 21 installed
    git submodule update --init --recursive
    ./gradlew publishToMavenLocal
  3. mavenLocal به سطح پروژه settings.gradle.kts اضافه کنید:
    dependencyResolutionManagement {
      repositories {
        mavenLocal() // Add this line
        ..
      }
    }
  4. سپس، نسخه محلی SDK را اضافه کنید:
    ...
    // Firestore 99.0.0-pipeline.preview.1 has pipelines
    implementation("com.google.firebase:firebase-firestore:99.0.0-pipeline.preview.1")
    
    // Firebase Authentication
    implementation("com.google.firebase:firebase-auth")
    ...
پایتون
  1. کیت توسعه نرم‌افزار پایتون فایراستور را کلون کنید و شاخه پیش‌نمایش خط لوله را بررسی کنید:
    git clone https://github.com/googleapis/python-firestore.git
    # or git clone git@github.com:googleapis/python-firestore.git
    cd python-firestore
    
    # check out pipeline preview branch
    git fetch origin pipeline-preview
    git checkout pipeline-preview
  2. SDK سرور محلی python-firestore را نصب کنید:
    python -m pip install -e .
  3. طبق معمول، Firebase Python Admin SDK را نصب کنید:
    pip install --user firebase-admin

مقداردهی اولیه 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 برنامه وب خود جایگزین کنید.

برای حفظ داده‌ها هنگام قطع اتصال دستگاه، به مستندات فعال‌سازی داده‌های آفلاین مراجعه کنید.

سویفت
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");
پایتون

با استفاده از Admin SDK، با پایگاه داده سازمانی خود احراز هویت کنید:

import firebase_admin
from firebase_admin import firestore

def main():
  default_app = firebase_admin.initialize_app()
  client = firestore.client(default_app, "your-new-enterprise-database")
  query = client.pipeline().database().limit(5)
  for result in query.execute():
    print(result.data())

if __name__ == "__main__":
    main()

اضافه کردن داده‌ها با استفاده از عملیات اصلی

برای بررسی عملیات اصلی (Core operations) و عملیات خط لوله (Pipeline operations) برای پرس و جو از داده‌ها، داده‌ها را با استفاده از عملیات اصلی (Core operations) به پایگاه داده خود اضافه کنید.

Cloud Firestore داده‌ها را در اسناد (Documents) ذخیره می‌کند که خود در مجموعه‌ها (Collections) ذخیره می‌شوند. 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);
});
سویفت
توجه: این محصول در 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);
            }
        });
پایتون
doc_ref = db.collection("users").document("alovelace")
doc_ref.set({"first": "Ada", "last": "Lovelace", "born": 1815})

حالا یک سند دیگر به مجموعه 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);
});
سویفت
توجه: این محصول در 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);
            }
        });
پایتون
doc_ref = db.collection("users").document("aturing")
doc_ref.set({"first": "Alan", "middle": "Mathison", "last": "Turing", "born": 1912})

خواندن داده‌ها با استفاده از عملیات اصلی

برای تأیید سریع اینکه داده‌ها را به Cloud Firestore اضافه کرده‌اید، از نمایشگر داده در کنسول Firebase استفاده کنید.

همچنین می‌توانید از متد "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()}`);
    });
});
سویفت
توجه: این محصول در 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());
                }
            }
        });
پایتون
users_ref = db.collection("users")
docs = users_ref.stream()

for doc in docs:
    print(f"{doc.id} => {doc.to_dict()}")

خواندن داده‌ها با استفاده از عملیات Pipeline

حالا می‌توانید تجربه‌ی پرس‌وجوی Pipeline را با تجربه‌ی پرس‌وجوی Core مقایسه کنید.

Web

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);
}
سویفت
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);
    }
});
پایتون
pipeline = client.pipeline().collection("users")
for result in pipeline.execute():
    print(f"{result.id} => {result.data()}")

داده‌های خود را ایمن کنید

اگر از SDK پلتفرم‌های وب، اندروید یا اپل استفاده می‌کنید، از 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;
    }
  }
}

قبل از اینکه برنامه وب، اندروید یا iOS خود را در محیط عملیاتی مستقر کنید، همچنین اقداماتی را انجام دهید تا مطمئن شوید که فقط کلاینت‌های برنامه شما می‌توانند به داده‌های Cloud Firestore شما دسترسی داشته باشند. به مستندات App Check مراجعه کنید.

اگر از یکی از SDK های سرور استفاده می‌کنید، از مدیریت هویت و دسترسی (IAM) برای ایمن‌سازی داده‌های خود در Cloud Firestore استفاده کنید.

مراحل بعدی

دانش خود را در مورد عملیات هسته و خط لوله با مباحث زیر عمیق‌تر کنید: