גישה לנתונים במצב לא מקוון

Cloud Firestore תומך בהתמדה של נתונים לא מקוונים. תכונה זו מאחסנת עותק של נתוני Cloud Firestore שהאפליקציה שלך משתמשת בהם באופן פעיל, כך שהאפליקציה שלך יכולה לגשת לנתונים כשהמכשיר במצב לא מקוון. אתה יכול לכתוב, לקרוא, להאזין ולשאול את הנתונים המאוחסנים במטמון. כאשר המכשיר חוזר לאינטרנט, Cloud Firestore מסנכרן את כל השינויים המקומיים שבוצעו על ידי האפליקציה שלך ל-Cloud Firestore.

כדי להשתמש בהתמדה במצב לא מקוון, אינך צריך לבצע שינויים כלשהם בקוד שבו אתה משתמש כדי לגשת לנתוני Cloud Firestore. כאשר התמדה במצב לא מקוון מופעלת, ספריית הלקוחות של Cloud Firestore מנהלת אוטומטית גישה לנתונים מקוונים ולא מקוונים ומסנכרנת נתונים מקומיים כשהמכשיר חוזר למצב מקוון.

הגדר התמדה במצב לא מקוון

כאשר אתה מאתחל את Cloud Firestore, אתה יכול להפעיל או להשבית התמדה במצב לא מקוון:

  • עבור פלטפורמות אנדרואיד ואפל, התמדה במצב לא מקוון מופעלת כברירת מחדל. כדי להשבית את ההתמדה, הגדר את האפשרות PersistenceEnabled ל- false .
  • עבור האינטרנט, התמדה במצב לא מקוון מושבתת כברירת מחדל. כדי לאפשר התמדה, קרא לשיטת enablePersistence . המטמון של Cloud Firestore אינו ניקה אוטומטית בין הפעלות. כתוצאה מכך, אם אפליקציית האינטרנט שלך מטפלת במידע רגיש, הקפד לשאול את המשתמש אם הוא נמצא במכשיר מהימן לפני שתאפשר התמדה.

Web modular API

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

Web namespaced API

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
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
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
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
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;

Kotlin+KTX

val settings = firestoreSettings {
    // Use memory cache
    setLocalCacheSettings(memoryCacheSettings {})
    // Use persistent disk cache (default)
    setLocalCacheSettings(persistentCacheSettings {})
}
db.firestoreSettings = settings

Java

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

Dart

// Apple and Android
db.settings = const Settings(persistenceEnabled: true);

// Web
await db
    .enablePersistence(const PersistenceSettings(synchronizeTabs: true));

הגדר את גודל המטמון

כאשר התמדה מופעלת, Cloud Firestore מאחסנת כל מסמך המתקבל מה-backend לגישה לא מקוונת. Cloud Firestore מגדירה סף ברירת מחדל לגודל המטמון. לאחר חריגה מברירת המחדל, Cloud Firestore מנסה מעת לעת לנקות מסמכים ישנים שאינם בשימוש. אתה יכול להגדיר סף גודל מטמון שונה או להשבית לחלוטין את תהליך הניקוי:

Web modular API

import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";

const firestoreDb = initializeFirestore(app, {
  cacheSizeBytes: CACHE_SIZE_UNLIMITED
});

Web namespaced API

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
// 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
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
// 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;
  

Kotlin+KTX


// 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

Java


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

Dart

db.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);

האזן לנתונים לא מקוונים

כשהמכשיר במצב לא מקוון, אם הפעלת התמדה במצב לא מקוון, המאזינים שלך יקבלו אירועי האזנה כאשר הנתונים המאוחסנים במטמון ישתנו. אתה יכול להאזין למסמכים, אוספים ושאילתות.

כדי לבדוק אם אתה מקבל נתונים מהשרת או מהמטמון, השתמש במאפיין fromCache ב- SnapshotMetadata באירוע תמונת המצב שלך. אם fromCache true , הנתונים הגיעו מהמטמון ועשויים להיות מיושנים או לא שלמים. אם fromCache הוא false , הנתונים מלאים ועדכניים עם העדכונים האחרונים בשרת.

כברירת מחדל, שום אירוע לא מועלה אם רק ה- SnapshotMetadata השתנו. אם אתה מסתמך על ערכי fromCache , ציין את אפשרות ההאזנה includeMetadataChanges כאשר אתה מצרף את מטפל ההאזנה שלך.

Web modular API

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

Web namespaced API

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);
      });
  });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
// 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)")
  }
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
// 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);
    }];

Kotlin+KTX

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

Java

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

            }
        });

Dart

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 מחזיר נתונים מהמטמון.

בעת שאילתת אוסף, תוצאה ריקה מוחזרת אם אין מסמכים שמורים. בעת שליפת מסמך ספציפי, במקום זאת מוחזרת שגיאה.

שאילתות נתונים לא מקוונים

שאילתה עובדת עם התמדה במצב לא מקוון. אתה יכול לאחזר את התוצאות של שאילתות עם Get ישיר או על ידי האזנה, כמתואר בסעיפים הקודמים. אתה יכול גם ליצור שאילתות חדשות על נתונים קבועים מקומיים כשהמכשיר במצב לא מקוון, אבל השאילתות יפעלו בתחילה רק מול המסמכים המאוחסנים במטמון.

הגדר אינדקסים של שאילתות לא מקוונות

כברירת מחדל, Firestore SDK סורק את כל המסמכים באוסף במטמון המקומי שלו בעת ביצוע שאילתות לא מקוונות. עם התנהגות ברירת מחדל זו, ביצועי שאילתות לא מקוונות עלולים להיפגע כאשר משתמשים נמצאים במצב לא מקוון לפרקי זמן ארוכים.

כשמטמון מתמשך מופעל, אתה יכול לשפר את הביצועים של שאילתות לא מקוונות על ידי מתן אפשרות ל-SDK ליצור אינדקסים מקומיים של שאילתות באופן אוטומטי.

הוספה לאינדקס אוטומטית מושבתת כברירת מחדל. האפליקציה שלך חייבת להפעיל אינדקס אוטומטי בכל פעם שהיא מתחילה. קבע אם הוספה לאינדקס אוטומטית מופעלת כפי שמוצג להלן.

מָהִיר
if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
    
Objective-C
PersistentCacheIndexManager *indexManager = [FIRFirestore firestore].persistentCacheIndexManager;
if (indexManager) {
  // Indexing is disabled by default
  [indexManager enableIndexAutoCreation];
}
    

Kotlin+KTX

// return type: PersistentCacheManager?

Firebase.firestore.persistentCacheIndexManager?.apply {
      // Indexing is disabled by default
      enableIndexAutoCreation()
    } ?: println("indexManager is null")
    

Java

// 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 שלך. בזמן שהגישה לרשת מושבתת, כל מאזיני תמונת המצב ובקשות המסמכים מאחזרות תוצאות מהמטמון. פעולות הכתיבה עומדות בתור עד להפעלת הגישה לרשת מחדש.

Web modular API

import { disableNetwork } from "firebase/firestore"; 

await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...

Web namespaced API

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];

Kotlin+KTX

db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}

Java

db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });

Dart

db.disableNetwork().then((_) {
  // Do offline things
});

השתמש בשיטה הבאה כדי להפעיל מחדש את הגישה לרשת:

Web modular API

import { enableNetwork } from "firebase/firestore"; 

await enableNetwork(db);
// Do online actions
// ...

Web namespaced API

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];

Kotlin+KTX

db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}

Java

db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });

Dart

db.enableNetwork().then((_) {
  // Back online
});