يوضّح لك هذا الدليل السريع كيفية إعداد Cloud Firestore، ثم إضافة البيانات، ثم عرض البيانات التي أضفتها في وحدة تحكّم Firebase.
إنشاء قاعدة بيانات Cloud Firestore
إذا لم يسبق لك إنشاء مشروع على Firebase، يمكنك إنشاء مشروع باتّباع الخطوات التالية: في Firebaseوحدة التحكّم، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروع على Firebase أو لإضافة خدمات Firebase إلى مشروع Google Cloud حالي.
افتح مشروعك في وحدة تحكّم Firebase. في اللوحة اليمنى، وسِّع إنشاء، ثم اختَر قاعدة بيانات Firestore.
انقر على إنشاء قاعدة بيانات.
اختَر موقعًا جغرافيًا لقاعدة البيانات.
إذا لم تتمكّن من اختيار موقع جغرافي، يعني ذلك أنّه تمّ ضبط "الموقع الجغرافي للموارد التلقائية Google Cloud" لمشروعك. تتشارك بعض موارد مشروعك (مثل مثيل Cloud Firestore التلقائي) في تبعية الموقع الجغرافي الشائعة، ويمكن ضبط الموقع الجغرافي إما أثناء إنشاء المشروع أو عند إعداد خدمة أخرى تتشارك في تبعية الموقع الجغرافي هذه.
اختَر وضعًا لبدء Cloud Firestore Security Rules:
- وضع الاختبار
هذه الطريقة مناسبة للبدء باستخدام مكتبات برامج الأجهزة الجوّالة والويب، ولكنّها تتيح لأي شخص قراءة بياناتك واستبدالها. بعد إجراء الاختبار، احرص على مراجعة قسم تأمين بياناتك.
لبدء استخدام حزمة تطوير البرامج (SDK) على الويب أو منصات Apple أو 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 لكل قاعدة بيانات.
انقر على إنشاء.
عند تفعيل Cloud Firestore، يتم أيضًا تفعيل واجهة برمجة التطبيقات في Cloud API Manager.
إعداد بيئة التطوير
أضِف التبعيات ومكتبات البرامج المطلوبة إلى تطبيقك.
Web
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
-
تتوفّر حزمة تطوير البرامج (SDK) Cloud Firestore كحزمة npm.
عليك استيراد كلّ من Firebase وCloud Firestore.npm install firebase@12.0.0 --save
import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";
Web
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب.
- أضِف مكتبتَي Firebase وCloud Firestore إلى تطبيقك:
تتوفّر حزمة تطوير البرامج (SDK) Cloud Firestore أيضًا كحزمة npm.<script src="https://www.gstatic.com/firebasejs/12.0.0/firebase-app-compat.js"></script> <script src="https://www.gstatic.com/firebasejs/12.0.0/firebase-firestore-compat.js"></script>
يجب طلب كلّ من Firebase وCloud Firestore يدويًا.npm install firebase@12.0.0 --save
import firebase from "firebase/compat/app"; // Required for side-effects import "firebase/firestore";
iOS+
اتّبِع التعليمات لإضافة Firebase إلى تطبيق Apple.
استخدِم أداة Swift Package Manager لتثبيت الموارد الاعتمادية في Firebase وإدارتها.
- في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف (File) > حِزم Swift (Swift Packages) > إضافة تبعية الحزمة (Add Package Dependency).
- عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصة Firebase على أجهزة Apple:
- اختَر مكتبة Firestore.
- بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.
https://github.com/firebase/firebase-ios-sdk
Android
- اتّبِع التعليمات لإضافة Firebase إلى تطبيق Android.
- باستخدام قائمة مواد 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:33.16.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:25.1.4") }
هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ بدءًا من إصدار تشرين الأول (أكتوبر) 2023، يمكن لكل من مطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للحصول على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).
Dart
- إذا لم يسبق لك إجراء ذلك، اضبط إعدادات Firebase وأعِدها في تطبيق Flutter.
- من جذر مشروع Flutter، شغِّل الأمر التالي لتثبيت المكوّن الإضافي:
flutter pub add cloud_firestore
- بعد الانتهاء، أعِد إنشاء تطبيق Flutter باتّباع الخطوات التالية:
flutter run
- اختياري: يمكنك تحسين أوقات إنشاء إصدارات iOS وmacOS من خلال تضمين إطار العمل المجمَّع مسبقًا.
في الوقت الحالي، تعتمد حزمة تطوير البرامج (SDK) لخدمة Firestore لنظام التشغيل iOS على رمز برمجي قد يستغرق إنشاؤه في Xcode أكثر من 5 دقائق. لتقليل أوقات الإنشاء بشكل كبير، يمكنك استخدام نسخة مجمَّعة مسبقًا عن طريق إضافة هذا السطر إلى حظر
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) لنظام التشغيل iOS من Firebase المحدّد في ملف
firebase_core
firebase_sdk_version.rb
. إذا لم تكن تستخدم أحدث إصدار منfirebase_core
، ابحث عن هذا الملف في ذاكرة التخزين المؤقت المحلية لحزمة Pub (عادةً~/.pub-cache
).بالإضافة إلى ذلك، تأكَّد من ترقية CocoaPods إلى الإصدار 1.9.1 أو إصدار أحدث:
gem install cocoapods
لمزيد من المعلومات، يُرجى الاطّلاع على المشكلة على GitHub.
Java
- أضِف حزمة تطوير البرامج (SDK) الخاصة بمدير Firebase إلى تطبيقك:
-
استخدام Gradle:
compile 'com.google.firebase:firebase-admin:1.32.0'
-
استخدام Maven:
<dependency> <groupId>com.google.firebase</groupId> <artifactId>firebase-admin</artifactId> <version>1.32.0</version> </dependency>
-
استخدام Gradle:
- اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
Python
- أضِف حزمة تطوير البرامج (SDK) لميزة "مشرف Firebase" إلى تطبيق Python:
pip install --upgrade firebase-admin
- اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
C++
- اتّبِع التعليمات لإضافة Firebase إلى مشروع C++.
- واجهة 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}")
- لإعداد عملية الدمج على أجهزة الكمبيوتر، اطّلِع على إضافة Firebase إلى مشروع C++.
Unity
- اتّبِع التعليمات لإضافة Firebase إلى مشروعك على Unity.
- استخدِم واجهة Unity لضبط مشروعك بهدف تصغير حجم إصدارات Android.
- يمكن العثور على هذا الخيار في إعدادات المشغّل > Android > إعدادات النشر > تصغير.
- قد تختلف الخيارات في إصدارات مختلفة من Unity، لذا يُرجى الرجوع إلى مستندات Unity الرسمية ودليل تصحيح أخطاء إصدار Firebase Unity.
-
إذا ظل عدد الطرق المشار إليها يتجاوز الحدّ الأقصى بعد تفعيل التصغير، يمكنك تفعيل
multidex
في:-
mainTemplate.gradle
إذا كان خيار نموذج Gradle المخصّص ضِمن إعدادات المشغّل مفعَّلاً -
أو ملف
build.gradle
على مستوى الوحدة، إذا كنت تستخدم "استوديو Android" لإنشاء المشروع الذي تم تصديره.
-
يجب تصغير حجم الإصدار لتجنُّب الرسالة Error while merging dex archives
.
Node.js
-
أضِف حزمة تطوير البرامج (SDK) الخاصة بـ Firebase Admin إلى تطبيقك:
npm install firebase-admin --save
- اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
Go
- أضِف حزمة تطوير البرامج (SDK) الخاصة بـ Firebase Admin إلى تطبيق Go:
go get firebase.google.com/go
- اتّبِع التعليمات أدناه لتهيئة Cloud Firestore باستخدام بيانات الاعتماد المناسبة في بيئتك.
PHP
-
تستخدم مكتبات برامج الخادم Cloud Firestore (Java وNode.js وPython وGo وPHP وC# وRuby) بيانات الاعتماد التلقائية لتطبيق Google للمصادقة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
GOOGLE_APPLICATION_CREDENTIALS
ليشير إلى ملف مفتاح JSON لحساب الخدمة. يمكنك إنشاء ملف مفتاح في صفحة بيانات الاعتماد في API Console.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- في بيئة الإنتاج، لن تحتاج إلى المصادقة إذا شغّلت تطبيقك على App Engine أو Compute Engine باستخدام المشروع نفسه الذي تستخدمه في Cloud Firestore. وإلا، عليك إعداد حساب خدمة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
- ثبِّت إضافة gRPC وفعِّلها لبرنامج PHP، وهي إضافة ضرورية لاستخدام مكتبة البرامج.
-
أضِف مكتبة Cloud Firestore PHP إلى تطبيقك:
composer require google/cloud-firestore
#C
-
تستخدم مكتبات برامج الخادم Cloud Firestore (Java وNode.js وPython وGo وPHP وC# وRuby) بيانات الاعتماد التلقائية لتطبيق Google للمصادقة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
GOOGLE_APPLICATION_CREDENTIALS
ليشير إلى ملف مفتاح JSON لحساب الخدمة. يمكنك إنشاء ملف مفتاح في صفحة بيانات الاعتماد في API Console.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- في بيئة الإنتاج، لن تحتاج إلى المصادقة إذا شغّلت تطبيقك على App Engine أو Compute Engine باستخدام المشروع نفسه الذي تستخدمه في Cloud Firestore. وإلا، عليك إعداد حساب خدمة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
-
أضِف مكتبة Cloud Firestore C# إلى تطبيقك في ملف
.csproj
:<ItemGroup> <PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" /> </ItemGroup>
-
أضِف ما يلي إلى ملف
Program.cs
:using Google.Cloud.Firestore;
لغة Ruby
-
تستخدم مكتبات برامج الخادم Cloud Firestore (Java وNode.js وPython وGo وPHP وC# وRuby) بيانات الاعتماد التلقائية لتطبيق Google للمصادقة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
GOOGLE_APPLICATION_CREDENTIALS
ليشير إلى ملف مفتاح JSON لحساب الخدمة. يمكنك إنشاء ملف مفتاح في صفحة بيانات الاعتماد في API Console.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- في بيئة الإنتاج، لن تحتاج إلى المصادقة إذا شغّلت تطبيقك على App Engine أو Compute Engine باستخدام المشروع نفسه الذي تستخدمه في Cloud Firestore. وإلا، عليك إعداد حساب خدمة.
-
لإجراء المصادقة من بيئة التطوير، اضبط متغيّر البيئة
-
أضِف مكتبة Cloud Firestore Ruby إلى تطبيقك في
Gemfile
:gem "google-cloud-firestore"
-
ثبِّت التبعيات من
Gemfile
باستخدام:bundle install
(اختياري) إنشاء نموذج أوّلي واختباره باستخدام Firebase Local Emulator Suite
بالنسبة إلى مطوّري التطبيقات على الأجهزة الجوّالة، قبل التحدّث عن كيفية كتابة تطبيقك في Cloud Firestore والقراءة منه، دعنا نقدّم مجموعة من الأدوات التي يمكنك استخدامها لإنشاء نماذج أولية واختبار وظائف Cloud Firestore: Firebase Local Emulator Suite. إذا كنت بصدد تجربة نماذج بيانات مختلفة أو تحسين قواعد الأمان أو البحث عن الطريقة الأكثر فعالية من حيث التكلفة للتفاعل مع الخلفية، قد يكون من المفيد أن تتمكّن من العمل محليًا بدون نشر الخدمات المباشرة.
يُعدّ Cloud Firestore المحاكي جزءًا من Local Emulator Suite، ما يتيح لتطبيقك التفاعل مع المحتوى والإعدادات المحاكية لقاعدة البيانات، بالإضافة إلى موارد المشروع المحاكية (الدوال وقواعد البيانات الأخرى وقواعد الأمان) بشكل اختياري.
لا يتطلّب استخدام محاكي Cloud Firestore سوى بضع خطوات:
- إضافة سطر من الرمز البرمجي إلى إعدادات الاختبار في تطبيقك للاتصال بالمحاكي
- من جذر دليل مشروعك المحلي، شغِّل
firebase emulators:start
. - إجراء مكالمات من رمز النموذج الأولي لتطبيقك باستخدام حزمة تطوير البرامج (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
import FirebaseCore import FirebaseFirestore
FirebaseApp.configure() let db = Firestore.firestore()
Objective-C
@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;
Java
يتم إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Firestore بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، راجِع إعداد حزمة SDK للمشرف.import com.google.auth.oauth2.GoogleCredentials; import com.google.cloud.firestore.Firestore; import com.google.firebase.FirebaseApp; import com.google.firebase.FirebaseOptions; // Use the application default credentials GoogleCredentials credentials = GoogleCredentials.getApplicationDefault(); FirebaseOptions options = new FirebaseOptions.Builder() .setCredentials(credentials) .setProjectId(projectId) .build(); FirebaseApp.initializeApp(options); Firestore db = FirestoreClient.getFirestore();
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase على الخادم الخاص بك، استخدِم حساب خدمة.
انتقِل إلى المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لإعداد حزمة تطوير البرامج (SDK):
import com.google.auth.oauth2.GoogleCredentials; import com.google.cloud.firestore.Firestore; import com.google.firebase.FirebaseApp; import com.google.firebase.FirebaseOptions; // Use a service account InputStream serviceAccount = new FileInputStream("path/to/serviceAccount.json"); GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount); FirebaseOptions options = new FirebaseOptions.Builder() .setCredentials(credentials) .build(); FirebaseApp.initializeApp(options); Firestore db = FirestoreClient.getFirestore();
Python
يتم إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Firestore بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، راجِع إعداد حزمة SDK للمشرف.import firebase_admin from firebase_admin import firestore # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore.client()
يمكن أيضًا استخدام بيانات الاعتماد التلقائية الحالية للتطبيق من أجل تهيئة حزمة تطوير البرامج (SDK).
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore.client()
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase على الخادم الخاص بك، استخدِم حساب خدمة.
انتقِل إلى المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لإعداد حزمة تطوير البرامج (SDK):
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore # Use a service account. cred = credentials.Certificate('path/to/serviceAccount.json') app = firebase_admin.initialize_app(cred) db = firestore.client()
Python
يتم إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Firestore بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، راجِع إعداد حزمة SDK للمشرف.import firebase_admin from firebase_admin import firestore_async # Application Default credentials are automatically created. app = firebase_admin.initialize_app() db = firestore_async.client()
يمكن أيضًا استخدام بيانات الاعتماد التلقائية الحالية للتطبيق من أجل تهيئة حزمة تطوير البرامج (SDK).
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use the application default credentials. cred = credentials.ApplicationDefault() firebase_admin.initialize_app(cred) db = firestore_async.client()
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase على الخادم الخاص بك، استخدِم حساب خدمة.
انتقِل إلى المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لإعداد حزمة تطوير البرامج (SDK):
import firebase_admin from firebase_admin import credentials from firebase_admin import firestore_async # Use a service account. cred = credentials.Certificate('path/to/serviceAccount.json') app = firebase_admin.initialize_app(cred) db = firestore_async.client()
C++
// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance(). App::Create(); Firestore* db = Firestore::GetInstance();
Node.js
يتم إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Firestore بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، راجِع إعداد حزمة SDK للمشرف.-
الإعداد في Cloud Functions
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp(); const db = getFirestore();
-
الإعداد في Google Cloud
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp({ credential: applicationDefault() }); const db = getFirestore();
-
بدء الاستخدام على الخادم الخاص بك
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase على الخادم الخاص بك (أو أي بيئة Node.js أخرى)، استخدِم حساب خدمة. انتقِل إلى إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لإعداد حزمة تطوير البرامج (SDK):
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app'); const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
const serviceAccount = require('./path/to/serviceAccountKey.json'); initializeApp({ credential: cert(serviceAccount) }); const db = getFirestore();
Go
يتم إعداد حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Firestore بطرق مختلفة حسب بيئتك. في ما يلي الطرق الأكثر شيوعًا. للحصول على مرجع كامل، راجِع إعداد حزمة SDK للمشرف.import ( "log" firebase "firebase.google.com/go" "google.golang.org/api/option" ) // Use the application default credentials ctx := context.Background() conf := &firebase.Config{ProjectID: projectID} app, err := firebase.NewApp(ctx, conf) if err != nil { log.Fatalln(err) } client, err := app.Firestore(ctx) if err != nil { log.Fatalln(err) } defer client.Close()
لاستخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase على الخادم الخاص بك، استخدِم حساب خدمة.
انتقِل إلى المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة في Google Cloud Console. أنشئ مفتاحًا خاصًا جديدًا واحفظ ملف JSON. بعد ذلك، استخدِم الملف لإعداد حزمة تطوير البرامج (SDK):
import ( "log" firebase "firebase.google.com/go" "google.golang.org/api/option" ) // Use a service account ctx := context.Background() sa := option.WithCredentialsFile("path/to/serviceAccount.json") app, err := firebase.NewApp(ctx, nil, sa) if err != nil { log.Fatalln(err) } client, err := app.Firestore(ctx) if err != nil { log.Fatalln(err) } defer client.Close()
PHP
PHP
لمزيد من المعلومات حول تثبيت وإنشاء عميل Cloud Firestore، يُرجى الرجوع إلى مكتبات عميل Cloud Firestore.
Unity
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
#C
#C
لمزيد من المعلومات حول تثبيت وإنشاء عميل Cloud Firestore، يُرجى الرجوع إلى مكتبات عميل Cloud Firestore.
لغة Ruby
إضافة بيانات
تخزّن 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
// 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
// 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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
لمزيد من المعلومات حول تثبيت وإنشاء عميل Cloud Firestore، يُرجى الرجوع إلى مكتبات عميل Cloud Firestore.
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."); });
#C
لغة Ruby
الآن أضِف مستندًا آخر إلى المجموعة 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
// 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
// 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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
لمزيد من المعلومات حول تثبيت وإنشاء عميل Cloud Firestore، يُرجى الرجوع إلى مكتبات عميل Cloud Firestore.
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."); });
#C
لغة Ruby
قراءة البيانات
استخدِم أداة عرض البيانات في وحدة تحكّم 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
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
[[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()}"); } });
Java
Python
users_ref = db.collection("users") docs = users_ref.stream() for doc in docs: print(f"{doc.id} => {doc.to_dict()}")
Python
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; } });
Node.js
Go
PHP
PHP
لمزيد من المعلومات حول تثبيت وإنشاء عميل Cloud Firestore، يُرجى الرجوع إلى مكتبات عميل Cloud Firestore.
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."); });
#C
لغة Ruby
تأمين بياناتك
إذا كنت تستخدم حزمة تطوير البرامج (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. راجِع مستندات App Check.
إذا كنت تستخدم إحدى حِزم تطوير البرامج (SDK) الخاصة بالخادم، استخدِم إدارة الهوية والوصول (IAM) لتأمين بياناتك في Cloud Firestore.
مشاهدة فيديو تعليمي
للحصول على إرشادات مفصّلة حول كيفية بدء استخدام مكتبات برامج العميل على الأجهزة الجوّالة Cloud Firestore، شاهِد أحد الفيديوهات التعليمية التالية:
الويب
iOS+
Android
يمكنك العثور على المزيد من الفيديوهات في قناة YouTube الخاصة بـ Firebase.
الخطوات التالية
يمكنك تعزيز معرفتك من خلال المواضيع التالية:
- Codelabs: تعرَّف على كيفية استخدام Cloud Firestore في تطبيق حقيقي من خلال اتّباع الخطوات الواردة في Codelab لنظام التشغيل Android أو iOS أو الويب.
- نموذج البيانات: يمكنك الاطّلاع على مزيد من المعلومات حول كيفية تنظيم البيانات في Cloud Firestore، بما في ذلك البيانات الهرمية والمجموعات الفرعية.
- إضافة بيانات: مزيد من المعلومات عن إنشاء البيانات وتعديلها في Cloud Firestore
- الحصول على البيانات: مزيد من المعلومات حول كيفية استرداد البيانات
- إجراء طلبات بحث بسيطة ومركّبة: تعرَّف على كيفية إجراء طلبات بحث بسيطة ومركّبة.
- ترتيب الاستعلامات والحدّ منها تعرَّف على كيفية ترتيب البيانات التي تعرضها استعلاماتك والحدّ منها.