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

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

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

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

הערה:

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

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

כדי להשתמש בשמירת נתונים במצב אופליין, צריך לשלב את Firebase בפיתוח של אפליקציות לנייד ולאינטרנט. ספריות הלקוח של Firestore בצד השרת ל-C#‎,‏ Go,‏ Java,‏ Node.js,‏ PHP,‏ Python ו-Ruby לא תומכות בשמירת נתונים במצב אופליין. אם הארגון שלכם לא מאשר להשתמש ב-Firebase, אתם יכולים להשתמש בספריות הלקוח האלה בצד השרת כדי להימנע מתלות ב-Firebase.

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

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

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

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

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

מידע נוסף על ה-SDK המודולרי של Web v9 עם תמיכה ב-tree-shaking ושדרוג מגרסה 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 המודולרי של Web v9 עם תמיכה ב-tree-shaking ושדרוג מגרסה 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
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 שומר במטמון כל מסמך שמתקבל מה-backend כדי לאפשר גישה אופליין. ב-Firestore מוגדר סף ברירת מחדל לגודל המטמון. אם חורגים ממגבלת ברירת המחדל, Firestore מנסה מדי פעם לנקות מסמכים ישנים יותר שלא בשימוש. אפשר להגדיר סף אחר לגודל המטמון או להשבית את תהליך הניקוי לגמרי:

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

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

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

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

מידע נוסף על Tree-shakeable Modular Web API והיתרונות שלו על פני Namespaced 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
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 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 לאינטרנט

מידע נוסף על Tree-shakeable Modular Web API והיתרונות שלו על פני 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);
      });
  });
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
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 מחזיר נתונים מהמטמון.

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

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

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

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

כברירת מחדל, כשמריצים שאילתות אופליין, ה-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 לאינטרנט

מידע נוסף על Tree-shakeable Modular Web API והיתרונות שלו על פני Namespaced 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
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 לאינטרנט

מידע נוסף על Tree-shakeable Modular Web API והיתרונות שלו על פני Namespaced 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
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