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

Cloud Firestore hỗ trợ việc lưu trữ cố định dữ liệu khi không có mạng. Tính năng này lưu vào bộ nhớ đệm một bản sao của dữ liệu Cloud Firestore mà ứng dụng của bạn đang sử dụng, nhờ đó, ứng dụng có thể truy cập vào dữ liệu đó khi thiết bị không có kết nối mạng. Bạn có thể ghi, đọc, nghe và truy vấn dữ liệu được lưu vào bộ nhớ đệm. Khi thiết bị kết nối mạng trở lại, Cloud Firestore sẽ đồng bộ hoá mọi thay đổi cục bộ mà ứng dụng của bạn thực hiện với phần phụ trợ Cloud Firestore.

Để sử dụng tính năng lưu trữ liên tục ngoại tuyến, bạn không cần thay đổi gì đối với mã mà bạn sử dụng để truy cập dữ liệu Cloud Firestore. Khi bật tính năng lưu trữ cố định ngoại tuyến, 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ị có kết nối mạng trở lại.

Định cấu hình tính năng lưu trữ liên tục khi không có mạng

Khi khởi chạy Cloud Firestore, bạn có thể bật hoặc tắt tính năng lưu trữ liên tục khi không có mạng:

  • Đối với các nền tảng Android và Apple, tính năng lưu trữ liên tục khi không có mạng được bật theo mặc định. Để tắt tính năng lưu trữ cố định, hãy đặt tuỳ chọn PersistenceEnabled thành false.
  • Đối với web, chế độ lưu trữ cố định khi không có mạng theo mặc định sẽ bị tắt. Để bật tính năng lưu trữ, hãy gọi phương thức enablePersistence. Bộ nhớ đệm của Cloud Firestore không tự động bị 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 thiết bị đáng tin cậy hay không trước khi bật tính năng lưu trữ liên tục.

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 dùng được 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 dùng được 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+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

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

Khi bật tính năng lưu trữ cố định, Cloud Firestore sẽ lưu mọi tài liệu nhận được từ phần phụ trợ vào bộ nhớ đệm để truy cập khi không có mạng. Cloud Firestore đặt ngưỡng mặc định cho kích thước bộ nhớ đệm. Sau khi vượt quá giá trị mặc định, Cloud Firestore sẽ định kỳ cố gắng dọn dẹp các tài liệu cũ không dùng đến. 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 dùng được 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 dùng được 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+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

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

Khi thiết bị không có mạng, nếu bạn đã bật tính năng lưu trữ liên tục khi không có mạng, 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, tuyển tập và truy vấn.

Để kiểm tra xem bạn có nhận được 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 tổng quan 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 hoàn chỉnh. Nếu fromCache là false, thì dữ liệu đã hoàn chỉnh và mới nhất 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 kích hoạt 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 đí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 dùng được 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 dùng được 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+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

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

Nếu bạn nhận được một tài liệu khi thiết bị không có kết nối mạng, Cloud Firestore sẽ trả về dữ liệu từ bộ nhớ đệm.

Khi truy vấn một tập hợ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ể, hệ thống sẽ trả về lỗi.

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 định 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 trữ cục bộ khi thiết bị không có kết nối mạng, nhưng ban đầu các truy vấn sẽ chỉ chạy dựa trên các tài liệu đã 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 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 cố định, 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 tự động lập chỉ mục bị tắt theo mặc định. Ứng dụng của bạn phải bật tính năng tự động lập chỉ mục 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+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();

Sau khi bạn bật tính năng lập chỉ mục tự động, SDK sẽ đánh giá xem bộ sưu tập nào có nhiều 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 dưới đây để tắt quyền truy cập mạng cho ứng dụng Cloud Firestore. 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 sẽ được đưa vào hàng đợi cho đến khi quyền truy cập mạng được kích hoạ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 dùng được 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 dùng được trên các mục tiêu watchOS và 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

Hãy 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 dùng được 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 dùng được trên các mục tiêu watchOS và 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