Cloud Firestore 資料包是您根據 Cloud Firestore 文件和查詢快照建立的靜態資料文件，並由您在 CDN、託管服務或其他解決方案上發布。資料包包括您想要提供給客戶端應用程式的文件以及有關產生它們的查詢的元資料。您可以使用用戶端 SDK 透過網路或本機儲存下載捆綁包，然後將捆綁包資料載入至 Cloud Firestore 本機快取。載入套件後，客戶端應用程式可以從本機快取或後端查詢文件。
透過資料包，您的應用程式可以更快地載入常見查詢的結果，因為文件在啟動時即可使用，而無需呼叫 Cloud Firestore 後端。如果從本機快取載入結果，您也可以從降低的存取成本中受益。您無需為查詢相同的初始 100 個文件而支付一百萬個應用程式實例的費用，只需為捆綁這 100 個文件所需的查詢付費。
Cloud Firestore 資料包旨在與其他 Firebase 後端產品良好配合。請看一下整合解決方案，其中捆綁包由 Cloud Functions 建置並透過 Firebase Hosting 提供給使用者。
將捆綁包與您的應用程式一起使用涉及三個步驟：
- 使用 Admin SDK 建置捆綁包
- 從本地儲存或 CDN 提供捆綁包
- 在客戶端載入套件
什麼是資料包？
資料包是一種靜態二進位文件，由您構建，用於打包一個或多個文件和/或查詢快照，您可以從中提取命名查詢。正如我們下面討論的，伺服器端 SDK 允許您建立捆綁包，而客戶端 SDK 提供了讓您將捆綁包載入到本機快取的方法。
命名查詢是捆綁包的一個特別強大的功能。命名查詢是您可以從捆綁包中提取的Query對象，然後立即使用它從快取或後端查詢數據，就像您在應用程式中與 Cloud Firestore 通訊的任何部分中通常執行的操作一樣。
在伺服器上建立資料包
使用 Node.js 或 Java Admin SDK可以讓您完全控制捆綁包中包含的內容以及如何提供它們。
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()
爪哇
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 向客戶端應用程式提供捆綁包，或從 Cloud Storage 等下載它們。
假設上一節中建立的套件已儲存到名為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 的狀態一樣監視該物件的完成情況。成功完成捆綁包載入任務後，捆綁包內容將在本機快取中可用。
Web modular API
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 namespaced API
// 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
}
}
}
}Objective-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 分鐘之前建立的套件中載入命名查詢，一旦您使用它從後端而不是快取讀取，您只需為更新文件以匹配後端儲存的內容所需的資料庫讀取取付費;也就是說，您只需支付增量費用。