بدء استخدام إصدار Firestore Enterprise

يوضّح لك هذا الدليل السريع كيفية إعداد إصدار 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

  1. إذا لم يسبق لك ذلك، أنشئ مشروعًا على Firebase: في الـ Firebase وحدة تحكّم، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروع على Firebase أو إضافة خدمات Firebase إلى مشروع حالي Google Cloud.

  2. افتح مشروعك في وحدة تحكّم Firebase. في اللوحة اليمنى، وسِّع إنشاء، ثم انقر على قاعدة بيانات Firestore.

  3. انقر على إنشاء قاعدة بيانات.

  4. اختَر Enterprise لوضع قاعدة البيانات.

  5. اختَر Firestore في "الوضع الأصلي" لوضع العملية، الذي يتيح العمليات الأساسية وعمليات سلسلة المعالجة.

  6. اختَر موقعًا لقاعدة البيانات.

  7. اختَر وضعًا لبدء استخدام Cloud Firestore Security Rules

    وضع الاختبار

    هذا الوضع مناسب للبدء في استخدام مكتبات برامج العميل للأجهزة الجوّالة والويب، ولكنّه يسمح لأي مستخدم بقراءة بياناتك والكتابة فوقها. بعد الاختبار، احرص على مراجعة قسم تأمين بياناتك.

    للبدء في استخدام حزمة SDK للويب أو منصات Apple أو Android، اختَر وضع الاختبار.

    وضع الإنتاج

    يؤدي هذا الوضع إلى رفض جميع عمليات القراءة والكتابة من عملاء الأجهزة الجوّالة والويب. سيظل بإمكان خوادم التطبيقات التي تم التحقّق من هويتها (Python) الوصول إلى قاعدة البيانات.

    ستنطبق مجموعة قواعد أمان Cloud Firestore الأولية على قاعدة بيانات Cloud Firestore التلقائية.Cloud Firestore Security RulesCloud Firestore إذا أنشأت قواعد بيانات متعددة لمشروعك، يمكنك نشر Cloud Firestore Security Rules لكل قاعدة بيانات.

  8. انقر على إنشاء.

عند تفعيل إصدار Enterprise من Firestore، يتم أيضًا تفعيل واجهة برمجة التطبيقات في الـ Cloud API Manager.

إعداد بيئة التطوير

أضِف التبعيات ومكتبات برامج العميل المطلوبة إلى تطبيقك.

Web

  1. اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
  2. تتوفّر حزمة Cloud Firestore SDK كحزمة npm.
    npm install firebase@12.12.1 --save
    عليك استيراد كل من Firebase وCloud Firestore.
    import { initializeApp } from "firebase/app";
    import { getFirestore } from "firebase/firestore";
iOS+

اتّبِع التعليمات لإضافة Firebase إلى تطبيقك على Apple.

استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

  1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > حِزم Swift > إضافة تبعية حزمة.
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة Firebase SDK لمنصات Apple:
  3.   https://github.com/firebase/firebase-ios-sdk
      
  4. اختَر مكتبة Firestore.
  5. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.
Android
  1. اتّبِع التعليمات لإضافة Firebase إلى تطبيق Android.
  2. باستخدام قائمة مواد منصة 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
ملاحظة: لا يتوفّر هذا المنتج على 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);
            }
        });

قراءة البيانات باستخدام العمليات الأساسية

استخدِم عارض البيانات في وحدة تحكّم 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());
                }
            }
        });

قراءة البيانات باستخدام عمليات سلسلة المعالجة

يمكنك الآن مقارنة تجربة طلب البيانات باستخدام سلسلة المعالجة بتجربة طلب البيانات باستخدام العمليات الأساسية.

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.