Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Gói dữ liệu Cloud Firestore

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Gói dữ liệu Cloud Firestore là các tệp dữ liệu tĩnh do bạn tạo từ ảnh chụp nhanh tài liệu và truy vấn của Cloud Firestore và được bạn xuất bản trên CDN, dịch vụ lưu trữ hoặc giải pháp khác. Gói dữ liệu bao gồm cả tài liệu bạn muốn cung cấp cho ứng dụng khách của mình và siêu dữ liệu về các truy vấn đã tạo ra chúng. Bạn sử dụng SDK ứng dụng khách để tải xuống các gói qua mạng hoặc từ bộ nhớ cục bộ, sau đó bạn tải dữ liệu gói vào bộ đệm cục bộ của Cloud Firestore. Khi một gói được tải, ứng dụng khách có thể truy vấn tài liệu từ bộ đệm cục bộ hoặc chương trình phụ trợ.

Với các gói dữ liệu, ứng dụng của bạn có thể tải kết quả của các truy vấn phổ biến sớm hơn, vì các tài liệu có sẵn khi khởi động mà không cần lệnh gọi đến phần phụ trợ của Cloud Firestore. Nếu kết quả được tải từ bộ đệm cục bộ, bạn cũng được hưởng lợi từ việc giảm chi phí truy cập. Thay vì trả tiền cho một triệu phiên bản ứng dụng để truy vấn cùng 100 tài liệu ban đầu, bạn chỉ trả tiền cho các truy vấn cần thiết để nhóm 100 tài liệu đó.

Gói dữ liệu Cloud Firestore được xây dựng để hoạt động tốt với các sản phẩm phụ trợ khác của Firebase. Hãy xem một giải pháp tích hợp trong đó các gói được Cloud Function xây dựng và phân phát cho người dùng bằng Dịch vụ lưu trữ Firebase.

Sử dụng một gói với ứng dụng của bạn bao gồm ba bước:

  1. Xây dựng gói với SDK quản trị
  2. Cung cấp gói từ bộ nhớ cục bộ hoặc từ CDN
  3. Đang tải các gói trong ứng dụng khách

Gói dữ liệu là gì?

Gói dữ liệu là một tệp nhị phân tĩnh do bạn tạo để đóng gói một hoặc nhiều ảnh chụp nhanh tài liệu và/hoặc truy vấn và từ đó bạn có thể trích xuất các truy vấn đã đặt tên . Như chúng tôi thảo luận bên dưới, SDK phía máy chủ cho phép bạn tạo các gói và SDK máy khách cung cấp các phương thức cho phép bạn tải các gói vào bộ nhớ cache cục bộ.

Các truy vấn được đặt tên là một tính năng đặc biệt mạnh mẽ của các gói. Truy vấn được đặt tên là các đối tượng Query mà bạn có thể trích xuất từ ​​một gói, sau đó sử dụng ngay lập tức để truy vấn dữ liệu từ bộ đệm hoặc từ phần phụ trợ, như cách bạn thường làm trong bất kỳ phần nào của ứng dụng giao tiếp với Cloud Firestore.

Xây dựng gói dữ liệu trên máy chủ

Việc sử dụng Node.js hoặc SDK quản trị Java cho phép bạn kiểm soát hoàn toàn những gì sẽ bao gồm trong các gói và cách phân phối chúng.

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();
      
con trăn
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()
      

Cung cấp gói dữ liệu

Bạn có thể phân phát các gói cho ứng dụng khách của mình từ CDN hoặc bằng cách tải chúng xuống, chẳng hạn như Cloud Storage.

Giả sử gói được tạo trong phần trước đã được lưu vào tệp có tên bundle.txt và được đăng trên máy chủ. Tệp gói này giống như bất kỳ nội dung nào khác mà bạn có thể phân phối trên web, như được hiển thị ở đây cho ứng dụng Node.js Express đơn giản.

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);

Đang tải gói dữ liệu trong máy khách

Bạn tải các gói Firestore bằng cách tìm nạp chúng từ máy chủ từ xa, cho dù bằng cách thực hiện yêu cầu HTTP, gọi API lưu trữ hay sử dụng bất kỳ kỹ thuật nào khác để tìm nạp tệp nhị phân trên mạng.

Sau khi được tìm nạp, sử dụng SDK máy khách Cloud Firestore, ứng dụng của bạn sẽ gọi phương thức loadBundle , phương thức này trả về một đối tượng theo dõi tác vụ, việc hoàn thành mà bạn có thể theo dõi nhiều khi theo dõi trạng thái của Lời hứa. Khi hoàn thành tác vụ tải gói thành công, nội dung gói có sẵn trong bộ đệm cục bộ.

mạng
// 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
  // ...
}
Nhanh
Lưu ý: Sản phẩm này không khả dụng trên các mục tiêu watchOS và 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

      }
    }
  }
}
Mục tiêu-C
Lưu ý: Sản phẩm này không khả dụng trên các mục tiêu watchOS và 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
            // ...
        }
    });
}
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> &){
      // ...
    });
  });
});

Lưu ý rằng nếu bạn tải một truy vấn đã đặt tên từ một gói được tạo trước đó chưa đầy 30 phút, khi bạn sử dụng nó để đọc từ phần phụ trợ thay vì bộ đệm, bạn sẽ chỉ trả tiền cho các lần đọc cơ sở dữ liệu cần thiết để cập nhật tài liệu cho khớp với những gì được lưu trữ trên phần phụ trợ ; nghĩa là, bạn chỉ trả tiền cho đồng bằng.

Tiếp theo là gì?