Cloud Firestore-Datenpakete sind statische Datendateien, die Sie aus Cloud Firestore-Dokument- und Abfrage-Snapshots erstellen und in einem CDN, einem Hostingdienst oder einer anderen Lösung veröffentlichen. Daten-Bundles enthalten sowohl die Dokumente, die Sie Ihren Clientanwendungen zur Verfügung stellen möchten, als auch Metadaten zu den Abfragen, die sie generiert haben. Sie verwenden Client-SDKs, um Bundles über das Netzwerk oder aus dem lokalen Speicher herunterzuladen. Anschließend laden Sie die Bundle-Daten in den lokalen Cache Cloud Firestore. Sobald ein Bundle geladen wurde, kann eine Client-App Dokumente aus dem lokalen Cache oder dem Back-End abfragen.
Mit Datenpaketen können Ihre Apps die Ergebnisse häufiger Abfragen schneller laden, da die Dokumente beim Start verfügbar sind, ohne dass Aufrufe an das Cloud Firestore-Back-End erforderlich sind. Wenn Ergebnisse aus dem lokalen Cache geladen werden, profitieren Sie auch von geringeren Zugriffskosten. Anstatt für eine Million App-Instanzen zu bezahlen, um dieselben 100 Dokumente abzufragen, zahlen Sie nur für die Abfragen, die zum Bündeln dieser 100 Dokumente erforderlich sind.
Cloud Firestore-Datenpakete sind für die Verwendung mit anderen Firebase-Backend-Produkten konzipiert. Sehen wir uns eine integrierte Lösung an, bei der Bundles von Cloud Functions erstellt und Nutzern mit Firebase Hosting bereitgestellt werden.
Die Verwendung eines Bundles mit Ihrer App umfasst drei Schritte:
- Bundle mit dem Admin SDK erstellen
- Bundle aus lokalem Speicher oder über ein CDN bereitstellen
- Bundles im Client laden
Was ist ein Datenpaket?
Ein Datenpaket ist eine statische Binärdatei, die Sie erstellen, um einen oder mehrere Dokument- und/oder Abfrage-Snapshots zu verpacken, und aus der Sie benannte Abfragen extrahieren können. Wie weiter unten erläutert, können Sie mit den serverseitigen SDKs Bundles erstellen und Client-SDKs bieten Methoden zum Laden von Bundles in den lokalen Cache.
Benannte Abfragen sind eine besonders leistungsstarke Funktion von Sets. Benannte Abfragen sind Query-Objekte, die Sie aus einem Bundle extrahieren und dann sofort verwenden können, um Daten entweder aus dem Cache oder aus dem Backend abzufragen, wie Sie es normalerweise in jedem Teil Ihrer App tun, der mit Cloud Firestore kommuniziert.
Daten-Bundles auf dem Server erstellen
Mit dem Admin SDK für Node.js oder Java haben Sie die vollständige Kontrolle darüber, was in die Bundles aufgenommen werden soll und wie sie bereitgestellt werden.
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()
Datenpakete bereitstellen
Sie können Bundles über ein CDN oder durch Herunterladen von z. B. Cloud Storage an Ihre Client-Apps bereitstellen.
Angenommen, das im vorherigen Abschnitt erstellte Bundle wurde in einer Datei namens bundle.txt gespeichert und auf einem Server veröffentlicht. Diese Bundle-Datei ähnelt jedem anderen Asset, das Sie über das Web bereitstellen können, wie hier für eine einfache Node.js Express-Anwendung gezeigt.
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);
Daten-Bundles im Client laden
Firestore-Bundles laden Sie, indem Sie sie von einem Remoteserver abrufen. Dies kann durch eine HTTP-Anfrage, durch Aufrufen einer Storage API oder mithilfe einer anderen Methode zum Abrufen von Binärdateien in einem Netzwerk erfolgen.
Nach dem Abruf mit dem Cloud Firestore-Client-SDK ruft die App die loadBundle-Methode auf, die ein Aufgaben-Tracking-Objekt zurückgibt. Die Beendigung dieses Vorgangs können Sie bei der Überwachung des Status eines Promise-Objekts im Blick behalten.
Wenn das Laden des Bundles abgeschlossen ist, sind die Inhalte des Bundles im lokalen Cache verfügbar.
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> &){ // ... }); }); });
Wenn Sie eine benannte Abfrage aus einem Bundle laden, das weniger als 30 Minuten zuvor erstellt wurde, und Sie diese zum Lesen aus dem Back-End statt aus dem Cache verwenden, zahlen Sie nur für Datenbanklesevorgänge, die zum Aktualisieren der Dokumente erforderlich sind, damit sie mit dem im Back-End gespeicherten übereinstimmen. Das heißt, Sie zahlen nur für die Deltas.
Und jetzt?
Weitere Informationen finden Sie in der API-Referenzdokumentation für die Data Bundles-Clientseite (Apple, Android, Web) und die Serverseite (Node.js).
Sehen Sie sich die Cloud Functions- und Firebase Hosting-Lösung zum Erstellen und Bereitstellen von Bundles noch einmal an.