Questa pagina è stata tradotta dall'API Cloud Translation.

Accedi ai dati offline

Cloud Firestore supporta la persistenza dei dati offline. Questa funzione memorizza nella cache una copia dei dati di Cloud Firestore che la tua app sta utilizzando attivamente, in modo che la tua app possa accedere ai dati quando il dispositivo è offline. È possibile scrivere, leggere, ascoltare ed eseguire query sui dati memorizzati nella cache. Quando il dispositivo torna online, Cloud Firestore sincronizza tutte le modifiche locali apportate dalla tua app al back-end di Cloud Firestore.

Per utilizzare la persistenza offline, non è necessario apportare alcuna modifica al codice utilizzato per accedere ai dati di Cloud Firestore. Con la persistenza offline abilitata, la libreria client di Cloud Firestore gestisce automaticamente l'accesso ai dati online e offline e sincronizza i dati locali quando il dispositivo torna online.

Configura la persistenza offline

Quando inizializzi Cloud Firestore, puoi abilitare o disabilitare la persistenza offline:

Per le piattaforme Android e Apple, la persistenza offline è abilitata per impostazione predefinita. Per disabilitare la persistenza, imposta l'opzione PersistenceEnabled su false .
Per il Web, la persistenza offline è disabilitata per impostazione predefinita. Per abilitare la persistenza, chiama il metodo enablePersistence . La cache di Cloud Firestore non viene cancellata automaticamente tra le sessioni. Di conseguenza, se la tua app Web gestisce informazioni riservate, assicurati di chiedere all'utente se si trova su un dispositivo attendibile prima di abilitare la persistenza.

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

Rapido

Nota: questo prodotto non è disponibile sui target watchOS e 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 = settingsViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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 = settingsDocSnippets.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

Configura la dimensione della cache

Quando la persistenza è abilitata, Cloud Firestore memorizza nella cache ogni documento ricevuto dal back-end per l'accesso offline. Cloud Firestore imposta una soglia predefinita per le dimensioni della cache. Dopo aver superato il valore predefinito, Cloud Firestore tenta periodicamente di ripulire i documenti meno recenti e inutilizzati. È possibile configurare una soglia di dimensioni della cache diversa o disabilitare completamente il processo di pulizia:

Web modular API

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

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

Web namespaced API

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

Rapido

Nota: questo prodotto non è disponibile sui target watchOS e 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 = settingsViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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

Ascolta i dati offline

Mentre il dispositivo è offline, se hai abilitato la persistenza offline, i tuoi listener riceveranno eventi di ascolto quando i dati memorizzati nella cache locale cambiano. Puoi ascoltare documenti, raccolte e query.

Per verificare se stai ricevendo dati dal server o dalla cache, usa la proprietà fromCache su SnapshotMetadata nell'evento snapshot. Se fromCache è true , i dati provengono dalla cache e potrebbero essere obsoleti o incompleti. Se fromCache è false , i dati sono completi e aggiornati con gli ultimi aggiornamenti sul server.

Per impostazione predefinita, non viene generato alcun evento se sono stati modificati solo gli SnapshotMetadata . Se fai affidamento sui valori fromCache , specifica l'opzione di ascolto includeMetadataChanges quando colleghi il gestore di ascolto.

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

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

Rapido

Nota: questo prodotto non è disponibile sui target watchOS e 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

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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

Ottieni dati offline

Se ricevi un documento mentre il dispositivo è offline, Cloud Firestore restituisce i dati dalla cache.

Quando si esegue una query su una raccolta, viene restituito un risultato vuoto se non sono presenti documenti memorizzati nella cache. Quando si recupera un documento specifico, viene invece restituito un errore.

Interroga i dati offline

L'interrogazione funziona con la persistenza offline. È possibile recuperare i risultati delle query con un get diretto o mediante l'ascolto, come descritto nelle sezioni precedenti. Puoi anche creare nuove query sui dati persistenti in locale mentre il dispositivo è offline, ma le query verranno inizialmente eseguite solo sui documenti memorizzati nella cache.

Configura indici di query offline

