Truy cập dữ liệu khi không có mạng

Cloud Firestore hỗ trợ tính năng lưu giữ dữ liệu ngoại tuyến. Tính năng này lưu vào bộ nhớ đệm một bản sao dữ liệu Cloud Firestore mà ứng dụng của bạn đang sử dụng tích cực, nhờ đó, ứng dụng có thể truy cập vào dữ liệu khi thiết bị ở chế độ ngoại tuyến. Bạn có thể ghi, đọc, nghe và truy vấn dữ liệu đã lưu vào bộ nhớ đệm.

Khi thiết bị kết nối lại với mạng, Cloud Firestore sẽ đồng bộ hoá mọi thay đổi cục bộ do ứng dụng của bạn thực hiện với phần phụ trợ Cloud Firestore. Đối với nhiều thay đổi đối với cùng một tài liệu, lần ghi cuối cùng sẽ được áp dụng.

Để sử dụng tính năng lưu giữ ngoại tuyến, bạn không cần thực hiện bất kỳ thay đổi nào đối với mã mà bạn dùng để truy cập vào dữ liệu Cloud Firestore. Khi tính năng lưu giữ ngoại tuyến được bật, thư viện ứng dụng Cloud Firestore sẽ tự động quản lý quyền truy cập dữ liệu trực tuyến và ngoại tuyến, đồng thời đồng bộ hoá dữ liệu cục bộ khi thiết bị kết nối lại với mạng.

Định cấu hình tính năng lưu giữ ngoại tuyến

Khi khởi chạy Cloud Firestore, bạn có thể bật hoặc tắt tính năng lưu giữ ngoại tuyến:

  • Đối với nền tảng Android và Apple, tính năng lưu giữ ngoại tuyến được bật theo mặc định. Để tắt tính năng lưu giữ, hãy đặt tuỳ chọn PersistenceEnabled thành false.
  • Đối với web, tính năng lưu giữ ngoại tuyến bị tắt theo mặc định. Để bật tính năng lưu giữ, hãy gọi phương thức enablePersistence. Bộ nhớ đệm của Cloud Firestore không tự động xoá giữa các phiên. Do đó, nếu ứng dụng web của bạn xử lý thông tin nhạy cảm, hãy nhớ hỏi người dùng xem họ có đang sử dụng một thiết bị đáng tin cậy hay không trước khi bật tính năng lưu giữ.

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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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

Định cấu hình kích thước bộ nhớ đệm

Khi tính năng lưu giữ được bật, Cloud Firestore sẽ lưu vào bộ nhớ đệm mọi tài liệu nhận được từ phần phụ trợ để truy cập ngoại tuyến. Cloud Firestore đặt một ngưỡng mặc định cho kích thước bộ nhớ đệm. Sau khi vượt quá ngưỡng mặc định, Cloud Firestore định kỳ cố gắng dọn dẹp các tài liệu cũ hơn, không được sử dụng. Bạn có thể định cấu hình một ngưỡng kích thước bộ nhớ đệm khác hoặc tắt hoàn toàn quy trình dọn dẹp:

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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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

Nghe dữ liệu ngoại tuyến

Khi thiết bị ở chế độ ngoại tuyến, nếu bạn đã bật tính năng lưu giữ ngoại tuyến, thì trình nghe sẽ nhận được các sự kiện nghe khi dữ liệu được lưu vào bộ nhớ đệm cục bộ thay đổi. Bạn có thể nghe tài liệu, bộ sưu tập và truy vấn.

Để kiểm tra xem bạn có đang nhận dữ liệu từ máy chủ hay bộ nhớ đệm hay không, hãy sử dụng thuộc tính fromCache trên SnapshotMetadata trong sự kiện ảnh chụp nhanh. Nếu fromCache là true, thì dữ liệu đó đến từ bộ nhớ đệm và có thể đã lỗi thời hoặc không đầy đủ. Nếu fromCache là false, thì dữ liệu đó đầy đủ và hiện tại với các bản cập nhật mới nhất trên máy chủ.

Theo mặc định, không có sự kiện nào được tạo nếu chỉ SnapshotMetadata thay đổi. Nếu bạn dựa vào các giá trị fromCache, hãy chỉ định tuỳ chọn nghe includeMetadataChanges khi bạn đính kèm trình xử lý nghe.

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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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

Lấy dữ liệu ngoại tuyến

Nếu bạn lấy một tài liệu khi thiết bị ở chế độ ngoại tuyến, Cloud Firestore trả về dữ liệu từ bộ nhớ đệm.

Khi truy vấn một bộ sưu tập, kết quả trống sẽ được trả về nếu không có tài liệu nào được lưu vào bộ nhớ đệm. Khi tìm nạp một tài liệu cụ thể, một lỗi sẽ được trả về.

Truy vấn dữ liệu ngoại tuyến

Tính năng truy vấn hoạt động với tính năng lưu giữ ngoại tuyến. Bạn có thể truy xuất kết quả của các truy vấn bằng cách lấy trực tiếp hoặc bằng cách nghe, như mô tả trong các phần trước. Bạn cũng có thể tạo các truy vấn mới trên dữ liệu được lưu giữ cục bộ khi thiết bị ở chế độ ngoại tuyến, nhưng ban đầu, các truy vấn sẽ chỉ chạy trên các tài liệu được lưu vào bộ nhớ đệm.

Định cấu hình chỉ mục truy vấn ngoại tuyến

Theo mặc định, SDK Firestore sẽ quét tất cả tài liệu trong một bộ sưu tập trong bộ nhớ đệm cục bộ khi thực thi các truy vấn ngoại tuyến. Với hành vi mặc định này, hiệu suất truy vấn ngoại tuyến có thể bị ảnh hưởng khi người dùng ở chế độ ngoại tuyến trong thời gian dài.

Khi bật bộ nhớ đệm liên tục, bạn có thể cải thiện hiệu suất của các truy vấn ngoại tuyến bằng cách cho phép SDK tự động tạo chỉ mục truy vấn cục bộ.

Tính năng lập chỉ mục tự động bị tắt theo mặc định. Ứng dụng của bạn phải bật tính năng lập chỉ mục tự động mỗi khi khởi động. Kiểm soát xem tính năng lập chỉ mục tự động có được bật hay không như minh hoạ bên dưới.

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

Sau khi bật tính năng lập chỉ mục tự động, SDK sẽ đánh giá những bộ sưu tập có số lượng lớn tài liệu được lưu vào bộ nhớ đệm và tối ưu hoá hiệu suất của các truy vấn cục bộ.

SDK cung cấp một phương thức để xoá chỉ mục truy vấn.

Tắt và bật quyền truy cập mạng

Bạn có thể sử dụng phương thức bên dưới để tắt quyền truy cập mạng cho ứng dụng Cloud Firestore của bạn. Khi quyền truy cập mạng bị tắt, tất cả trình nghe ảnh chụp nhanh và yêu cầu tài liệu sẽ truy xuất kết quả từ bộ nhớ đệm. Các thao tác ghi được xếp hàng đợi cho đến khi quyền truy cập mạng được bật lại.

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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và App Clip. 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Objective-C
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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

Sử dụng phương thức sau để bật lại quyền truy cập mạng:

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
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và App Clip. 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Objective-C
Lưu ý: Sản phẩm này không hoạt động trên các mục tiêu watchOS và 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