Gói dữ liệu Cloud Firestore là các tệp dữ liệu tĩnh do bạn tạo từ bản lưu toàn cảnh truy vấn và tài liệu Cloud Firestore, đồng thời do bạn phát hành trên CDN, dịch vụ lưu trữ hoặc giải pháp khác. Gói dữ liệu bao gồm cả tài liệu bạn muốn cung cấp cho ứng dụng khách và siêu dữ liệu về các truy vấn đã tạo ra tài liệu đó. Bạn sử dụng SDK ứng dụng để tải các gói xuống qua mạng hoặc từ bộ nhớ cục bộ, sau đó tải dữ liệu gói vào bộ nhớ đệm cục bộ Cloud Firestore. Sau khi tải một gói, ứng dụng khách có thể truy vấn tài liệu từ bộ nhớ đệm cục bộ hoặc phần phụ trợ.
Với gói dữ liệu, ứng dụng của bạn có thể tải kết quả của các truy vấn phổ biến sớm hơn, vì tài liệu có sẵn khi khởi động mà không cần gọi đến phần phụ trợ Cloud Firestore. Nếu kết quả được tải từ bộ nhớ đệm cục bộ, bạn cũng sẽ được hưởng lợi từ việc giảm chi phí truy cập. Thay vì trả phí cho một triệu phiên bản ứng dụng để truy vấn cùng 100 tài liệu ban đầu, bạn chỉ trả phí cho các truy vấn cần thiết để gói 100 tài liệu đó.
Gói dữ liệu Cloud Firestore được xây dựng để hoạt động hiệu quả với các sản phẩm phụ trợ khác của Firebase. Hãy xem một giải pháp tích hợp trong đó các gói được tạo bằng Cloud Functions và phân phát cho người dùng bằng Firebase Hosting.
Quy trình sử dụng gói với ứng dụng bao gồm 3 bước:
- Tạo gói bằng SDK dành cho quản trị viên
- Phân phát gói từ bộ nhớ cục bộ hoặc từ CDN
- Tải gói trong ứng dụng
Gói dữ liệu là gì?
Gói dữ liệu là một tệp nhị phân tĩnh do bạn tạo để đóng gói một hoặc nhiều tệp tổng quan về tài liệu và/hoặc truy vấn, từ đó bạn có thể trích xuất truy vấn được đặt tên. Như chúng ta thảo luận bên dưới, SDK phía máy chủ cho phép bạn tạo gói và SDK ứng dụng cung cấp các phương thức để bạn tải gói vào bộ nhớ đệm cục bộ.
Truy vấn được đặt tên là một tính năng đặc biệt mạnh mẽ của gói. Truy vấn được đặt tên là các đối tượng Query mà bạn có thể trích xuất từ một gói, sau đó sử dụng ngay để truy vấn dữ liệu từ bộ nhớ đệm hoặc từ phần phụ trợ, như bạn thường làm trong bất kỳ phần nào của ứng dụng giao tiếp với Cloud Firestore.
Tạo gói dữ liệu trên máy chủ
Việc sử dụng SDK dành cho quản trị viên Node.js hoặc Java giúp bạn có toàn quyền kiểm soát nội dung cần đưa vào gói và cách phân phát các gói đó.
Node.js
var bundleId = "latest-stories";
var bundle = firestore.bundle(bundleId);
var docSnapshot = await firestore.doc('stories/stories').get();
var querySnapshot = await firestore.collection('stories').get();
// Build the bundle
// Note how querySnapshot is named "latest-stories-query"
var bundleBuffer = bundle.add(docSnapshot); // Add a document
.add('latest-stories-query', querySnapshot) // Add a named query.
.build()
Java
Firestore db = FirestoreClient.getFirestore(app);
// Query the 50 latest stories
QuerySnapshot latestStories = db.collection("stories")
.orderBy("timestamp", Direction.DESCENDING)
.limit(50)
.get()
.get();
// Build the bundle from the query results
FirestoreBundle bundle = db.bundleBuilder("latest-stories")
.add("latest-stories-query", latestStories)
.build();
Python
from google.cloud import firestore
from google.cloud.firestore_bundle import FirestoreBundle
db = firestore.Client()
bundle = FirestoreBundle("latest-stories")
doc_snapshot = db.collection("stories").document("news-item").get()
query = db.collection("stories")._query()
# Build the bundle
# Note how `query` is named "latest-stories-query"
bundle_buffer: str = bundle.add_document(doc_snapshot).add_named_query(
"latest-stories-query", query,
).build()
Phân phát gói dữ liệu
Bạn có thể phân phát gói cho ứng dụng khách từ CDN hoặc bằng cách tải xuống từ, ví dụ: Cloud Storage.
Giả sử gói được tạo trong phần trước đã được lưu vào một tệp có tên bundle.txt và được đăng trên máy chủ. Tệp gói này giống như mọi tài sản khác mà bạn có thể phân phát trên web, như minh hoạ ở đây cho một ứng dụng Express Node.js đơn giản.
const fs = require('fs');
const server = require('http').createServer();
server.on('request', (req, res) => {
const src = fs.createReadStream('./bundle.txt');
src.pipe(res);
});
server.listen(8000);
Tải gói dữ liệu trong ứng dụng
Bạn tải các gói Firestore bằng cách tìm nạp các gói đó từ một máy chủ từ xa, cho dù đó là bằng cách tạo một yêu cầu HTTP, gọi một API bộ nhớ hay sử dụng bất kỳ kỹ thuật nào khác để tìm nạp tệp nhị phân trên mạng.
Sau khi tìm nạp, bằng cách sử dụng SDK ứng dụng Cloud Firestore, ứng dụng của bạn sẽ gọi phương thức loadBundle. Phương thức này sẽ trả về một đối tượng theo dõi tác vụ, bạn có thể theo dõi quá trình hoàn thành tác vụ này giống như theo dõi trạng thái của một Lời hứa.
Khi hoàn tất tác vụ tải gói thành công, nội dung gói sẽ có trong bộ nhớ đệm cục bộ.
Web
import { loadBundle, namedQuery, getDocsFromCache } from "firebase/firestore";
async function fetchFromBundle() {
// Fetch the bundle from Firebase Hosting, if the CDN cache is hit the 'X-Cache'
// response header will be set to 'HIT'
const resp = await fetch('/createBundle');
// Load the bundle contents into the Firestore SDK
await loadBundle(db, resp.body);
// Query the results from the cache
const query = await namedQuery(db, 'latest-stories-query');
const storiesSnap = await getDocsFromCache(query);
// Use the results
// ...
}
Web
// If you are using module bundlers.
import firebase from "firebase/app";
import "firebase/firestore";
import "firebase/firestore/bundle"; // This line enables bundle loading as a side effect.
// ...
async function fetchFromBundle() {
// Fetch the bundle from Firebase Hosting, if the CDN cache is hit the 'X-Cache'
// response header will be set to 'HIT'
const resp = await fetch('/createBundle');
// Load the bundle contents into the Firestore SDK
await db.loadBundle(resp.body);
// Query the results from the cache
// Note: omitting "source: cache" will query the Firestore backend.
const query = await db.namedQuery('latest-stories-query');
const storiesSnap = await query.get({ source: 'cache' });
// Use the results
// ...
}
Swift
// Utility function for errors when loading bundles.
func bundleLoadError(reason: String) -> NSError {
return NSError(domain: "FIRSampleErrorDomain",
code: 0,
userInfo: [NSLocalizedFailureReasonErrorKey: reason])
}
func fetchRemoteBundle(for firestore: Firestore,
from url: URL) async throws -> LoadBundleTaskProgress {
guard let inputStream = InputStream(url: url) else {
let error = self.bundleLoadError(reason: "Unable to create stream from the given url: \(url)")
throw error
}
return try await firestore.loadBundle(inputStream)
}
// Fetches a specific named query from the provided bundle.
func loadQuery(named queryName: String,
fromRemoteBundle bundleURL: URL,
with store: Firestore) async throws -> Query {
let _ = try await fetchRemoteBundle(for: store, from: bundleURL)
if let query = await store.getQuery(named: queryName) {
return query
} else {
throw bundleLoadError(reason: "Could not find query named \(queryName)")
}
}
// Load a query and fetch its results from a bundle.
func runStoriesQuery() async {
let queryName = "latest-stories-query"
let firestore = Firestore.firestore()
let remoteBundle = URL(string: "https://example.com/createBundle")!
do {
let query = try await loadQuery(named: queryName,
fromRemoteBundle: remoteBundle,
with: firestore)
let snapshot = try await query.getDocuments()
print(snapshot)
// handle query results
} catch {
print(error)
}
}
Objective-C
// Utility function for errors when loading bundles.
- (NSError *)bundleLoadErrorWithReason:(NSString *)reason {
return [NSError errorWithDomain:@"FIRSampleErrorDomain"
code:0
userInfo:@{NSLocalizedFailureReasonErrorKey: reason}];
}
// Loads a remote bundle from the provided url.
- (void)fetchRemoteBundleForFirestore:(FIRFirestore *)firestore
fromURL:(NSURL *)url
completion:(void (^)(FIRLoadBundleTaskProgress *_Nullable,
NSError *_Nullable))completion {
NSInputStream *inputStream = [NSInputStream inputStreamWithURL:url];
if (inputStream == nil) {
// Unable to create input stream.
NSError *error =
[self bundleLoadErrorWithReason:
[NSString stringWithFormat:@"Unable to create stream from the given url: %@", url]];
completion(nil, error);
return;
}
[firestore loadBundleStream:inputStream
completion:^(FIRLoadBundleTaskProgress * _Nullable progress,
NSError * _Nullable error) {
if (progress == nil) {
completion(nil, error);
return;
}
if (progress.state == FIRLoadBundleTaskStateSuccess) {
completion(progress, nil);
} else {
NSError *concreteError =
[self bundleLoadErrorWithReason:
[NSString stringWithFormat:
@"Expected bundle load to be completed, but got %ld instead",
(long)progress.state]];
completion(nil, concreteError);
}
completion(nil, nil);
}];
}
// Loads a bundled query.
- (void)loadQueryNamed:(NSString *)queryName
fromRemoteBundleURL:(NSURL *)url
withFirestore:(FIRFirestore *)firestore
completion:(void (^)(FIRQuery *_Nullable, NSError *_Nullable))completion {
[self fetchRemoteBundleForFirestore:firestore
fromURL:url
completion:^(FIRLoadBundleTaskProgress *progress, NSError *error) {
if (error != nil) {
completion(nil, error);
return;
}
[firestore getQueryNamed:queryName completion:^(FIRQuery *query) {
if (query == nil) {
NSString *errorReason =
[NSString stringWithFormat:@"Could not find query named %@", queryName];
NSError *error = [self bundleLoadErrorWithReason:errorReason];
completion(nil, error);
return;
}
completion(query, nil);
}];
}];
}
- (void)runStoriesQuery {
NSString *queryName = @"latest-stories-query";
FIRFirestore *firestore = [FIRFirestore firestore];
NSURL *bundleURL = [NSURL URLWithString:@"https://example.com/createBundle"];
[self loadQueryNamed:queryName
fromRemoteBundleURL:bundleURL
withFirestore:firestore
completion:^(FIRQuery *query, NSError *error) {
// Handle query results
}];
}
Kotlin+KTX
@Throws(IOException::class)
fun getBundleStream(urlString: String?): InputStream {
val url = URL(urlString)
val connection = url.openConnection() as HttpURLConnection
return connection.inputStream
}
@Throws(IOException::class)
fun fetchFromBundle() {
val bundleStream = getBundleStream("https://example.com/createBundle")
val loadTask = db.loadBundle(bundleStream)
// Chain the following tasks
// 1) Load the bundle
// 2) Get the named query from the local cache
// 3) Execute a get() on the named query
loadTask.continueWithTask<Query> { task ->
// Close the stream
bundleStream.close()
// Calling .result propagates errors
val progress = task.getResult(Exception::class.java)
// Get the named query from the bundle cache
db.getNamedQuery("latest-stories-query")
}.continueWithTask { task ->
val query = task.getResult(Exception::class.java)!!
// get() the query results from the cache
query.get(Source.CACHE)
}.addOnCompleteListener { task ->
if (!task.isSuccessful) {
Log.w(TAG, "Bundle loading failed", task.exception)
return@addOnCompleteListener
}
// Get the QuerySnapshot from the bundle
val storiesSnap = task.result
// Use the results
// ...
}
}
Java
public InputStream getBundleStream(String urlString) throws IOException {
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
return connection.getInputStream();
}
public void fetchBundleFrom() throws IOException {
final InputStream bundleStream = getBundleStream("https://example.com/createBundle");
LoadBundleTask loadTask = db.loadBundle(bundleStream);
// Chain the following tasks
// 1) Load the bundle
// 2) Get the named query from the local cache
// 3) Execute a get() on the named query
loadTask.continueWithTask(new Continuation<LoadBundleTaskProgress, Task<Query>>() {
@Override
public Task<Query> then(@NonNull Task<LoadBundleTaskProgress> task) throws Exception {
// Close the stream
bundleStream.close();
// Calling getResult() propagates errors
LoadBundleTaskProgress progress = task.getResult(Exception.class);
// Get the named query from the bundle cache
return db.getNamedQuery("latest-stories-query");
}
}).continueWithTask(new Continuation<Query, Task<QuerySnapshot>>() {
@Override
public Task<QuerySnapshot> then(@NonNull Task<Query> task) throws Exception {
Query query = task.getResult(Exception.class);
// get() the query results from the cache
return query.get(Source.CACHE);
}
}).addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
@Override
public void onComplete(@NonNull Task<QuerySnapshot> task) {
if (!task.isSuccessful()) {
Log.w(TAG, "Bundle loading failed", task.getException());
return;
}
// Get the QuerySnapshot from the bundle
QuerySnapshot storiesSnap = task.getResult();
// Use the results
// ...
}
});
}
Dart
// Get a bundle from a server
final url = Uri.https('example.com', '/create-bundle');
final response = await http.get(url);
String body = response.body;
final buffer = Uint8List.fromList(body.codeUnits);
// Load a bundle from a buffer
LoadBundleTask task = FirebaseFirestore.instance.loadBundle(buffer);
await task.stream.toList();
// Use the cached named query
final results = await FirebaseFirestore.instance.namedQueryGet(
"latest-stories-query",
options: const GetOptions(
source: Source.cache,
),
);
C++
db->LoadBundle("bundle_name", [](const LoadBundleTaskProgress& progress) {
switch(progress.state()) {
case LoadBundleTaskProgress::State::kError: {
// The bundle load has errored. Handle the error in the returned future.
return;
}
case LoadBundleTaskProgress::State::kInProgress: {
std::cout << "Bytes loaded from bundle: " << progress.bytes_loaded()
<< std::endl;
break;
}
case LoadBundleTaskProgress::State::kSuccess: {
std::cout << "Bundle load succeeeded" << std::endl;
break;
}
}
}).OnCompletion([db](const Future<LoadBundleTaskProgress>& future) {
if (future.error() != Error::kErrorOk) {
// Handle error...
return;
}
const std::string& query_name = "latest_stories_query";
db->NamedQuery(query_name).OnCompletion([](const Future<Query>& query_future){
if (query_future.error() != Error::kErrorOk) {
// Handle error...
return;
}
const Query* query = query_future.result();
query->Get().OnCompletion([](const Future<QuerySnapshot> &){
// ...
});
});
});
Xin lưu ý rằng nếu tải một truy vấn được đặt tên từ một gói được tạo chưa đến 30 phút trước, thì sau khi sử dụng truy vấn đó để đọc từ phần phụ trợ thay vì bộ nhớ đệm, bạn sẽ chỉ trả phí cho các lượt đọc cơ sở dữ liệu cần thiết để cập nhật tài liệu cho khớp với nội dung được lưu trữ trên phần phụ trợ; tức là bạn chỉ trả phí cho các delta.
Bước tiếp theo là gì?
Tham khảo tài liệu tham khảo API gói dữ liệu cho phía máy khách (Apple, Android, web) và phía máy chủ (Node.js).
Nếu bạn chưa xem, hãy xem giải pháp Cloud Functions và Firebase Hosting để tạo và phân phát gói.