Cloud Firestore pakiety danych to statyczne pliki danych utworzone przez Ciebie na podstawie Cloud Firestoremigawek dokumentów i zapytań, a następnie opublikowane w usłudze CDN, usłudze hostingowej lub innym rozwiązaniu. Pakiety danych zawierają zarówno dokumenty, które chcesz udostępnić aplikacjom klienckim, jak i metadane dotyczące zapytań, które je wygenerowały. Pakiety pobierasz za pomocą pakietów SDK klienta przez sieć lub z pamięci lokalnej, a następnie wczytujesz dane pakietu do lokalnej pamięci podręcznej Cloud Firestore. Po załadowaniu pakietu aplikacja klienta może wysyłać zapytania o dokumenty do lokalnej pamięci podręcznej lub do backendu.
Dzięki pakietom danych Twoje aplikacje mogą szybciej wczytywać wyniki typowych zapytań, ponieważ dokumenty są dostępne podczas uruchamiania bez konieczności wywoływania funkcji w backendzieCloud Firestore. Jeśli wyniki są wczytywane z pamięci podręcznej, możesz też skorzystać z obniżonych kosztów dostępu. Zamiast płacić za milion instancji aplikacji, aby zapytać o te same 100 pierwotnych dokumentów, płacisz tylko za zapytania potrzebne do zgrupowania tych 100 dokumentów.
Pakiety danych Cloud Firestore są tworzone z myślą o współpracy z innymi usługami backendowymi Firebase. Zapoznaj się z zintegrowanym rozwiązaniem, w którym pakiety są tworzone przez Cloud Functions i udostępniane użytkownikom za pomocą Firebase Hosting.
Aby użyć pakietu z aplikacją, wykonaj 3 kroki:
- Tworzenie pakietu za pomocą pakietu Admin SDK
- Udostępnianie pakietu z lokalnej pamięci lub z CDN
- Wczytywanie pakietów w kliencie
Czym jest pakiet danych?
Pakiet danych to statyczny plik binarny utworzony przez Ciebie w celu spakowania co najmniej 1 migawki dokumentu lub zapytania, z którego możesz wyodrębnić nazwane zapytania. Jak opisujemy poniżej, pakiety SDK po stronie serwera umożliwiają tworzenie pakietów, a pakiety SDK po stronie klienta udostępniają metody umożliwiające wczytywanie pakietów do lokalnego pamięci podręcznej.
Zapytania o nazwie to szczególnie przydatna funkcja pakietów. Zapytania o nazwie to obiekty Query, które możesz wyodrębnić z pakietu, a następnie od razu używać do wysyłania zapytań o dane z poziomu pamięci podręcznej lub z poziomu backendu, tak jak to robisz w dowolnej części aplikacji, która komunikuje się z Cloud Firestore.
Tworzenie pakietów danych na serwerze
Korzystanie z Admin SDK w Node.js lub Javie daje Ci pełną kontrolę nad tym, co chcesz uwzględnić 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()
Przekazywanie pakietów danych
Pakiety możesz dostarczać do aplikacji klienckich z CDN lub pobierając 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 jest taki sam jak każdy inny zasób, który możesz udostępniać w internecie, jak w tym przykładzie prostej aplikacji Express w Node.js.
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);
wczytywanie pakietów danych na kliencie,
Pakiety Firestore są wczytywane z serwera zdalnego, czy to przez wysłanie żądania HTTP, wywołanie interfejsu API usługi magazynu lub użycie innej metody pobierania plików binarnych w sieci.
Po pobraniu za pomocą pakietu SDK klienta Cloud Firestore aplikacja wywołuje metodę loadBundle, która zwraca obiekt śledzenia zadania. Możesz śledzić jego ukończenie w sposób podobny do sprawdzania stanu obietnicy.
Po pomyślnym zakończeniu zadania wczytywania pakietu jego zawartość jest dostępna w pamięci podręcznej lokalnej.
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> &){
// ...
});
});
});
Pamiętaj, że jeśli załadujesz zapytanie o nazwie z pakietu utworzonego mniej niż 30 minut temu, a potem używasz go do odczytu z back-endu zamiast z pamięci podręcznej, płacisz tylko za odczyty bazy danych potrzebne do zaktualizowania dokumentów tak, aby pasowały do tego, co jest przechowywane na back-endzie. Oznacza to, że płacisz tylko za różnice.
Co dalej?
Zapoznaj się z dokumentacją referencyjną interfejsu API pakietów danych po stronie klienta (Apple, Android, internet) i po stronie serwera (Node.js).
Jeśli jeszcze tego nie zrobiono, zapoznaj się z rozwiązaniem Cloud Functions i Firebase Hosting do tworzenia i obsługiwania pakietów.