Dostęp do danych offline

Cloud Firestore obsługuje trwałość danych offline. Ta funkcja umieszcza w pamięci podręcznej kopię danych Cloud Firestore, z których aplikacja aktywnie korzysta, dzięki czemu może ona uzyskiwać dostęp do danych, gdy urządzenie jest offline. Możesz zapisywać, odczytywać, odsłuchiwać i wysyłać zapytania dotyczące danych w pamięci podręcznej.

Gdy urządzenie powróci do trybu online, Cloud Firestore zsynchronizuje wszelkie zmiany lokalne wprowadzone przez aplikację z Cloud Firestore backendem. W przypadku wielu zmian w tym samym dokumencie obowiązuje zasada „ostatni zapis wygrywa”.

Aby korzystać z trwałości offline, nie musisz wprowadzać żadnych zmian w kodzie, którego używasz do uzyskiwania dostępu do danych Cloud Firestore. Gdy trwałość offline jest włączona, biblioteka klienta Cloud Firestore automatycznie zarządza dostępem do danych online i offline oraz synchronizuje dane produktów dostępnych lokalnie, gdy urządzenie jest ponownie online.

Konfigurowanie trwałości offline

Podczas inicjowania Cloud Firestore możesz włączyć lub wyłączyć trwałość offline:

  • Na platformach Android i Apple trwałość offline jest domyślnie włączona. Aby wyłączyć trwałość, ustaw opcję PersistenceEnabled na false.
  • W przypadku aplikacji internetowych trwałość offline jest domyślnie wyłączona. Aby włączyć trwałość, wywołaj metodę enablePersistence. Pamięć podręczna Cloud Firestore nie jest automatycznie czyszczona między sesjami. Dlatego, jeśli Twoja aplikacja internetowa obsługuje informacje poufne, przed włączeniem trwałości zapytaj użytkownika, czy korzysta z zaufanego urządzenia.

Web

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

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
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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

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

Konfigurowanie rozmiaru pamięci podręcznej

Gdy trwałość jest włączona, Cloud Firestore umieszcza w pamięci podręcznej każdy dokument otrzymany z backendu, aby umożliwić dostęp offline. Cloud Firestore ustawia domyślny próg rozmiaru pamięci podręcznej. Po przekroczeniu wartości domyślnej, Cloud Firestore okresowo próbuje zwolnić miejsce, usuwając starsze, nieużywane dokumenty. Możesz skonfigurować inny próg rozmiaru pamięci podręcznej lub całkowicie wyłączyć proces czyszczenia:

Web

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

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

Web

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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


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

Odsłuchiwanie danych offline

Gdy urządzenie jest offline i masz włączoną trwałość offline, Twoi słuchacze będą otrzymywać zdarzenia odsłuchiwania, gdy zmienią się dane w pamięci podręcznej. Możesz odsłuchiwać dokumenty, kolekcje i zapytania.

Aby sprawdzić, czy otrzymujesz dane z serwera czy z pamięci podręcznej, użyj właściwości fromCache w SnapshotMetadata w zdarzeniu migawki. Jeśli fromCache ma wartość true, dane pochodzą z pamięci podręcznej i mogą być nieaktualne lub niekompletne. Jeśli fromCache ma wartość false, dane są kompletne i aktualne z najnowszymi aktualizacjami na serwerze.

Domyślnie nie jest wywoływane żadne zdarzenie, jeśli zmieni się tylko SnapshotMetadata. Jeśli korzystasz z wartości fromCache, podczas dołączania obsługi zdarzeń odsłuchiwania określ opcję odsłuchiwania includeMetadataChanges.

Web

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

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
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani 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

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

Pobieranie danych offline

Jeśli pobierzesz dokument, gdy urządzenie jest offline, Cloud Firestore zwróci dane z pamięci podręcznej.

Podczas wysyłania zapytań do kolekcji, jeśli nie ma dokumentów w pamięci podręcznej, zwracany jest pusty wynik. Podczas pobierania konkretnego dokumentu zwracany jest błąd.

Wysyłanie zapytań o dane offline

Wysyłanie zapytań działa z trwałością offline. Wyniki zapytań możesz pobierać bezpośrednio lub przez odsłuchiwanie, jak opisano w poprzednich sekcjach. Gdy urządzenie jest offline, możesz też tworzyć nowe zapytania dotyczące danych przechowywanych lokalnie, ale początkowo będą one wykonywane tylko w przypadku dokumentów w pamięci podręcznej.

Konfigurowanie indeksów zapytań offline

Domyślnie pakiet Firestore SDK skanuje wszystkie dokumenty w kolekcji w lokalnej pamięci podręcznej podczas wykonywania zapytań offline. W przypadku tego domyślnego zachowania wydajność zapytań offline może się pogorszyć, gdy użytkownicy są offline przez dłuższy czas.

Gdy włączona jest trwała pamięć podręczna, możesz zwiększyć wydajność zapytań offline, zezwalając pakietowi SDK na automatyczne tworzenie lokalnych indeksów zapytań.

Automatyczne indeksowanie jest domyślnie wyłączone. Aplikacja musi włączyć automatyczne indeksowanie przy każdym uruchomieniu. Sposób włączania automatycznego indeksowania pokazujemy poniżej.

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

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

Gdy automatyczne indeksowanie jest włączone, pakiet SDK sprawdza, które kolekcje mają dużą liczbę dokumentów w pamięci podręcznej, i optymalizuje wydajność zapytań lokalnych.

Pakiet SDK udostępnia metodę usuwania indeksów zapytań.

Wyłączanie i włączanie dostępu do sieci

Aby wyłączyć dostęp do sieci dla klienta Cloud Firestore, możesz użyć metody opisanej poniżej. Gdy dostęp do sieci jest wyłączony, wszystkie słuchacze migawek i żądania dokumentów pobierają wyniki z pamięci podręcznej. Operacje zapisu są umieszczane w kolejce do momentu ponownego włączenia dostępu do sieci.

Web

import { disableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani App Clip. 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Objective-C
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani App Clip. 
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin

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

Aby ponownie włączyć dostęp do sieci, użyj tej metody:

Web

import { enableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani App Clip. 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Objective-C
Uwaga: ten produkt nie jest dostępny w przypadku watchOS ani App Clip. 
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin

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