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

يوضّح لك دليل البدء السريع هذا كيفية إعداد Cloud Firestore وإضافة البيانات، ثم عرض البيانات التي أضفتها للتو في وحدة تحكُّم Firebase.

يتيح Cloud Firestore استخدام حِزم تطوير البرامج (SDK) للأجهزة الجوّالة أو الويب ومكتبات برامج الخادم:

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

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

للحصول على مساعدة من الذكاء الاصطناعي، انسخ الطلب أدناه إلى وكيل الترميز بالذكاء الاصطناعي (مثل Gemini في "استوديو Android" و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 **Standard edition**. Help me to choose the best location for my database instance.

إنشاء قاعدة بيانات Cloud Firestore

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

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

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

  4. اختَر موقعًا جغرافيًا لقاعدة بياناتك.

    إذا لم تتمكّن من اختيار موقع جغرافي، يعني ذلك أنّه سبق أن تم ضبط "الموقع الجغرافي لموارد Google Cloud التلقائية" لمشروعك. تعتمد بعض موارد مشروعك (مثل مثيل Cloud Firestore التلقائي) على موقع جغرافي مشترك، ويمكن ضبط موقعها الجغرافي إما أثناء إنشاء المشروع أو عند إعداد خدمة أخرى تعتمد على هذا الموقع الجغرافي.

  5. اختَر وضع بدء لجهاز Cloud Firestore Security Rules:

    الوضع التجريبي

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

    للبدء باستخدام الويب أو منصات Apple أو حزمة تطوير البرامج (SDK) لنظام التشغيل Android، اختَر وضع الاختبار.

    وضع الإنتاج

    يتم رفض جميع عمليات القراءة والكتابة من عملاء الأجهزة الجوّالة والويب. سيظل بإمكان خوادم التطبيقات التي تمت مصادقتها (C#‎ أو Go أو Java أو Node.js أو PHP أو Python أو Ruby) الوصول إلى قاعدة بياناتك.

    لبدء استخدام مكتبة برامج الخادم بلغة C#‎ أو Go أو Java أو Node.js أو PHP أو Python أو Ruby، اختَر وضع الإنتاج.

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

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

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

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

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

Web

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

Web

  1. اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
  2. أضِف مكتبات Firebase وCloud Firestore إلى تطبيقك:
    <script src="https://www.gstatic.com/firebasejs/13.0.0/firebase-app-compat.js"></script>
    <script src="https://www.gstatic.com/firebasejs/13.0.0/firebase-firestore-compat.js"></script>
    تتوفّر حزمة تطوير البرامج (SDK) لـ Cloud Firestore أيضًا كحزمة npm.
    npm install firebase@13.0.0 --save
    يجب طلب كل من Firebase وCloud Firestore يدويًا.
    import firebase from "firebase/compat/app";
    // Required for side-effects
    import "firebase/firestore";
iOS+‎

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

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

  1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > حِزم Swift > إضافة تبعية الحزمة.
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple في Firebase:
  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:35.0.1"))
    
        // 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.0")
    }

    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ بدءًا من إصدار أكتوبر 2023، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمعرفة التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).

Dart

  1. اضبط إعدادات Firebase وابدأ استخدامه في تطبيق Flutter، إذا لم يسبق لك إجراء ذلك.
  2. من جذر مشروع Flutter، نفِّذ الأمر التالي لتثبيت المكوّن الإضافي:
    flutter pub add cloud_firestore
  3. بعد الانتهاء، أعِد إنشاء تطبيق Flutter:
    flutter run
  4. اختياري: يمكنك تحسين أوقات إنشاء إصدارات iOS وmacOS من خلال تضمين إطار العمل المُجمَّع مسبقًا.

    تعتمد حزمة تطوير البرامج (SDK) لخدمة Firestore لنظام التشغيل iOS حاليًا على رمز يمكن أن يستغرق أكثر من 5 دقائق لإنشائه في Xcode. لتقليل أوقات الإنشاء بشكل كبير، يمكنك استخدام نسخة تم تجميعها مسبقًا من خلال إضافة هذا السطر إلى مجموعة target 'Runner' do في Podfile:

    target 'Runner' do
      use_frameworks!
      use_modular_headers!
    
      pod 'FirebaseFirestore',
        :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
        :tag => 'IOS_SDK_VERSION'
    
      flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
      target 'RunnerTests' do
        inherit! :search_paths
      end
    end

    استبدِل IOS_SDK_VERSION بإصدار حزمة تطوير البرامج (SDK) لمنصة Firebase على أجهزة iOS المحدّد في ملف firebase_sdk_version.rb الخاص بـ firebase_core. إذا لم تكن تستخدم أحدث إصدار من firebase_core، ابحث عن هذا الملف في ذاكرة التخزين المؤقت لحزمة Pub المحلية (عادةً ~/.pub-cache).

    بالإضافة إلى ذلك، تأكّد من ترقية CocoaPods إلى الإصدار 1.9.1 أو إصدار أحدث:

    gem install cocoapods

    لمزيد من المعلومات، يُرجى الاطّلاع على المشكلة على GitHub.

