แพ็กเกจข้อมูลใน Cloud Firestore

หมายเหตุ: แพ็กเกจอินเทอร์เน็ตมือถือเป็นฟีเจอร์ Cloud Firestoreขั้นสูงที่ไม่บังคับ เราจะกล่าวถึงแพ็กเกจข้อมูลที่นี่พร้อมกับแนวคิดพื้นฐานสําหรับทําความเข้าใจCloud Firestore เพื่อให้คุณทราบถึงฟีเจอร์ที่ช่วยจัดการค่าใช้จ่ายในการค้นหาเมื่อแอปขยายขนาด ก่อนพิจารณาแพ็กเกจอินเทอร์เน็ตมือถือ นอกเหนือจากการอ่านหัวข้อภาพรวมและแนวคิดอื่นๆ แล้ว โปรดอ่านคำแนะนำสำหรับการค้นหา Cloud Firestore

แพ็กเกจข้อมูล Cloud Firestore คือไฟล์ข้อมูลแบบคงที่ที่คุณสร้างจากสแนปชอตเอกสารและคำค้นหาของ Cloud Firestore และเผยแพร่ใน CDN, บริการโฮสติ้ง หรือโซลูชันอื่นๆ ชุดข้อมูลประกอบด้วยทั้งเอกสารที่คุณต้องการส่งไปยังแอปไคลเอ็นต์และข้อมูลเมตาเกี่ยวกับคำค้นหาที่สร้างเอกสาร คุณใช้ SDK ของไคลเอ็นต์เพื่อดาวน์โหลด App Bundle ผ่านเครือข่ายหรือจากพื้นที่เก็บข้อมูลในเครื่อง จากนั้นโหลดข้อมูล App Bundle ลงในCloud Firestoreแคชในเครื่อง เมื่อโหลดแพ็กเกจแล้ว แอปไคลเอ็นต์จะค้นหาเอกสารจากแคชในเครื่องหรือแบ็กเอนด์ได้

เมื่อใช้แพ็กเกจอินเทอร์เน็ต แอปจะโหลดผลการค้นหาทั่วไปได้เร็วขึ้น เนื่องจากเอกสารจะพร้อมใช้งานตั้งแต่เริ่มต้นโดยไม่ต้องเรียกใช้แบ็กเอนด์ Cloud Firestore หากระบบโหลดผลการค้นหาจากแคชในเครื่อง คุณยังจะได้รับประโยชน์จากการลดค่าใช้จ่ายในการเข้าถึงด้วย คุณจ่ายเฉพาะการค้นหาที่จำเป็นในการรวมเอกสาร 100 รายการเหล่านั้น แทนที่จะต้องจ่ายค่าอินสแตนซ์แอป 1 ล้านรายการเพื่อค้นหาเอกสาร 100 รายการแรกแบบเดิม

Cloud Firestore data bundle สร้างขึ้นเพื่อให้ทำงานร่วมกับผลิตภัณฑ์แบ็กเอนด์อื่นๆ ของ Firebase ได้ดี ลองดูโซลูชันแบบรวมซึ่ง Cloud Functions จะสร้างแพ็กเกจและแสดงต่อผู้ใช้ด้วย Firebase Hosting

การใช้ App Bundle กับแอปประกอบด้วย 3 ขั้นตอน ดังนี้

การสร้างแพ็กเกจด้วย Admin SDK
แสดงแพ็กเกจจากพื้นที่เก็บข้อมูลในเครื่องหรือจาก CDN
การโหลดแพ็กเกจในไคลเอ็นต์

แพ็กเกจอินเทอร์เน็ตคืออะไร

กลุ่มข้อมูลคือไฟล์ไบนารีแบบคงที่ที่คุณสร้างขึ้นเพื่อแพ็กเกจสแนปชอตเอกสารและ/หรือคำค้นหาอย่างน้อย 1 รายการ และคุณสามารถดึงคำค้นหาที่มีชื่อจากไฟล์นี้ได้ ดังที่ได้อธิบายไว้ด้านล่าง 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()

การแสดงแพ็กเกจอินเทอร์เน็ต

คุณสามารถแสดง App Bundle ในแอปไคลเอ็นต์จาก 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 หรือการใช้เทคนิคอื่นๆ ในการดึงข้อมูลไฟล์ไบนารีในเครือข่าย

เมื่อดึงข้อมูลแล้ว แอปจะเรียกใช้เมธอด 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
  // ...
}fs_bundle_load.js

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
  // ...
}test.solution-bundles.js

Swift

หมายเหตุ: ผลิตภัณฑ์นี้ไม่พร้อมใช้งานบนเป้าหมาย watchOS และ App Clip

// 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)
  }
}SolutionBundles.swift

Objective-C

หมายเหตุ: ผลิตภัณฑ์นี้ไม่พร้อมใช้งานบนเป้าหมาย watchOS และ App Clip

// 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
  }];
}FIRSolutionsBundleViewController.m

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
        // ...
    }
}SolutionBundles.kt

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
            // ...
        }
    });
}SolutionBundles.java

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,
  ),
);
firestore.dart

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> &){
      // ...
    });
  });
});snippets.cpp

โปรดทราบว่าหากคุณโหลดการค้นหาที่มีชื่อจากแพ็กเกจที่สร้างขึ้นไม่ถึง 30 นาทีก่อนหน้านี้ เมื่อคุณใช้การค้นหาดังกล่าวเพื่ออ่านจากแบ็กเอนด์แทนแคช คุณจะจ่ายเฉพาะค่าอ่านฐานข้อมูลที่จําเป็นต่อการอัปเดตเอกสารให้ตรงกับข้อมูลที่จัดเก็บไว้ในแบ็กเอนด์ กล่าวคือ คุณจะจ่ายเฉพาะค่าการเปลี่ยนแปลง

ฉันควรทำอย่างไรต่อไป

โปรดดูเอกสารอ้างอิงเกี่ยวกับ API แพ็กเกจอินเทอร์เน็ตมือถือสำหรับฝั่งไคลเอ็นต์ (Apple, Android, เว็บ) และฝั่งเซิร์ฟเวอร์ (Node.js)
หากยังไม่ได้ดู ให้ดูโซลูชัน Cloud Functions และ Firebase Hosting สำหรับการสร้างและแสดงแพ็กเกจ