הפעלת נתונים ממקורות אופליין

הפעלת נתונים ממקורות אופליין

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

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

הערה:

• שמירה במצב אופליין נתמכת רק באפליקציות ל-Android, באפליקציות של Apple ובאפליקציות אינטרנט.
• פעולות בצינור לא תומכות בשימור אופליין. כדי להשתמש בנתונים שנשמרים אופליין עם מסדי נתונים של מהדורת Enterprise, צריך להשתמש בפעולות הליבה כמו שמתואר בדף הזה.

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

הגדרת שמירה במצב אופליין

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

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

חשוב: באינטרנט, שמירת נתונים במצב אופליין נתמכת רק בדפדפני האינטרנט Chrome,‏ Safari ו-Firefox.

גרסה 9 לאינטרנט

מידע נוסף על ה-SDK המודולרי לאינטרנט בגרסה 9, שאפשר להסיר ממנו קוד שלא בשימוש, ועל שדרוג מגרסה 8.

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

גרסה 8 לאינטרנט

מידע נוסף על ה-SDK המודולרי לאינטרנט בגרסה 9, שאפשר להסיר ממנו קוד שלא בשימוש, ועל שדרוג מגרסה 8.

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
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

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
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

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;
ViewController.m

‫Kotlin
Android

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

‫Java
Android

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);
DocSnippets.java

Dart

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

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

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

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

גרסה 9 לאינטרנט

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

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

גרסה 8 לאינטרנט

מידע נוסף על Web API מודולרי עם tree-shaking ועל היתרונות שלו בהשוואה ל-API עם מרחב שמות.

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

// 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
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

// 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;
ViewController.m
  

‫Kotlin
Android

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

// 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,
);
firestore.dart

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

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

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

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

גרסה 9 לאינטרנט

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);
    });
});
use_from_cache.js

גרסה 8 לאינטרנט

מידע נוסף על Web API מודולרי עם tree-shaking ועל היתרונות שלו בהשוואה ל-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);
      });
  });
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

// 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)")
  }
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

// 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);
    }];
ViewController.m

‫Kotlin
Android

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")
        }
    }
DocSnippets.kt

‫Java
Android

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

            }
        });
DocSnippets.java

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}");
    }
  }
});
firestore.dart

קבלת נתונים ממקורות אופליין

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

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

שליחת שאילתות לנתונים ממקורות אופליין

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

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

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

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

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

Swift

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
Android

// return type: PersistentCacheManager?

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

‫Java
Android

// 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 מספקת שיטה למחיקת אינדקסים של שאילתות.

השבתה והפעלה של גישה לרשת

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

גרסה 9 לאינטרנט

import { disableNetwork } from "firebase/firestore"; 

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

גרסה 8 לאינטרנט

מידע נוסף על Web API מודולרי עם tree-shaking ועל היתרונות שלו בהשוואה ל-API עם מרחב שמות.

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

‫Kotlin
Android

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

‫Java
Android

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

Dart

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

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

גרסה 9 לאינטרנט

import { enableNetwork } from "firebase/firestore"; 

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

גרסה 8 לאינטרנט

מידע נוסף על Web API מודולרי עם tree-shaking ועל היתרונות שלו בהשוואה ל-API עם מרחב שמות.

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ב-watchOS ובמטרות של קליפים של אפליקציות.

[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

‫Kotlin
Android

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

‫Java
Android

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

Dart

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