C++‎
  1. اتّبِع التعليمات من أجل إضافة Firebase إلى مشروع C++‎.
  2. واجهة C++‎ لنظام التشغيل Android
    • تبعيات Gradle: أضِف ما يلي إلى ملف Gradle للوحدة (على مستوى التطبيق)، وعادةً يكون app/build.gradle:
              android.defaultConfig.externalNativeBuild.cmake {
                arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
              }
      
              apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
              firebaseCpp.dependencies {
                // earlier entries
                auth
                firestore
              }
              
    • التبعيات الثنائية: وبالمثل، فإنّ الطريقة المقترَحة للحصول على التبعيات الثنائية هي إضافة ما يلي إلى ملف CMakeLists.txt:
              add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)
              set(firebase_libs firebase_auth firebase_firestore firebase_app)
              # Replace the target name below with the actual name of your target,
              # for example, "native-lib".
              target_link_libraries(${YOUR_TARGET_NAME_HERE} "${firebase_libs}")
              
  3. لإعداد الدمج مع أجهزة الكمبيوتر المكتبية، اطّلِع على إضافة Firebase إلى مشروع C++‎.
Unity
  1. اتّبِع التعليمات من أجل إضافة Firebase إلى مشروعك على Unity.
  2. استخدِم واجهة Unity لضبط مشروعك من أجل تصغير إصدارات Android.
  3. يجب تصغير الإصدار لتجنُّب ظهور الرسالة Error while merging dex archives.

    • يمكن العثور على هذا الخيار في إعدادات المشغّل > Android > إعدادات النشر > تصغير.
    • قد تختلف الخيارات في إصدارات Unity المختلفة، لذا يُرجى الرجوع إلى مستندات Unity الرسمية و دليل تصحيح أخطاء إصدار Firebase Unity.
    • إذا كان عدد الطرق المُشار إليها لا يزال يتجاوز الحدّ الأقصى بعد تفعيل ميزة إزالة البيانات غير الضرورية، يمكنك تفعيل multidex في:
      • ‫mainTemplate.gradle في حال تفعيل نموذج Gradle المخصّص ضمن إعدادات المشغّل
      • أو ملف build.gradle على مستوى الوحدة، إذا كنت تستخدم "استوديو Android" لإنشاء المشروع الذي تم تصديره.

(اختياري) إنشاء النماذج الأولية واختبارها باستخدام Firebase Local Emulator Suite

بالنسبة إلى مطوّري التطبيقات للأجهزة الجوّالة، قبل الحديث عن كيفية كتابة تطبيقك للبيانات في Cloud Firestore وقراءتها منها، لنتعرّف على مجموعة من الأدوات التي يمكنك استخدامها لإنشاء نماذج أولية واختبار وظائف Cloud Firestore: Firebase Local Emulator Suite. إذا كنت تجرّب نماذج بيانات مختلفة، أو تحسّن قواعد الأمان، أو تعمل على العثور على الطريقة الأكثر فعالية من حيث التكلفة للتفاعل مع الواجهة الخلفية، فإنّ القدرة على العمل محليًا بدون نشر الخدمات المباشرة يمكن أن تكون فكرة رائعة.

يُعدّ محاكي Cloud Firestore جزءًا من Local Emulator Suite، وهو يتيح لتطبيقك التفاعل مع محتوى قاعدة البيانات التي تمت محاكاتها وإعداداتها، بالإضافة إلى موارد المشروع التي تمت محاكاتها (الدوال وقواعد البيانات الأخرى وقواعد الأمان) بشكل اختياري.

يتطلّب استخدام محاكي Cloud Firestore بضع خطوات فقط:

  1. إضافة سطر من الرموز إلى إعدادات اختبار تطبيقك للاتصال بالمحاكي
  2. من جذر دليل مشروعك على جهاز المستخدم، نفِّذ الأمر firebase emulators:start.
  3. إجراء طلبات من الرمز البرمجي للنموذج الأوّلي لتطبيقك باستخدام حزمة تطوير برامج (SDK) لمنصة Cloud Firestore كالمعتاد

