توفّر Cloud Firestore ميزة الاحتفاظ بالبيانات بلا إنترنت. تخزِّن هذه الميزة نسخة في ذاكرة التخزين المؤقت من بيانات Cloud Firestore التي يستخدمها تطبيقك بشكل نشط، حتى تتمكّن التطبيق من الوصول إلى البيانات عندما يكون الجهاز غير متصل بالإنترنت. يمكنك كتابة البيانات المخزّنة مؤقتًا وقراءتها والاستماع إليها والاستعلام عنها. عندما يعود الجهاز إلى الاتصال بالإنترنت، تتم مزامنة أي تغييرات محلية أجراها تطبيقك مع البنية الأساسية لتطبيق Cloud Firestore.Cloud Firestore
لاستخدام ميزة "التخزين المؤقت بلا إنترنت"، ليس عليك إجراء أي تغييرات على الرمز الذي تستخدمه للوصول إلى بيانات Cloud Firestore. عند تفعيل ميزة "الوصول إلى البيانات بلا إنترنت"، تدِير مكتبة عملاء Cloud Firestore تلقائيًا إمكانية الوصول إلى البيانات على الإنترنت وعلى الأجهزة بلا إنترنت، كما تتم مزامنة البيانات المحلية عند إعادة اتصال الجهاز بالإنترنت.
ضبط ميزة الاحتفاظ بالبيانات بلا إنترنت
عند بدء Cloud Firestore، يمكنك تفعيل أو إيقاف الحفاظ على البيانات بلا إنترنت:
- بالنسبة إلى منصّتَي Android وApple، تكون ميزة الاحتفاظ بالبيانات بلا إنترنت مفعّلة تلقائيًا. لإيقاف
الاستمرارية، اضبط الخيار
PersistenceEnabledعلىfalse. - بالنسبة إلى الويب، تكون ميزة الاحتفاظ بالبيانات بلا إنترنت غير مفعَّلة تلقائيًا. لتفعيل
الثبات، يمكنك استدعاء الطريقة
enablePersistence. لا يتم محو ذاكرة التخزين المؤقت لتطبيق Cloud Firestore تلقائيًا بين الجلسات. نتيجةً لذلك، إذا كان تطبيق الويب الخاص بك يعالج معلومات حسّاسة، احرص على سؤال المستخدم عمّا إذا كان يستخدم جهازًا موثوقًا قبل تفعيل ميزة الاحتفاظ بالبيانات.
// Memory cache is the default if no config is specified.
initializeFirestore(app);
// This is the default behavior if no persistence is specified.
initializeFirestore(app, {localCache: memoryLocalCache()});
// Defaults to single-tab persistence if no tab manager is specified.
initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})});
// Same as `initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})})`,
// but more explicit about tab management.
initializeFirestore(app,
{localCache:
persistentLocalCache(/*settings*/{tabManager: persistentSingleTabManager()})
});
// Use multi-tab IndexedDb persistence.
initializeFirestore(app,
{localCache:
persistentLocalCache(/*settings*/{tabManager: persistentMultipleTabManager()})
});
firebase.firestore().enablePersistence() .catch((err) => { if (err.code == 'failed-precondition') { // Multiple tabs open, persistence can only be enabled // in one tab at a a time. // ... } else if (err.code == 'unimplemented') { // The current browser does not support all of the // features required to enable persistence // ... } }); // Subsequent queries will use persistence, if it was enabled successfully
let settings = FirestoreSettings() // Use memory-only cache settings.cacheSettings = MemoryCacheSettings(garbageCollectorSettings: MemoryLRUGCSettings()) // Use persistent disk cache, with 100 MB cache size settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber) // Any additional options // ... // Enable offline data persistence let db = Firestore.firestore() db.settings = settings
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init]; // Use memory-only cache settings.cacheSettings = [[FIRMemoryCacheSettings alloc] initWithGarbageCollectorSettings:[[FIRMemoryLRUGCSettings alloc] init]]; // Use persistent disk cache (default behavior) // This example uses 100 MB. settings.cacheSettings = [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)]; // Any additional options // ... // Enable offline data persistence FIRFirestore *db = [FIRFirestore firestore]; db.settings = settings;
val settings = firestoreSettings { // Use memory cache setLocalCacheSettings(memoryCacheSettings {}) // Use persistent disk cache (default) setLocalCacheSettings(persistentCacheSettings {}) } db.firestoreSettings = settings
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder(db.getFirestoreSettings()) // Use memory-only cache .setLocalCacheSettings(MemoryCacheSettings.newBuilder().build()) // Use persistent disk cache (default) .setLocalCacheSettings(PersistentCacheSettings.newBuilder() .build()) .build(); db.setFirestoreSettings(settings);
// Apple and Android db.settings = const Settings(persistenceEnabled: true); // Web await db .enablePersistence(const PersistenceSettings(synchronizeTabs: true));
ضبط حجم ذاكرة التخزين المؤقت
عند تفعيل ميزة الاحتفاظ بالبيانات، يخزِّن Cloud Firestore كل مستند يتم تلقّيه من الخلفية للوصول إليه بلا إنترنت. تُحدِّد Cloud Firestore حدًا تلقائيًا لحجم ذاكرة التخزين المؤقت. بعد تجاوز الحدّ التلقائي، يحاول Cloud Firestore بصفة دورية تنظيف المستندات القديمة غير المستخدَمة. يمكنك ضبط حدّ مختلف لحجم ذاكرة التخزين المؤقت أو إيقاف عملية التنظيف بالكامل:
import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore"; const firestoreDb = initializeFirestore(app, { cacheSizeBytes: CACHE_SIZE_UNLIMITED });
firebase.firestore().settings({ cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED });
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "FirestoreCacheSizeUnlimited" // to disable clean-up. let settings = Firestore.firestore().settings // Set cache size to 100 MB settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber) Firestore.firestore().settings = settings
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "kFIRFirestoreCacheSizeUnlimited" // to disable clean-up. FIRFirestoreSettings *settings = [FIRFirestore firestore].settings; // Set cache size to 100 MB settings.cacheSettings = [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)]; [FIRFirestore firestore].settings = settings;
// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED" // to disable clean-up. val settings = FirebaseFirestoreSettings.Builder() .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED) .build() db.firestoreSettings = settings
// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED" // to disable clean-up. FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder() .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED) .build(); db.setFirestoreSettings(settings);
db.settings = const Settings( persistenceEnabled: true, cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED, );
الاستماع إلى البيانات بلا إنترنت
عندما يكون الجهاز غير متصل بالإنترنت، إذا فعّلت ميزة الاحتفاظ بالبيانات بلا إنترنت، سيتلقّى المستمعون أحداث الاستماع عند تغيير البيانات المخزّنة مؤقتًا على الجهاز. يمكنك الاستماع إلى المستندات والمجموعات وطلبات البحث.
للتحقّق ممّا إذا كنت تتلقّى البيانات من الخادم أو من ذاكرة التخزين المؤقت، استخدِم الخاصية
fromCache في SnapshotMetadata في حدث اللقطة. إذا كان
fromCache يساوي true، يعني ذلك أنّ البيانات مصدرها ذاكرة التخزين المؤقت وقد تكون قديمة أو
غير مكتملة. إذا كان fromCache يساوي false، تكون البيانات كاملة وحديثة وتتضمّن
أحدث التعديلات على الخادم.
لا يتم تلقائيًا تنشيط أي حدث في حال تغيّر SnapshotMetadata فقط. إذا
كنت تعتمد على قيم fromCache، حدِّد الخيار includeMetadataChanges listen
عند إرفاق معالِج الاستماع.
import { collection, onSnapshot, where, query } from "firebase/firestore"; const q = query(collection(db, "cities"), where("state", "==", "CA")); onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => { snapshot.docChanges().forEach((change) => { if (change.type === "added") { console.log("New city: ", change.doc.data()); } const source = snapshot.metadata.fromCache ? "local cache" : "server"; console.log("Data came from " + source); }); });
db.collection("cities").where("state", "==", "CA") .onSnapshot({ includeMetadataChanges: true }, (snapshot) => { snapshot.docChanges().forEach((change) => { if (change.type === "added") { console.log("New city: ", change.doc.data()); } var source = snapshot.metadata.fromCache ? "local cache" : "server"; console.log("Data came from " + source); }); });
// Listen to metadata updates to receive a server snapshot even if // the data is the same as the cached data. db.collection("cities").whereField("state", isEqualTo: "CA") .addSnapshotListener(includeMetadataChanges: true) { querySnapshot, error in guard let snapshot = querySnapshot else { print("Error retreiving snapshot: \(error!)") return } for diff in snapshot.documentChanges { if diff.type == .added { print("New city: \(diff.document.data())") } } let source = snapshot.metadata.isFromCache ? "local cache" : "server" print("Metadata: Data fetched from \(source)") }
// Listen to metadata updates to receive a server snapshot even if // the data is the same as the cached data. [[[db collectionWithPath:@"cities"] queryWhereField:@"state" isEqualTo:@"CA"] addSnapshotListenerWithIncludeMetadataChanges:YES listener:^(FIRQuerySnapshot *snapshot, NSError *error) { if (snapshot == nil) { NSLog(@"Error retreiving snapshot: %@", error); return; } for (FIRDocumentChange *diff in snapshot.documentChanges) { if (diff.type == FIRDocumentChangeTypeAdded) { NSLog(@"New city: %@", diff.document.data); } } NSString *source = snapshot.metadata.isFromCache ? @"local cache" : @"server"; NSLog(@"Metadata: Data fetched from %@", source); }];
db.collection("cities").whereEqualTo("state", "CA") .addSnapshotListener(MetadataChanges.INCLUDE) { querySnapshot, e -> if (e != null) { Log.w(TAG, "Listen error", e) return@addSnapshotListener } for (change in querySnapshot!!.documentChanges) { if (change.type == DocumentChange.Type.ADDED) { Log.d(TAG, "New city: ${change.document.data}") } val source = if (querySnapshot.metadata.isFromCache) { "local cache" } else { "server" } Log.d(TAG, "Data fetched from $source") } }
db.collection("cities").whereEqualTo("state", "CA") .addSnapshotListener(MetadataChanges.INCLUDE, new EventListener<QuerySnapshot>() { @Override public void onEvent(@Nullable QuerySnapshot querySnapshot, @Nullable FirebaseFirestoreException e) { if (e != null) { Log.w(TAG, "Listen error", e); return; } for (DocumentChange change : querySnapshot.getDocumentChanges()) { if (change.getType() == Type.ADDED) { Log.d(TAG, "New city:" + change.getDocument().getData()); } String source = querySnapshot.getMetadata().isFromCache() ? "local cache" : "server"; Log.d(TAG, "Data fetched from " + source); } } });
db .collection("cities") .where("state", isEqualTo: "CA") .snapshots(includeMetadataChanges: true) .listen((querySnapshot) { for (var change in querySnapshot.docChanges) { if (change.type == DocumentChangeType.added) { final source = (querySnapshot.metadata.isFromCache) ? "local cache" : "server"; print("Data fetched from $source}"); } } });
الحصول على البيانات بلا إنترنت
إذا تلقّيت مستندًا عندما يكون الجهاز غير متصل بالإنترنت، يعرض تطبيق Cloud Firestore البيانات من ذاكرة التخزين المؤقت.
عند طلب البحث في مجموعة، يتم عرض نتيجة فارغة إذا لم تكن هناك مستندات في ذاكرة التخزين المؤقت. عند جلب مستند محدّد، يتم عرض خطأ بدلاً من ذلك.
طلب البحث في البيانات المتوفّرة بلا إنترنت
تعمل طلبات البحث مع ميزة الاحتفاظ بالبيانات بلا إنترنت. يمكنك استرداد نتائج طلبات البحث إما من خلال طلب مباشر أو من خلال الاستماع، كما هو موضّح في الأقسام السابقة. يمكنك أيضًا إنشاء طلبات بحث جديدة عن البيانات المحفوظة على الجهاز عندما يكون الجهاز غير متصل بالإنترنت، ولكن لن يتم تنفيذ طلبات البحث في البداية إلا على المستندات التي تم تخزينها مؤقتًا في ذاكرة التخزين المؤقت.
ضبط فهارس طلبات البحث بلا إنترنت
تبحث حزمة تطوير البرامج (SDK) لـ Firestore تلقائيًا في ذاكرة التخزين المؤقتة المحلية عن جميع المستندات في مجموعة عند تنفيذ طلبات بحث بلا إنترنت. مع هذا السلوك التلقائي، يمكن أن ينخفض أداء طلبات البحث بلا إنترنت عندما يكون المستخدمون بلا إنترنت لفترات طويلة.
عند تفعيل ميزة "الذاكرة المؤقتة الثابتة"، يمكنك تحسين أداء طلبات البحث بلا إنترنت من خلال السماح لحزمة تطوير البرامج (SDK) بإنشاء فهارس طلبات بحث محلية تلقائيًا.
تكون الفهرسة التلقائية غير مفعّلة تلقائيًا. يجب أن يفعّل تطبيقك الترتيب العميق تلقائيًا في كل مرة يتم فيها تشغيله. يمكنك التحكّم في ما إذا كانت الفهرسة التلقائية مفعَّلة كما هو موضّح أدناه.
if let indexManager = Firestore.firestore().persistentCacheIndexManager { // Indexing is disabled by default indexManager.enableIndexAutoCreation() } else { print("indexManager is nil") }
PersistentCacheIndexManager *indexManager = [FIRFirestore firestore].persistentCacheIndexManager; if (indexManager) { // Indexing is disabled by default [indexManager enableIndexAutoCreation]; }
// return type: PersistentCacheManager? Firebase.firestore.persistentCacheIndexManager?.apply { // Indexing is disabled by default enableIndexAutoCreation() } ?: println("indexManager is null")
// return type: @Nullable PersistentCacheIndexManager PersistentCacheIndexManager indexManager = FirebaseFirestore.getInstance().getPersistentCacheIndexManager(); if (indexManager != null) { // Indexing is disabled by default indexManager.enableIndexAutoCreation(); } // If not check indexManager != null, IDE shows warning: Method invocation 'enableIndexAutoCreation' may produce 'NullPointerException' FirebaseFirestore.getInstance().getPersistentCacheIndexManager().enableIndexAutoCreation();
بعد تفعيل الفهرسة التلقائية، تقيِّم حزمة تطوير البرامج (SDK) المجموعات التي تحتوي على عدد كبير من المستندات المخزّنة مؤقتًا وتحسِّن أداء طلبات البحث المحلية.
توفّر حزمة SDK طريقة لحذف فهارس طلبات البحث.
إيقاف الوصول إلى الشبكة وتفعيله
يمكنك استخدام الطريقة الموضّحة أدناه لإيقاف إمكانية الوصول إلى الشبكة لعملاء Cloud Firestore. عندما يكون الوصول إلى الشبكة غير مفعّل، تسترجع جميع عمليات الاطّلاع على اللقطات وطلبات المستندات النتائج من ذاكرة التخزين المؤقت. يتم وضع عمليات الكتابة في قائمة الانتظار إلى أن تتم إعادة تفعيل إمكانية الوصول إلى الشبكة.
import { disableNetwork } from "firebase/firestore"; await disableNetwork(db); console.log("Network disabled!"); // Do offline actions // ...
firebase.firestore().disableNetwork() .then(() => { // Do offline actions // ... });
Firestore.firestore().disableNetwork { (error) in // Do offline things // ... }
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) { // Do offline actions // ... }];
db.disableNetwork().addOnCompleteListener { // Do offline things // ... }
db.disableNetwork() .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // Do offline things // ... } });
db.disableNetwork().then((_) { // Do offline things });
اتّبِع الطريقة التالية لإعادة تفعيل إمكانية الوصول إلى الشبكة:
import { enableNetwork } from "firebase/firestore"; await enableNetwork(db); // Do online actions // ...
firebase.firestore().enableNetwork() .then(() => { // Do online actions // ... });
Firestore.firestore().enableNetwork { (error) in // Do online things // ... }
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) { // Do online actions // ... }];
db.enableNetwork().addOnCompleteListener { // Do online things // ... }
db.enableNetwork() .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // Do online things // ... } });
db.enableNetwork().then((_) { // Back online });