חבילות נתונים של Cloud Firestore

חבילות נתונים של Cloud Firestore הן קבצי נתונים סטטיים שאתם יוצרים מתוך תמונות מצב של מסמכים ושאילתות של Cloud Firestore, ומפרסמים ברשת CDN, בשירות אירוח או בפתרון אחר. חבילות הנתונים כוללות גם את המסמכים שרוצים לספק לאפליקציות הלקוח וגם מטא-נתונים על השאילתות שיצרו אותם. משתמשים בערכות SDK של לקוח כדי להוריד חבילות דרך הרשת או מאחסון מקומי, ואז טוענים את נתוני החבילה למטמון המקומי Cloud Firestore. אחרי שחבילה נטענת, אפליקציית לקוח יכולה לשלוח שאילתות לגבי מסמכים מהמטמון המקומי או מהקצה העורפי.

חבילות נתונים מאפשרות לאפליקציות לטעון את התוצאות של שאילתות נפוצות מהר יותר, כי המסמכים זמינים בהפעלה בלי שצריך לבצע קריאות ל-backend של Cloud Firestore. אם התוצאות נטענות ממטמון מקומי, אתם גם נהנים מעלויות גישה מופחתות. במקום לשלם על מיליון מופעים של אפליקציות כדי לשלוח שאילתות לגבי אותם 100 מסמכים ראשוניים, אתם משלמים רק על השאילתות שנדרשות כדי לאגד את 100 המסמכים האלה.

חבילות הנתונים של Cloud Firestore נועדו לעבוד בצורה טובה עם מוצרי קצה עורפיים אחרים של Firebase. כדאי לעיין בפתרון משולב שבו חבילות נוצרות על ידי Cloud Functions ומוצגות למשתמשים באמצעות Firebase Hosting.

השימוש בחבילה באפליקציה כולל שלושה שלבים:

יצירת החבילה באמצעות Admin SDK
הצגת החבילה מאחסון מקומי או מ-CDN
טעינת חבילות בלקוח

מהי חבילת נתונים?

חבילת נתונים היא קובץ בינארי סטטי שאתם יוצרים כדי לארוז תמונות מצב של מסמכים ו/או שאילתות, שממנו אפשר לחלץ שאילתות עם שמות. כפי שמפורט בהמשך, ערכות ה-SDK בצד השרת מאפשרות ליצור חבילות, וערכות ה-SDK בצד הלקוח מספקות שיטות לטעינת חבילות למטמון המקומי.

שאילתות עם שם הן תכונה חשובה במיוחד בחבילות. שאילתות עם שם הן אובייקטים שאפשר לחלץ מחבילה, ואז להשתמש בהם באופן מיידי כדי להריץ שאילתות על נתונים ממטמון או מהקצה העורפי, כמו שאתם עושים בדרך כלל בכל חלק באפליקציה שמתקשר עם Cloud Firestore.Query

יצירת חבילות נתונים בשרת

השימוש ב-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 של אחסון או שימוש בטכניקה אחרת לאחזור קבצים בינאריים ברשת.

אחרי השליפה, האפליקציה שולחת קריאה ל-method‏ loadBundle באמצעות Cloud Firestore Client SDK. ה-method מחזיר אובייקט למעקב אחרי משימות, ואפשר לעקוב אחרי השלמת המשימה בדומה למעקב אחרי הסטטוס של 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 וביעדים של קליפים של אפליקציות.

// 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 וביעדים של קליפים של אפליקציות.

// 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

@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, ‏ web) ובצד השרת (Node.js).
אם עדיין לא עשיתם את זה, כדאי לעיין בפתרון Cloud Functions וFirebase Hosting ליצירה ולהצגה של חבילות.