Per impostazione predefinita, l'SDK di Firestore esegue la scansione di tutti i documenti in una raccolta nella sua cache locale durante l'esecuzione di query offline. Con questo comportamento predefinito, le prestazioni delle query offline possono risentirne quando gli utenti sono offline per lunghi periodi di tempo.

Puoi migliorare le prestazioni delle query offline configurando indici di query locali:

Rapido

L'SDK della piattaforma Apple fornisce un metodo setIndexConfiguration che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
let indexConfigJson = """
  {
    indexes: [
        ...
    ],
    fieldOverrides: [
        ...
    ]
  }
"""

// Apply the configuration.
Firestore.firestore().setIndexConfiguration(indexConfigJson)

Obiettivo-C

L'SDK della piattaforma Apple fornisce setIndexConfiguration , metodi che leggono la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
NSString *indexConfigJson = @" {                   "
                             "   indexes: [        "
                             "     ...             "
                             "   ],                "
                             "   fieldOverrides: [ "
                             "     ...             "
                             "   ]                 "
                             " }                   ";

// Apply the configuration.
[[FIRFirestore firestore] setIndexConfigurationFromJSON:indexConfigJson
                                             completion:^(NSError * _Nullable error) {
    // ...
}];

Java

Android SDK fornisce un metodo setIndexConfiguration che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
String indexConfigJson = " {                   "
                       + "   indexes: [        "
                       + "     ...             "
                       + "   ],                "
                       + "   fieldOverrides: [ "
                       + "     ...             "
                       + "   ]                 "
                       + " }                   ";
// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson);

Kotlin+KTX

// You will normally read this from a file asset or cloud storage.
val indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
"""

// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson)

Dart

Flutter SDK fornisce un metodo setIndexConfigurationFromJSON che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
var indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
""";

// Apply the configuration.
await FirebaseFirestore.instance.setIndexConfigurationFromJSON(json: indexConfigJson);

In alternativa, puoi utilizzare il metodo setIndexConfiguration per configurare gli indici con un'API basata su classi.

var indexes = [
  Index(
    collectionGroup: "posts",
    queryScope: QueryScope.collection,
    fields: [
      IndexField(fieldPath: "author", arrayConfig: ArrayConfig.contains),
      IndexField(fieldPath: "timestamp", order: Order.descending)
    ],
  ),
];
await FirebaseFirestore.instance.setIndexConfiguration(indexes: indexes);

La configurazione dell'indice offline da usare dipende dalle raccolte e dai documenti a cui la tua app accede in modo massiccio mentre è offline e dalle prestazioni offline desiderate. Anche se puoi esportare la configurazione dell'indice back-end per l'utilizzo sul client, i modelli di accesso offline della tua app probabilmente differiscono in modo significativo dai modelli di accesso online, pertanto la tua configurazione dell'indice online potrebbe non essere adatta per l'utilizzo offline. A quali raccolte e documenti vuoi che la tua app acceda offline con prestazioni elevate? Dopo aver analizzato il comportamento della tua app, segui i principi per la definizione dell'indice dalla guida all'indicizzazione .

Per rendere le configurazioni dell'indice offline disponibili per il caricamento nell'app client:

compilali e distribuiscili con la tua app
scaricarli da un CDN
recuperali da un sistema di archiviazione come Cloud Storage for Firebase .

Disabilita e abilita l'accesso alla rete

Puoi utilizzare il metodo seguente per disabilitare l'accesso alla rete per il tuo client Cloud Firestore. Mentre l'accesso alla rete è disabilitato, tutti i listener di snapshot e le richieste di documenti recuperano i risultati dalla cache. Le operazioni di scrittura vengono messe in coda finché non viene riabilitato l'accesso alla rete.

Web modular API

import { disableNetwork } from "firebase/firestore"; 

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

Web namespaced API

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

Rapido

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

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

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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

Utilizzare il seguente metodo per riattivare l'accesso alla rete:

Web modular API

import { enableNetwork } from "firebase/firestore"; 

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

Web namespaced API

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

Rapido

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

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

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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