حزم بيانات Cloud Firestore

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

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

تم تصميم حزم بيانات Cloud Firestore للعمل بشكل جيد مع منتجات Firebase الخلفية الأخرى. ألقِ نظرة على الحل المتكامل الذي يتم من خلاله إنشاء الحزم بواسطة Cloud Functions وتقديمها للمستخدمين من خلال استضافة Firebase.

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

  1. إنشاء الحزمة باستخدام Admin SDK
  2. خدمة الحزمة من التخزين المحلي أو من CDN
  3. تحميل الحزم في العميل

ما هي باقة البيانات؟

حزمة البيانات عبارة عن ملف ثنائي ثابت تم إنشاؤه بواسطتك لحزم واحدة أو أكثر من لقطات المستند و/أو الاستعلام والتي يمكنك من خلالها استخراج الاستعلامات المسماة . كما نناقش أدناه، تتيح لك مجموعات SDK من جانب الخادم إنشاء حزم وتوفر حزم SDK للعملاء طرقًا تتيح لك تحميل الحزم إلى ذاكرة التخزين المؤقت المحلية.

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

بناء حزم البيانات على الخادم

يمنحك استخدام Node.js أو Java Admin SDK التحكم الكامل في ما يجب تضمينه في الحزم وكيفية تقديمها.

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

بمجرد جلبه، باستخدام SDK لعميل Cloud Firestore، يستدعي تطبيقك طريقة loadBundle ، التي تُرجع كائن تتبع المهام، والذي يمكنك مراقبة إكماله بقدر ما تراقب حالة الوعد. عند إكمال مهمة تحميل الحزمة بنجاح، تتوفر محتويات الحزمة في ذاكرة التخزين المؤقت المحلية.

Web modular API

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 namespaced API

// 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
  // ...
}
سويفت
ملاحظة: هذا المنتج غير متوفر في أنظمة watchOS وApp Clip.
// Utility function for errors when loading bundles.
func bundleLoadError(reason: String) -> NSError {
  return NSError(domain: "FIRSampleErrorDomain",
                 code: 0,
                 userInfo: [NSLocalizedFailureReasonErrorKey: reason])
}

// Loads a remote bundle from the provided url.
func fetchRemoteBundle(for firestore: Firestore,
                       from url: URL,
                       completion: @escaping ((Result<LoadBundleTaskProgress, Error>) -> ())) {
  guard let inputStream = InputStream(url: url) else {
    let error = self.bundleLoadError(reason: "Unable to create stream from the given url: \(url)")
    completion(.failure(error))
    return
  }

  // The return value of this function is ignored, but can be used for more granular
  // bundle load observation.
  let _ = firestore.loadBundle(inputStream) { (progress, error) in
    switch (progress, error) {

    case (.some(let value), .none):
      if value.state == .success {
        completion(.success(value))
      } else {
        let concreteError = self.bundleLoadError(
          reason: "Expected bundle load to be completed, but got \(value.state) instead"
        )
        completion(.failure(concreteError))
      }

    case (.none, .some(let concreteError)):
      completion(.failure(concreteError))

    case (.none, .none):
      let concreteError = self.bundleLoadError(reason: "Operation failed, but returned no error.")
      completion(.failure(concreteError))

    case (.some(let value), .some(let concreteError)):
      let concreteError = self.bundleLoadError(
        reason: "Operation returned error \(concreteError) with nonnull progress: \(value)"
      )
      completion(.failure(concreteError))
    }
  }
}

// Fetches a specific named query from the provided bundle.
func loadQuery(named queryName: String,
               fromRemoteBundle bundleURL: URL,
               with store: Firestore,
               completion: @escaping ((Result<Query, Error>) -> ())) {
  fetchRemoteBundle(for: store,
                    from: bundleURL) { (result) in
    switch result {
    case .success:
      store.getQuery(named: queryName) { query in
        if let query = query {
          completion(.success(query))
        } else {
          completion(
            .failure(
              self.bundleLoadError(reason: "Could not find query named \(queryName)")
            )
          )
        }
      }

    case .failure(let error):
      completion(.failure(error))
    }
  }
}

// Load a query and fetch its results from a bundle.
func runStoriesQuery() {
  let queryName = "latest-stories-query"
  let firestore = Firestore.firestore()
  let remoteBundle = URL(string: "https://example.com/createBundle")!
  loadQuery(named: queryName,
            fromRemoteBundle: remoteBundle,
            with: firestore) { (result) in
    switch result {
    case .failure(let error):
      print(error)

    case .success(let query):
      query.getDocuments { (snapshot, error) in

        // handle query results

      }
    }
  }
}
ج موضوعية
ملاحظة: هذا المنتج غير متوفر في أنظمة 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
  }];
}

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
            // ...
        }
    });
}
سي ++
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 دقيقة، بمجرد استخدامه للقراءة من الواجهة الخلفية بدلاً من ذاكرة التخزين المؤقت، فسوف تدفع فقط مقابل عمليات قراءة قاعدة البيانات اللازمة لتحديث المستندات لمطابقة ما تم تخزينه على الواجهة الخلفية ; أي أنك تدفع فقط مقابل الدلتا.

ماذا بعد؟