بسته‌های داده Cloud Firestore

بسته‌های داده Cloud Firestore فایل‌های داده ایستا هستند که توسط شما از سند Cloud Firestore و عکس‌های فوری پرس و جو ساخته می‌شوند و توسط شما در CDN، سرویس میزبانی یا راه‌حل‌های دیگر منتشر می‌شوند. بسته‌های داده شامل اسنادی می‌شوند که می‌خواهید به برنامه‌های مشتری خود ارائه دهید و همچنین فراداده‌های مربوط به جستارهایی که آنها را ایجاد کرده‌اند. شما از SDK های مشتری برای بارگیری بسته ها از طریق شبکه یا از حافظه محلی استفاده می کنید، پس از آن داده های بسته را در حافظه پنهان محلی Cloud Firestore بارگیری می کنید. هنگامی که یک بسته بارگیری می شود، یک برنامه مشتری می تواند اسناد را از حافظه پنهان محلی یا باطن جستجو کند.

با بسته‌های داده، برنامه‌های شما می‌توانند نتایج جستجوهای رایج را زودتر بارگیری کنند، زیرا اسناد در هنگام راه‌اندازی بدون نیاز به تماس با پشتیبان Cloud Firestore در دسترس هستند. اگر نتایج از حافظه نهان محلی بارگیری شود، از کاهش هزینه های دسترسی نیز بهره مند خواهید شد. به جای پرداخت هزینه برای یک میلیون نمونه برنامه برای پرس و جو از 100 سند اولیه، فقط برای درخواست های مورد نیاز برای بسته بندی آن 100 سند پرداخت می کنید.

بسته‌های داده Cloud Firestore به گونه‌ای ساخته شده‌اند که با سایر محصولات باطن Firebase به خوبی کار کنند. نگاهی به راه حل یکپارچه ای بیندازید که در آن بسته ها توسط توابع Cloud ساخته شده و با میزبانی 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 یا با دانلود آن‌ها از فضای ذخیره‌سازی ابری، به برنامه‌های مشتری خود ارائه دهید.

فرض کنید بسته ایجاد شده در بخش قبل در فایلی به نام 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 ذخیره‌سازی یا استفاده از هر تکنیک دیگری برای واکشی فایل‌های باینری در شبکه.

پس از واکشی، با استفاده از Cloud Firestore Client SDK، برنامه شما متد loadBundle را فراخوانی می‌کند که یک شی ردیابی کار را برمی‌گرداند، که تکمیل آن را می‌توانید به همان اندازه که وضعیت یک Promise را نظارت می‌کنید، نظارت کنید. با تکمیل موفقیت آمیز کار بارگیری بسته، محتویات بسته در حافظه پنهان محلی موجود است.

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
  // ...
}
fs_bundle_load.js

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
  // ...
}
test.solution-bundles.js
سریع
توجه: این محصول در اهداف 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
هدف-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
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 دقیقه قبل بارگیری کنید، پس از استفاده از آن برای خواندن از پشتیبان به جای حافظه پنهان، فقط برای خواندن پایگاه داده مورد نیاز برای به روز رسانی اسناد برای مطابقت با آنچه در باطن ذخیره شده است، پرداخت خواهید کرد. ; یعنی شما فقط برای دلتاها پرداخت می کنید.

بعدش چی؟