حِزم بيانات Cloud Firestore

حِزم بيانات Cloud Firestore هي ملفات بيانات ثابتة تنشئها من لقطات مستندات وطلبات بحث Cloud Firestore، وتنشرها على شبكة توصيل المحتوى (CDN) أو خدمة استضافة أو حلّ آخر. تتضمّن حِزم البيانات كلاً من المستندات التي تريد تقديمها إلى تطبيقات العملاء والبيانات الوصفية عن طلبات البحث التي أنشأتها. يمكنك استخدام حِزم تطوير البرامج (SDK) للعملاء لتنزيل الحِزم عبر الشبكة أو من مساحة التخزين المحلية، وبعد ذلك تحمِّل بيانات الحِزمة إلى Cloud Firestore الذاكرة المؤقتة المحلية. بعد تحميل حِزمة، يمكن لتطبيق العميل طلب مستندات من ذاكرة التخزين المؤقت المحلية أو الخلفية.

باستخدام حِزم البيانات، يمكن لتطبيقاتك تحميل نتائج طلبات البحث الشائعة في وقت أقرب، لأنّه تتوفّر المستندات عند بدء التشغيل بدون الحاجة إلى طلبات إلى واجهة برمجة التطبيقات في Cloud Firestore الخلفية. إذا تم تحميل النتائج من ذاكرة التخزين المؤقت المحلية، يمكنك أيضًا الاستفادة من تقليل تكاليف الوصول إلى البيانات. بدلاً من الدفع مقابل مليون مثيل للتطبيق لطلب البحث عن 100 مستند أوّلي نفسه، لن تدفع سوى مقابل طلبات البحث اللازمة لتجميع هذه المستندات المائة.

تم تصميم حِزم بيانات Cloud Firestore للعمل بشكل جيد مع منتجات Firebase الخلفية الأخرى. اطّلِع على حلّ متكامل يُنشئ فيه Cloud Functions الحِزم ويعرضها للمستخدمين باستخدام Firebase Hosting.

يتضمّن استخدام حِزمة مع تطبيقك ثلاث خطوات:

  1. إنشاء الحِزمة باستخدام حزمة SDK للمشرف
  2. عرض الحِزمة من مساحة التخزين الداخلية أو من شبكة توصيل المحتوى (CDN)
  3. تحميل الحِزم في البرنامج

ما هي حِزمة البيانات؟

حِزمة البيانات هي ملف ثنائي ثابت تُنشئه لحزمة واحدة أو أكثر من لقطات مستندات و/أو استعلامات، ويمكنك من خلالها استخراج استعلامات مُسمّاة. كما سنناقش أدناه، تتيح لك حِزم 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()
جافا
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 أو استدعاء واجهة برمجة تطبيقات تخزين أو استخدام أي أسلوب آخر لجلبها من الملفات الثنائية على الشبكة.

بعد استرجاعها، يستدعي تطبيقك loadBundle باستخدام حزمة تطوير البرامج (SDK) لعملاء Cloud Firestore، والتي تعرض loadBundle، وهي عنصر تتبُّع المهام الذي يمكنك تتبُّع اكتماله تمامًا كما تتبُّع حالة الوعد. عند إكمال مهمة تحميل الحِزمة بنجاح، تصبح محتويات الحِزمة متاحة في ذاكرة التخزين المؤقت المحلية.

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 وأهداف تطبيقات Apple Clips. 
// 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 وأهداف تطبيقات Apple Clips. 
// 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 دقيقة، بعد استخدامها للقراءة من الخلفية بدلاً من ذاكرة التخزين المؤقت، لن تدفع سوى مقابل عمليات قراءة قاعدة البيانات اللازمة لتعديل المستندات لتتطابق مع ما هو مخزّن في الخلفية، أي أنّك لن تدفع سوى مقابل الاختلافات.

الخطوة التالية