חבילות נתונים של Cloud Firestore הן קובצי נתונים סטטיים שאתם יוצרים ממצבי snapshot של מסמכים ושאילתות ב-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.
יצירת חבילות נתונים בשרת
כשמשתמשים ב-Admin SDK של Node.js או Java, יש לכם שליטה מלאה על מה לכלול בחבילות ועל האופן שבו להציג אותן.
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()
הצגת חבילות נתונים
אפשר להציג חבילות לאפליקציות הלקוח מ-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, בין שבאמצעות קריאה ל-Storage API או באמצעות כל שיטה אחרת לאחזור קבצים בינאריים ברשת.
לאחר האחזור, האפליקציה קוראת ל-method loadBundle באמצעות ה-SDK של הלקוח Cloud Firestore, שמחזיר אובייקט למעקב אחר משימות. אפשר לעקוב אחרי השלמת המשימה כמו שעוקבים אחרי סטטוס של Promise.
בסיום המשימה של טעינת החבילה, תוכן החבילה זמין במטמון המקומי.
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> &){
// ...
});
});
});
חשוב לזכור: אם תטעינו שאילתה בעלת שם מחבילה שנוצרה לפני פחות מ-30 דקות, אחרי שתשתמשו בה כדי לקרוא מהקצה העורפי במקום מהמטמון, תשלמו רק על קריאות למסד הנתונים שנדרשות כדי לעדכן את המסמכים כך שיתאימו למה שנשמר בקצה העורפי. כלומר, תשלמו רק על ההבדלים (deltas).
מה הלאה?
אפשר לעיין במסמכי העזרה של API לחבילות הנתונים בצד הלקוח (Apple, Android, אינטרנט) ובצד השרת (Node.js).
אם עדיין לא עשיתם זאת, כדאי לעיין בפתרון של Cloud Functions ו-Firebase Hosting ליצירה ולהצגה של חבילות.