يتوفّر دليل تفصيلي يتضمّن Cloud Firestore وCloud Functions. ننصحك أيضًا بالاطّلاع على مقدمة حول Local Emulator Suite.

إعداد 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);


// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);

استبدِل FIREBASE_CONFIGURATION بـ firebaseConfig لتطبيق الويب.

للاحتفاظ بالبيانات عند فقدان الجهاز للاتصال، يُرجى الاطّلاع على مستندات تفعيل البيانات بلا إنترنت.

Web

import firebase from "firebase/app";
import "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
firebase.initializeApp(firebaseConfig);


// Initialize Cloud Firestore and get a reference to the service
const db = firebase.firestore();

استبدِل FIREBASE_CONFIGURATION بـ firebaseConfig لتطبيق الويب.

للاحتفاظ بالبيانات عند فقدان الجهاز للاتصال، يُرجى الاطّلاع على مستندات تفعيل البيانات بلا إنترنت.

Swift
ملاحظة: لا يتوفّر هذا المنتج على watchOS وأهداف App Clip.
import FirebaseCore
import FirebaseFirestore
FirebaseApp.configure()

let db = Firestore.firestore()
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS وأهداف App Clip.
@import FirebaseCore;
@import FirebaseFirestore;

// Use Firebase library to configure APIs
[FIRApp configure];
  
FIRFirestore *defaultFirestore = [FIRFirestore firestore];

Kotlin

// Access a Cloud Firestore instance from your Activity
val db = Firebase.firestore

Java

// Access a Cloud Firestore instance from your Activity
FirebaseFirestore db = FirebaseFirestore.getInstance();

Dart

db = FirebaseFirestore.instance;
C++‎
// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
App::Create();
Firestore* db = Firestore::GetInstance();
Unity
using Firebase.Firestore;
using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;

إضافة بيانات

تخزّن 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)")
}
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS وأهداف App Clip.
// Add a new document with a generated ID
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Ada",
      @"last": @"Lovelace",
      @"born": @1815
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];

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);
            }
        });

Dart

// Create a new user with a first and last name
final user = <String, dynamic>{
  "first": "Ada",
  "last": "Lovelace",
  "born": 1815
};

// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
    print('DocumentSnapshot added with ID: ${doc.id}'));
C++‎
// Add a new document with a generated ID
Future<DocumentReference> user_ref =
    db->Collection("users").Add({{"first", FieldValue::String("Ada")},
                                 {"last", FieldValue::String("Lovelace")},
                                 {"born", FieldValue::Integer(1815)}});

user_ref.OnCompletion([](const Future<DocumentReference>& future) {
  if (future.error() == Error::kErrorOk) {
    std::cout << "DocumentSnapshot added with ID: " << future.result()->id()
              << std::endl;
  } else {
    std::cout << "Error adding document: " << future.error_message() << std::endl;
  }
});
Unity
DocumentReference docRef = db.Collection("users").Document("alovelace");
Dictionary<string, object> user = new Dictionary<string, object>
{
	{ "First", "Ada" },
	{ "Last", "Lovelace" },
	{ "Born", 1815 },
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
	Debug.Log("Added data to the alovelace document in the users collection.");
});

أضِف الآن مستندًا آخر إلى مجموعة "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)")
}
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS وأهداف App Clip.
// Add a second document with a generated ID.
__block FIRDocumentReference *ref =
    [[self.db collectionWithPath:@"users"] addDocumentWithData:@{
      @"first": @"Alan",
      @"middle": @"Mathison",
      @"last": @"Turing",
      @"born": @1912
    } completion:^(NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error adding document: %@", error);
      } else {
        NSLog(@"Document added with ID: %@", ref.documentID);
      }
    }];

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);
            }
        });

Dart

// Create a new user with a first and last name
final user = <String, dynamic>{
  "first": "Alan",
  "middle": "Mathison",
  "last": "Turing",
  "born": 1912
};

// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
    print('DocumentSnapshot added with ID: ${doc.id}'));
