Pakiety danych Cloud Firestore to statyczne pliki danych utworzone przez Ciebie na podstawie zrzutów dokumentów i zapytań Cloud Firestore oraz publikowane przez Ciebie w sieci CDN, usłudze hostingowej lub innym rozwiązaniu. Pakiety danych obejmują zarówno dokumenty, które chcesz udostępnić aplikacjom klienckim, jak i metadane zapytań, które je wygenerowały. Pakiety SDK klienta służą do pobierania pakietów przez sieć lub z pamięci lokalnej. Później dane pakietu są przesyłane do lokalnej pamięci podręcznej Cloud Firestore. Po załadowaniu pakietu aplikacja kliencka może wysyłać zapytania o dokumenty z lokalnej pamięci podręcznej lub backendu.
Dzięki pakietom danych aplikacje mogą szybciej ładować wyniki typowych zapytań, ponieważ dokumenty są dostępne przy uruchamianiu bez konieczności wywoływania backendu Cloud Firestore. Jeśli wyniki są wczytywane z lokalnej pamięci podręcznej, odnosi się to również do niższych kosztów dostępu. Zamiast płacić za milion instancji aplikacji za zapytania obejmujące te same początkowe 100 dokumentów, płacisz tylko za zapytania, które są niezbędne do połączenia tych 100 dokumentów.
Pakiety danych Cloud Firestore są tworzone tak, aby dobrze współpracowały z innymi usługami backendu Firebase. Zapoznaj się ze zintegrowanym rozwiązaniem, w którym pakiety są tworzone przez Cloud Functions i udostępniane użytkownikom za pomocą Hostingu Firebase.
Korzystanie z pakietu z aplikacją wymaga wykonania 3 kroków:
- Tworzenie pakietu za pomocą pakietu Admin SDK
- Wyświetlanie pakietu z pamięci lokalnej lub z sieci CDN
- Wczytuję pakiety na kliencie
Czym jest pakiet danych?
Pakiet danych to statyczny plik binarny utworzony przez Ciebie, który zawiera spakowane zrzuty dokumentów lub zapytań, z których można wyodrębniać nazwane zapytania. Jak omawiamy poniżej, pakiety SDK po stronie serwera umożliwiają tworzenie pakietów, a pakiety SDK klientów dostarczają metody wczytywania pakietów do lokalnej pamięci podręcznej.
Zapytania nazwane są szczególnie zaawansowaną funkcją pakietów. Zapytania nazwane to obiekty Query, które można wyodrębnić z pakietu, a następnie natychmiast używać do wysyłania zapytań dotyczących danych z pamięci podręcznej lub backendu, jak zwykle w każdej części aplikacji, która komunikuje się z Cloud Firestore.
Tworzenie pakietów danych na serwerze
Korzystając z pakietu Admin SDK w środowisku Node.js lub Java, masz pełną kontrolę nad tym, co chcesz umieścić w pakietach i jak je wyświetlać.
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()
Wyświetlane pakiety danych
Możesz udostępniać pakiety swoim aplikacjom klienckim z sieci CDN lub pobierać je, np. z Cloud Storage.
Załóżmy, że pakiet utworzony w poprzedniej sekcji został zapisany w pliku o nazwie bundle.txt i opublikowany na serwerze. Ten plik pakietu przypomina każdy inny zasób, który możesz wyświetlać w internecie, jak pokazano tutaj w przypadku prostej aplikacji 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);
Wczytuję pakiety danych w kliencie
Pakiety Firestore można wczytać przez pobranie ich z serwera zdalnego. Można to zrobić za pomocą żądania HTTP, wywołania interfejsu API Storage lub dowolnej innej metody pobierania plików binarnych z sieci.
Po pobraniu aplikacja za pomocą pakietu SDK klienta Cloud Firestore wywołuje metodę loadBundle, która zwraca obiekt śledzenia zadań. Jej wykonanie możesz dokładnie monitorować, śledząc stan obietnicy.
Po pomyślnym ukończeniu zadania wczytywania pakietu jego zawartość będzie dostępna w lokalnej pamięci podręcznej.
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
// ...
}
});
}
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> &){
// ...
});
});
});
Pamiętaj, że jeśli wczytasz nazwane zapytanie z pakietu utworzonego mniej niż 30 minut wcześniej, to gdy użyjesz go do odczytu z backendu, a nie pamięci podręcznej, będziesz płacić tylko za odczyty bazy danych niezbędne do aktualizowania dokumentów przechowywanych w backendzie, czyli płacisz tylko za wartości delta.
Co dalej?
Zapoznaj się z dokumentacją interfejsu API pakietów danych po stronie klienta (Apple, Android, internet) i po stronie serwera (Node.js).
Zapoznaj się z rozwiązaniem Cloud Functions i Hostingiem Firebase, które służy do tworzenia i wyświetlania pakietów (chyba że masz to już za sobą).