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

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

הערה: תמיכה בשמירה אופליין קיימת רק באפליקציות ל-Android, ל-Apple ולאינטרנט.

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

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

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

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

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

Web

מידע נוסף על ה-SDK המודולרי של Web v9 שאפשר לנקות ממנו קוד מיותר ושדרוג מגרסה 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()})
  });
  

Web

מידע נוסף על ה-SDK המודולרי של Web v9 שאפשר לנקות ממנו קוד מיותר ושדרוג מגרסה 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 ו-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
ViewController.swift

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

Kotlin+KTX

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

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

Dart

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

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

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API במרחב שמות

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

Swift

הערה: המוצר הזה לא זמין ליעדים של 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
ViewController.swift

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

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

האזנה לנתונים אופליין

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

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-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);
    });
});
use_from_cache.js

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-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 ו-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)")
  }
ViewController.swift

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

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

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

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

אחזור נתונים אופליין

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

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

שליחת שאילתות לנתונים אופליין

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

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

import { disableNetwork } from "firebase/firestore"; 

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

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

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

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

Objective-C

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

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

Kotlin+KTX

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

Java

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

import { enableNetwork } from "firebase/firestore"; 

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

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

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

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

Objective-C

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

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

Kotlin+KTX

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

Java

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