C++‎
db->Collection("users")
    .Add({{"first", FieldValue::String("Alan")},
          {"middle", FieldValue::String("Mathison")},
          {"last", FieldValue::String("Turing")},
          {"born", FieldValue::Integer(1912)}})
    .OnCompletion([](const Future<DocumentReference>& future) {
      if (future.error() == Error::kErrorOk) {
        std::cout << "DocumentSnapshot added with ID: "
                  << future.result()->id() << std::endl;
      } else {
        std::cout << "Error adding document: " << future.error_message()
                  << std::endl;
      }
    });
Unity
DocumentReference docRef = db.Collection("users").Document("aturing");
Dictionary<string, object> user = new Dictionary<string, object>
{
	{ "First", "Alan" },
	{ "Middle", "Mathison" },
	{ "Last", "Turing" },
	{ "Born", 1912 }
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
	Debug.Log("Added data to the aturing document in the users collection.");
});

قراءة البيانات

استخدِم عارض البيانات في وحدة تحكّم 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)")
}
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS وأهداف App Clip.
[[self.db collectionWithPath:@"users"]
    getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot,
                                 NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Error getting documents: %@", error);
      } else {
        for (FIRDocumentSnapshot *document in snapshot.documents) {
          NSLog(@"%@ => %@", document.documentID, document.data);
        }
      }
    }];

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());
                }
            }
        });

Dart

await db.collection("users").get().then((event) {
  for (var doc in event.docs) {
    print("${doc.id} => ${doc.data()}");
  }
});
C++‎
Future<QuerySnapshot> users = db->Collection("users").Get();
users.OnCompletion([](const Future<QuerySnapshot>& future) {
  if (future.error() == Error::kErrorOk) {
    for (const DocumentSnapshot& document : future.result()->documents()) {
      std::cout << document << std::endl;
    }
  } else {
    std::cout << "Error getting documents: " << future.error_message()
              << std::endl;
  }
});
Unity
CollectionReference usersRef = db.Collection("users");
usersRef.GetSnapshotAsync().ContinueWithOnMainThread(task =>
{
  QuerySnapshot snapshot = task.Result;
  foreach (DocumentSnapshot document in snapshot.Documents)
  {
    Debug.Log(String.Format("User: {0}", document.Id));
    Dictionary<string, object> documentDictionary = document.ToDictionary();
    Debug.Log(String.Format("First: {0}", documentDictionary["First"]));
    if (documentDictionary.ContainsKey("Middle"))
    {
      Debug.Log(String.Format("Middle: {0}", documentDictionary["Middle"]));
    }

    Debug.Log(String.Format("Last: {0}", documentDictionary["Last"]));
    Debug.Log(String.Format("Born: {0}", documentDictionary["Born"]));
  }

  Debug.Log("Read all data from the users collection.");
});

تأمين بياناتك

إذا كنت تستخدم حزمة تطوير البرامج (SDK) للويب أو 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. يُرجى الاطّلاع على مستندات فحص التطبيقات.

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

مشاهدة فيديو تعليمي

للحصول على إرشادات مفصّلة حول بدء استخدام مكتبات عملاء تطبيقات الجوّال في Cloud Firestore، يمكنك مشاهدة أحد الفيديوهات التعليمية التالية:

الويب
iOS+‎
Android

يمكنك العثور على المزيد من الفيديوهات في قناة Firebase على YouTube.

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

يمكنك تعميق معرفتك من خلال المواضيع التالية:

  • الدروس التطبيقية حول الترميز: تعلَّم كيفية استخدام Cloud Firestore في تطبيق حقيقي من خلال اتّباع الدرس التطبيقي حول الترميز لنظام التشغيل Android أو iOS أو الويب.
  • نموذج البيانات: يمكنك الاطّلاع على مزيد من المعلومات حول كيفية تنظيم البيانات في Cloud Firestore، بما في ذلك البيانات الهرمية والمجموعات الفرعية.
  • إضافة البيانات: مزيد من المعلومات حول إنشاء البيانات وتعديلها في Cloud Firestore
  • الحصول على البيانات: مزيد من المعلومات حول كيفية استرداد البيانات
  • إجراء طلبات بحث بسيطة ومركّبة: تعرَّف على كيفية إجراء طلبات بحث بسيطة ومركّبة.
  • ترتيب طلبات البحث وحصرها تعرَّف على كيفية ترتيب البيانات التي تعرضها طلبات البحث وحصرها.
  • مهارات وكلاء Firebase: تعرَّف على كيفية تحسين أدوات المطوّرين بالذكاء الاصطناعي لتنفيذ المهام بفعالية أكبر واستخدام أفضل الممارسات Cloud Firestore (مثل كتابة Cloud Firestore Security Rules).