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

يوضّح لك هذا التشغيل السريع كيفية إعداد إصدار Firestore Enterprise، وإضافة البيانات، ثم استخدام العمليات الأساسية أو عمليات سلسلة المعالجة للاستعلام عن البيانات التي أضفتها للتو في وحدة تحكّم Firebase.

Cloud Firestore تتوافق مع حِزم SDK للأجهزة الجوّالة أو الويب ومكتبات برامج الخادم:

  • تتوافق Cloud Firestore مع حِزم SDK لنظامَي التشغيل Android وiOS والويب والمزيد. بالإضافة إلى Cloud Firestore Security Rules وFirebase Authentication، تتيح حِزم SDK للأجهزة الجوّالة والويب بُنى تطبيقات بلا خادم تتصل فيها الأجهزة مباشرةً بقاعدة بيانات Cloud Firestore.

  • Cloud Firestore تتوافق مع مكتبات برامج الخادم للغات Java وNode.js و Python. استخدِم مكتبات برامج الخادم هذه لإعداد بيئات خادم مميزة تتمتّع بإمكانية الوصول الكامل إلى قاعدة البيانات. يمكنك الاطّلاع على مزيد من المعلومات عن هذه المكتبات في التشغيل السريع لمكتبات برامج الخادم.

إنشاء قاعدة بيانات في إصدار Firestore Enterprise

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

  2. في اللوحة اليمنى، انتقِل إلى قواعد البيانات والتخزين > Firestore.

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

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

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

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

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

    وضع الاختبار

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

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

    وضع الإنتاج

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

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

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

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

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

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

Web

  1. اتّبِع التعليمات لإضافة Firebase إلى تطبيقك على الويب.
  2. تتوفّر حزمة Cloud Firestore SDK كحزمة npm.
    npm install firebase@12.14.0 --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 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:34.14.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.3.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.

في ما يلي بعض مجموعات القواعد الأساسية التي يمكنك استخدامها للبدء. يمكنك تعديل قواعد الأمان من وحدة تحكّم 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. يُرجى الاطّلاع على مستندات App Check.

إذا كنت تستخدم إحدى حِزم SDK للخادم، استخدِم إدارة الهوية والوصول (IAM) لتأمين بياناتك في Cloud Firestore.

الخطوات التالية

تعمّق في معرفتك بالعمليات الأساسية وعمليات سلسلة المعالجة من خلال المواضيع التالية:

  • مزيد من المعلومات عن الاستعلام باستخدام العمليات الأساسية
  • مزيد من المعلومات عن الاستعلام باستخدام عمليات مسار التعلّم.
  • تعرَّف على كيفية تحسين أدوات تطوير الذكاء الاصطناعي لتنفيذ المهام بفعالية أكبر واستخدام أفضل ممارسات Cloud Firestore (مثل كتابة Cloud Firestore Security Rules) من خلال مهارات وكيل Firebase.