Cloud Firestore veri paketleri, Cloud Firestore doküman ve sorgu anlık görüntülerinden oluşturulan ve CDN, barındırma hizmeti veya başka bir çözümde yayınladığınız statik veri dosyalarıdır. Veri paketleri hem istemci uygulamalarınıza sağlamak istediğiniz belgeleri hem de bu belgeleri oluşturan sorgularla ilgili meta verileri içerir. Paketleri ağ üzerinden veya yerel depolama alanından indirmek için istemci SDK'larını kullanır, ardından paket verilerini Cloud Firestoreyerel önbelleğe yüklersiniz. Bir paket yüklendikten sonra istemci uygulaması, yerel önbellekten veya arka uçtan dokümanları sorgulayabilir.
Veri paketleri sayesinde, uygulamalarınız yaygın sorguların sonuçlarını daha hızlı yükleyebilir. Bunun nedeni, Cloud Firestore arka ucuna çağrı yapılmasına gerek kalmadan belgelerin başlangıçta kullanılabilir olmasıdır. Sonuçlar yerel önbellekten yüklenirse daha düşük erişim maliyetlerinden de yararlanabilirsiniz. Aynı ilk 100 dokümanı sorgulamak için bir milyon uygulama örneği için ödeme yapmak yerine, yalnızca bu 100 dokümanı gruplandırmak için gereken sorgular için ödeme yaparsınız.
Cloud Firestore veri paketleri, diğer Firebase arka uç ürünleriyle uyumlu olacak şekilde tasarlanmıştır. Paketlerin Cloud Functions tarafından oluşturulduğu ve Firebase Hosting ile kullanıcılara sunulduğu entegre bir çözüme göz atın.
Uygulamanızla paket kullanma işlemi üç adımdan oluşur:
- Paketi Admin SDK ile oluşturma
- Paketi yerel depolama alanından veya CDN'den yayınlama
- İstemciye paket yükleme
Veri paketi nedir?
Veri paketi, bir veya daha fazla belge ve/veya sorgu anlık görüntüsünü paketlemek için oluşturduğunuz ve adlandırılmış sorgular ayıklayabileceğiniz statik bir ikili dosyadır. Aşağıda da bahsettiğimiz gibi, sunucu tarafı SDK'lar paket oluşturmanıza olanak tanır ve istemci SDK'ları, paketleri yerel önbelleğe yüklemenize olanak tanıyan yöntemler sağlar.
Adlandırılmış sorgular, paketlerin özellikle güçlü bir özelliğidir. Adlandırılmış sorgular, bir paketten ayıklayabileceğiniz ve ardından uygulamanızın Cloud Firestore ile iletişim kuran herhangi bir bölümünde normalde yaptığınız gibi, verileri önbellekten veya arka uçtan sorgulamak için hemen kullanabileceğiniz Query nesneleridir.
Sunucuda veri paketleri oluşturma
Node.js veya Java Yönetici SDK'sını kullanmak, paketlere nelerin dahil edileceği ve bunların nasıl yayınlanacağı üzerinde tam kontrol sahibi olmanızı sağlar.
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()
Veri paketleri yayınlama
Paketleri istemci uygulamalarınıza bir CDN'den veya örneğin Cloud Storage'ten indirerek yayınlayabilirsiniz.
Önceki bölümde oluşturulan paketin bundle.txt adlı bir dosyaya kaydedildiğini ve bir sunucuya yayınlandığını varsayalım. Bu paket dosyası, basit bir Node.js Express uygulaması için burada gösterildiği gibi web üzerinden yayınlayabileceğiniz diğer öğelerle aynıdır.
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);
Veri paketlerini istemciye yükleme
Firestore paketlerini, HTTP isteği göndererek, depolama API'sini çağırarak veya ağdaki ikili dosyaları almak için başka bir teknik kullanarak uzak bir sunucudan getirerek yüklersiniz.
Getirildikten sonra uygulamanız, Cloud Firestore istemci SDK'sını kullanarak loadBundle yöntemini çağırır. Bu yöntem, bir görev izleme nesnesi döndürür. Bu nesnenin tamamlanmasını, bir Promise'ın durumunu izlediğinizde olduğu gibi izleyebilirsiniz.
Paket yükleme görevi başarıyla tamamlandığında paket içerikleri yerel önbellekte kullanılabilir.
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 dakikadan kısa bir süre önce oluşturulmuş bir paketten adlandırılmış bir sorgu yüklerseniz bu sorguyu önbellekten değil de arka uçtan okumak için kullandığınızda yalnızca dokümanları arka uçta depolananla eşleşecek şekilde güncellemek için gereken veritabanı okumaları için ödeme yapacağınızı unutmayın. Yani yalnızca farklar için ödeme yaparsınız.
Sonrasında ne olacak?
İstemci tarafı (Apple, Android, web) ve sunucu tarafı (Node.js) için veri paketleri API referans dokümanlarına bakın.
Henüz yapmadıysanız paket oluşturma ve yayınlama için Cloud Functions ve Firebase Hosting çözümüne göz atın.