Cloud Firestore 數據包是您根據 Cloud Firestore 文檔和查詢快照構建並發佈在 CDN、託管服務或其他解決方案上的靜態數據文件。數據包包括您要提供給客戶端應用程序的文檔以及有關生成它們的查詢的元數據。您使用客戶端 SDK 通過網絡或從本地存儲下載捆綁包，然後將捆綁包數據加載到 Cloud Firestore 本地緩存。加載包後，客戶端應用程序可以從本地緩存或後端查詢文檔。
借助數據包，您的應用可以更快地加載常見查詢的結果，因為文檔在啟動時可用，無需調用 Cloud Firestore 後端。如果從本地緩存加載結果，您還可以降低訪問成本。您無需支付一百萬個應用程序實例來查詢相同的初始 100 個文檔，您只需為捆綁這 100 個文檔所需的查詢付費。
Cloud Firestore 數據包旨在與其他 Firebase 後端產品配合使用。查看一個集成解決方案，其中捆綁包由 Cloud Functions 構建並通過 Firebase 託管服務於用戶。
在您的應用程序中使用捆綁包涉及三個步驟：
- 使用 Admin SDK 構建捆綁包
- 從本地存儲或 CDN 提供捆綁包
- 在客戶端加載包
什麼是數據包？
數據包是您構建的靜態二進製文件，用於打包一個或多個文檔和/或查詢快照，您可以從中提取命名查詢。正如我們在下面討論的，服務器端 SDK 讓您構建捆綁包，而客戶端 SDK 提供讓您將捆綁包加載到本地緩存的方法。
命名查詢是 bundle 的一個特別強大的特性。命名查詢是您可以從捆綁包中提取的Query對象，然後立即用於從緩存或後端查詢數據，就像您通常在與 Cloud Firestore 對話的應用程序的任何部分中所做的那樣。
在服務器上構建數據包
使用 Node.js 或 Java Admin SDK可以讓您完全控制要包含在捆綁包中的內容以及如何為它們提供服務。
節點.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()
爪哇
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()
服務數據包
您可以從 CDN 或通過從雲存儲等平台下載它們來為您的客戶端應用程序提供捆綁包。
假設在上一節中創建的包已保存到名為bundle.txt的文件中並發佈到服務器上。這個捆綁文件就像您可以通過網絡提供的任何其他資產一樣，如這裡所示的一個簡單的 Node.js Express 應用程序。
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);
在客戶端加載數據包
您可以通過從遠程服務器獲取 Firestore 包來加載它們，無論是通過發出 HTTP 請求、調用存儲 API 還是使用任何其他技術在網絡上獲取二進製文件。
獲取後，您的應用會使用 Cloud Firestore 客戶端 SDK 調用loadBundle方法，該方法會返回一個任務跟踪對象，您可以像監控 Promise 的狀態一樣監控該對象的完成情況。捆綁包加載任務成功完成後，捆綁包內容將在本地緩存中可用。
網絡
// 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
// ...
}迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
// Utility function for errors when loading bundles.
func bundleLoadError(reason: String) -> NSError {
return NSError(domain: "FIRSampleErrorDomain",
code: 0,
userInfo: [NSLocalizedFailureReasonErrorKey: reason])
}
// Loads a remote bundle from the provided url.
func fetchRemoteBundle(for firestore: Firestore,
from url: URL,
completion: @escaping ((Result<LoadBundleTaskProgress, Error>) -> ())) {
guard let inputStream = InputStream(url: url) else {
let error = self.bundleLoadError(reason: "Unable to create stream from the given url: \(url)")
completion(.failure(error))
return
}
// The return value of this function is ignored, but can be used for more granular
// bundle load observation.
let _ = firestore.loadBundle(inputStream) { (progress, error) in
switch (progress, error) {
case (.some(let value), .none):
if value.state == .success {
completion(.success(value))
} else {
let concreteError = self.bundleLoadError(
reason: "Expected bundle load to be completed, but got \(value.state) instead"
)
completion(.failure(concreteError))
}
case (.none, .some(let concreteError)):
completion(.failure(concreteError))
case (.none, .none):
let concreteError = self.bundleLoadError(reason: "Operation failed, but returned no error.")
completion(.failure(concreteError))
case (.some(let value), .some(let concreteError)):
let concreteError = self.bundleLoadError(
reason: "Operation returned error \(concreteError) with nonnull progress: \(value)"
)
completion(.failure(concreteError))
}
}
}
// Fetches a specific named query from the provided bundle.
func loadQuery(named queryName: String,
fromRemoteBundle bundleURL: URL,
with store: Firestore,
completion: @escaping ((Result<Query, Error>) -> ())) {
fetchRemoteBundle(for: store,
from: bundleURL) { (result) in
switch result {
case .success:
store.getQuery(named: queryName) { query in
if let query = query {
completion(.success(query))
} else {
completion(
.failure(
self.bundleLoadError(reason: "Could not find query named \(queryName)")
)
)
}
}
case .failure(let error):
completion(.failure(error))
}
}
}
// Load a query and fetch its results from a bundle.
func runStoriesQuery() {
let queryName = "latest-stories-query"
let firestore = Firestore.firestore()
let remoteBundle = URL(string: "https://example.com/createBundle")!
loadQuery(named: queryName,
fromRemoteBundle: remoteBundle,
with: firestore) { (result) in
switch result {
case .failure(let error):
print(error)
case .success(let query):
query.getDocuments { (snapshot, error) in
// handle query results
}
}
}
}目標-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
// 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
// ...
}
});
}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> &){
// ...
});
});
});請注意，如果您從不到 30 分鐘之前構建的捆綁包中加載命名查詢，一旦您使用它從後端讀取而不是緩存，您只需為更新文檔以匹配後端存儲的內容所需的數據庫讀取付費;也就是說，您只需為增量付費。
接下來是什麼？
請參閱客戶端（ Apple 、 Android 、 Web ）和服務器端（ Node.js ）的數據包 API 參考文檔。
如果您還沒有，請查看Cloud Functions and Firebase Hosting solution for building and serving bundles 。