แพ็กเกจข้อมูล Cloud Firestore คือไฟล์ข้อมูลแบบคงที่ที่คุณสร้างจากเอกสาร Cloud Firestore และสแนปชอตการค้นหา และเผยแพร่ใน CDN, บริการโฮสติ้ง หรือโซลูชันอื่นๆ กลุ่มข้อมูลมีทั้งเอกสารที่คุณต้องการส่งไปยังแอปไคลเอ็นต์และข้อมูลเมตาเกี่ยวกับคำค้นหาที่สร้างไฟล์ดังกล่าว คุณใช้ SDK ของไคลเอ็นต์เพื่อดาวน์โหลดแพ็กเกจผ่านเครือข่ายหรือจากพื้นที่เก็บข้อมูลในเครื่องได้ จากนั้นคุณจะโหลดข้อมูลแพ็กเกจไปยังแคชในเครื่อง Cloud Firestore เมื่อโหลด Bundle แล้ว แอปไคลเอ็นต์สามารถค้นหาเอกสารจากแคชในเครื่องหรือแบ็กเอนด์ได้
เมื่อใช้แพ็กเกจข้อมูล แอปจะโหลดผลลัพธ์ของคำค้นหาทั่วไปได้เร็วขึ้น เนื่องจากเอกสารจะพร้อมใช้งานเมื่อเริ่มต้นระบบโดยไม่ต้องเรียกใช้แบ็กเอนด์ของ Cloud Firestore หากผลการค้นหาโหลดจากแคชในเครื่อง คุณจะได้รับประโยชน์จากการลดค่าใช้จ่ายในการเข้าถึงด้วย แทนที่จะต้องจ่ายเงินซื้ออินสแตนซ์ของแอป 1 ล้านครั้งเพื่อค้นหาเอกสาร 100 ฉบับแรกที่เหมือนกัน คุณจะจ่ายเงินสำหรับคำค้นหาที่จำเป็นต่อการรวมเอกสาร 100 รายการนั้นเท่านั้น
ชุดข้อมูล Cloud Firestore สร้างขึ้นเพื่อให้ทำงานร่วมกับผลิตภัณฑ์แบ็กเอนด์อื่นๆ ของ Firebase ได้อย่างมีประสิทธิภาพ ดูโซลูชันที่ผสานรวมซึ่งแพ็กเกจที่ Cloud Functions สร้างขึ้นและแสดงต่อผู้ใช้ด้วยโฮสติ้งของ Firebase
การใช้แพ็กเกจกับแอปมี 3 ขั้นตอน ดังนี้
- การสร้างแพ็กเกจด้วย Admin SDK
- การแสดงแพ็กเกจจากพื้นที่เก็บข้อมูลในเครื่องหรือจาก CDN
- กำลังโหลดแพ็กเกจในไคลเอ็นต์
แพ็กเกจข้อมูลคืออะไร
ชุดข้อมูลคือไฟล์ไบนารีแบบคงที่ที่คุณสร้างขึ้นเพื่อใช้ทำแพ็กเกจเอกสารและ/หรือสแนปชอตการค้นหาอย่างน้อย 1 รายการ และคุณสามารถแยกคำค้นหาที่มีชื่อออกมาได้ ตามที่ได้อธิบายไปด้านล่าง SDK ฝั่งเซิร์ฟเวอร์ให้คุณสร้างแพ็กเกจ และ SDK ของไคลเอ็นต์มอบวิธีให้คุณโหลดแพ็กเกจไปยังแคชในเครื่อง
การค้นหาที่มีชื่อเป็นฟีเจอร์ที่มีประสิทธิภาพอย่างยิ่งของกลุ่ม การค้นหาที่มีชื่อคือออบเจ็กต์ Query
ที่คุณแยกออกจาก Bundle ได้ จากนั้นใช้ทันทีเพื่อค้นหาข้อมูลจากแคชหรือจากแบ็กเอนด์ตามปกติเช่นเดียวกับที่คุณทำในส่วนใดก็ตามของแอปที่สื่อสารกับ 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 การเรียกใช้ API พื้นที่เก็บข้อมูล หรือใช้เทคนิคอื่นๆ ในการดึงข้อมูลไฟล์ไบนารีในเครือข่าย
เมื่อดึงข้อมูลแล้วโดยใช้ SDK ของไคลเอ็นต์ Cloud Firestore แอปของคุณจะเรียกใช้เมธอด loadBundle
ซึ่งจะแสดงผลออบเจ็กต์การติดตามงาน ซึ่งเป็นการดำเนินการที่สมบูรณ์ซึ่งคุณสามารถตรวจสอบได้มากขณะตรวจสอบสถานะของ 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 // ... } }); }
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> &){ // ... }); }); });
โปรดทราบว่าหากคุณโหลดการค้นหาที่ตั้งชื่อไว้จาก Bundle ที่สร้างน้อยกว่า 30 นาที เมื่อคุณใช้การค้นหาเพื่ออ่านจากแบ็กเอนด์แทนแคช คุณจะจ่ายเฉพาะการอ่านฐานข้อมูลที่จำเป็นในการอัปเดตเอกสารให้ตรงกับสิ่งที่เก็บไว้ในแบ็กเอนด์ กล่าวคือ คุณจะจ่ายสำหรับเดลต้าเท่านั้น
ฉันควรทำอย่างไรต่อไป
โปรดดูเอกสารอ้างอิง API ของชุดข้อมูลสำหรับฝั่งไคลเอ็นต์ (Apple, Android, เว็บ) และฝั่งเซิร์ฟเวอร์ (Node.js)
โปรดดูที่โซลูชัน Cloud Functions และ Firebase Hosting สำหรับการสร้างแพ็กเกจและการแสดงแพ็กเกจ หากยังไม่ได้ดู