Truy xuất dữ liệu bằng cơ sở dữ liệu theo thời gian thực của Firebase cho C++

Tài liệu này trình bày các thông tin cơ bản về cách truy xuất dữ liệu, cách sắp xếp và lọc dữ liệu Firebase.

Trước khi bắt đầu

Hãy đảm bảo bạn đã thiết lập ứng dụng và có thể truy cập vào cơ sở dữ liệu như đề cập trong hướng dẫn Get Started.

Truy xuất dữ liệu

Dữ liệu Firebase được truy xuất bằng lệnh gọi một lần đến GetValue() hoặc đính kèm vào ValueListener trên một tệp tham chiếu FirebaseDatabase. Trình nghe giá trị được gọi một lần cho trạng thái ban đầu của dữ liệu và một lần nữa bất cứ khi nào dữ liệu thay đổi.

Nhận một DatabaseReference

Để ghi dữ liệu vào Cơ sở dữ liệu, bạn cần có một thực thể của DatabaseReference:

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

Đọc dữ liệu một lần

Bạn có thể sử dụng phương thức GetValue() để đọc ảnh chụp nhanh tĩnh của nội dung tại một đường dẫn nhất định một lần. Kết quả tác vụ sẽ chứa một bản tổng quan nhanh chứa tất cả dữ liệu ở vị trí đó, bao gồm cả dữ liệu con. Nếu không có dữ liệu, bản tổng quan nhanh được trả về sẽ là null.

  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").GetValue();

Tại thời điểm yêu cầu được đưa ra nhưng chúng ta phải đợi Tương lai hoàn tất thì mới có thể đọc giá trị đó. Vì trò chơi thường chạy trong một vòng lặp và ít được thực hiện lệnh gọi lại hơn so với các ứng dụng khác, nên bạn thường sẽ thăm dò ý kiến để hoàn tất.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

Hình ảnh này minh hoạ một số quy trình kiểm tra lỗi cơ bản, hãy xem tài liệu tham khảo firebase::Future để biết thêm thông tin về quy trình kiểm tra lỗi và các cách xác định thời điểm kết quả đã sẵn sàng.

Nghe sự kiện

Bạn có thể thêm người nghe để đăng ký khi có các thay đổi về dữ liệu:

Lớp cơ sở ValueListener

Gọi lại	Mức sử dụng thông thường
OnValueChanged	Đọc và theo dõi các thay đổi đối với toàn bộ nội dung của đường dẫn.

Lớp cơ sở OnChildListener

OnChildAdded	Truy xuất danh sách các mục hoặc theo dõi để bổ sung vào danh sách các mục. Đề xuất sử dụng với OnChildChanged và OnChildRemoved để theo dõi các thay đổi đối với danh sách.
OnChildChanged	Theo dõi những thay đổi đối với các mục trong danh sách. Hãy sử dụng cùng với OnChildAdded và OnChildRemoved để theo dõi các thay đổi đối với danh sách.
OnChildRemoved	Nghe các mục bị xoá khỏi danh sách. Hãy sử dụng cùng với OnChildAdded và OnChildChanged để theo dõi các thay đổi đối với danh sách.
OnChildMoved	Theo dõi những thay đổi đối với thứ tự của các mục trong danh sách theo thứ tự. Các lệnh gọi lại OnChildMoved luôn tuân theo các lệnh gọi lại OnChildChanged do thứ tự của mặt hàng thay đổi (dựa trên thứ tự theo phương thức hiện tại của bạn).

Lớp ValueListener

Bạn có thể sử dụng các lệnh gọi lại OnValueChanged để đăng ký các thay đổi đối với nội dung tại một đường dẫn nhất định. Lệnh gọi lại này được kích hoạt một lần khi trình nghe được đính kèm và lặp lại mỗi khi dữ liệu (bao gồm cả phần tử con) thay đổi. Lệnh gọi lại được truyền một ảnh chụp nhanh chứa tất cả dữ liệu ở vị trí đó, bao gồm cả dữ liệu con. Nếu không có dữ liệu, ảnh chụp nhanh được trả về sẽ là null.

Lưu ý quan trọng: Sự kiện OnValueChanged sẽ được gọi mỗi khi dữ liệu được thay đổi tại tham chiếu cơ sở dữ liệu được chỉ định, bao gồm cả các thay đổi đối với phần tử con. Để giới hạn kích thước của bản tổng quan nhanh, chỉ đính kèm ở mức cao nhất cần thiết để xem các thay đổi. Ví dụ: bạn không nên đính kèm trình nghe vào gốc của cơ sở dữ liệu.

Ví dụ sau minh hoạ một trò chơi truy xuất điểm số của bảng xếp hạng qua cơ sở dữ liệu:

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

Kết quả Future&ltDataSnapshot&gt chứa dữ liệu ở vị trí đã chỉ định trong cơ sở dữ liệu tại thời điểm diễn ra sự kiện. Việc gọi value() trên bản tổng quan nhanh sẽ trả về một Variant biểu thị dữ liệu.

Trong ví dụ này, phương thức OnCancelled cũng bị ghi đè để xem liệu quá trình đọc có bị huỷ hay không. Ví dụ: một lượt đọc có thể bị huỷ nếu ứng dụng không có quyền đọc từ một vị trí cơ sở dữ liệu Firebase. database::Error sẽ cho biết lý do xảy ra lỗi.

Lớp ChildListener

Các sự kiện con được kích hoạt để phản hồi các thao tác cụ thể xảy ra với các phần tử con của một nút từ một thao tác, chẳng hạn như một thao tác con mới được thêm vào thông qua phương thức PushChild() hoặc một thao tác con được cập nhật thông qua phương thức UpdateChildren(). Mỗi phương pháp này kết hợp lại có thể hữu ích để theo dõi các thay đổi đối với một nút cụ thể trong cơ sở dữ liệu. Ví dụ: một trò chơi có thể sử dụng cùng nhau các phương thức này để theo dõi hoạt động trong phần nhận xét của một phiên trò chơi, như minh hoạ dưới đây:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

Lệnh gọi lại OnChildAdded thường dùng để truy xuất danh sách các mục trong cơ sở dữ liệu Firebase. Lệnh gọi lại OnChildAdded được gọi một lần cho mỗi thành phần con hiện có và sau đó được gọi lại mỗi khi thêm một thành phần con mới vào đường dẫn đã chỉ định. Trình nghe được truyền một ảnh chụp nhanh chứa dữ liệu của nhà xuất bản con mới.

Lệnh gọi lại OnChildChanged được gọi bất cứ khi nào một nút con được sửa đổi. Điều này bao gồm mọi nội dung sửa đổi đối với các thành phần con của nút con. Hàm này thường dùng cùng với các lệnh gọi OnChildAdded và OnChildRemoved để phản hồi các thay đổi đối với danh sách các mục. Bản tổng quan nhanh được truyền vào trình nghe chứa dữ liệu đã cập nhật của phần tử con.

Lệnh gọi lại OnChildRemoved được kích hoạt khi xoá một thành phần con trực tiếp. Hàm này thường được dùng cùng với lệnh gọi lại OnChildAdded và OnChildChanged. Ảnh chụp nhanh được truyền vào lệnh gọi lại chứa dữ liệu của thành phần con đã bị xoá.

Lệnh gọi lại OnChildMoved được kích hoạt bất cứ khi nào lệnh gọi OnChildChanged được cập nhật dẫn đến việc sắp xếp lại thứ tự thành phần con. Hàm này được dùng với dữ liệu được sắp xếp bằng OrderByChild hoặc OrderByValue.

Sắp xếp và lọc dữ liệu

Bạn có thể sử dụng lớp Query của Cơ sở dữ liệu theo thời gian thực để truy xuất dữ liệu được sắp xếp theo khoá, theo giá trị hoặc theo giá trị của thành phần con. Bạn cũng có thể lọc kết quả được sắp xếp theo một số lượng kết quả cụ thể hoặc một dải khoá hoặc giá trị.

Lưu ý: Việc lọc và sắp xếp có thể gây tốn kém, đặc biệt là khi thực hiện trên ứng dụng. Nếu ứng dụng của bạn sử dụng truy vấn, hãy xác định quy tắc .indexOn để lập chỉ mục các khoá đó trên máy chủ và cải thiện hiệu suất truy vấn như mô tả trong phần Lập chỉ mục dữ liệu của bạn.

Sắp xếp dữ liệu

Để truy xuất dữ liệu đã sắp xếp, hãy bắt đầu bằng cách chỉ định một trong các phương thức theo thứ tự để xác định cách sắp xếp kết quả:

Phương thức	Hoạt động sử dụng
OrderByChild()	Sắp xếp kết quả theo giá trị của khoá con được chỉ định.
OrderByKey()	Sắp xếp kết quả theo khoá con.
OrderByValue()	Sắp xếp kết quả theo giá trị con.

Mỗi lần, bạn chỉ có thể sử dụng một phương thức đặt hàng. Việc gọi một phương thức theo thứ tự nhiều lần trong cùng một truy vấn sẽ gây ra lỗi.

Ví dụ sau minh hoạ cách bạn có thể đăng ký một bảng xếp hạng điểm số được sắp xếp theo điểm số.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Thao tác này xác định firebase::Query mà khi kết hợp với ValueListener, ứng dụng sẽ đồng bộ hoá với bảng xếp hạng trong cơ sở dữ liệu, được sắp xếp theo điểm số của mỗi mục nhập. Bạn có thể đọc thêm về cách xây dựng cấu trúc dữ liệu một cách hiệu quả trong phần Cấu trúc cơ sở dữ liệu của bạn.

Lệnh gọi đến phương thức OrderByChild() chỉ định khoá con để sắp xếp kết quả. Trong trường hợp này, kết quả được sắp xếp theo giá trị của giá trị "score" trong mỗi phần tử con. Để biết thêm thông tin về cách sắp xếp các loại dữ liệu khác, hãy xem phần Cách sắp xếp dữ liệu truy vấn.

Lọc dữ liệu

Để lọc dữ liệu, bạn có thể kết hợp bất kỳ phương thức giới hạn hoặc phạm vi nào với một phương thức theo thứ tự khi tạo truy vấn.

Phương thức	Hoạt động sử dụng
LimitToFirst()	Thiết lập số lượng mục tối đa cần trả về từ đầu danh sách kết quả theo thứ tự.
LimitToLast()	Thiết lập số lượng mục tối đa cần trả về từ cuối danh sách kết quả được sắp xếp theo thứ tự.
StartAt()	Trả về các mục lớn hơn hoặc bằng khoá hoặc giá trị đã chỉ định, tuỳ thuộc vào thứ tự từng phương thức đã chọn.
EndAt()	Trả về những mặt hàng có giá trị nhỏ hơn hoặc bằng khoá hoặc giá trị đã chỉ định, tuỳ thuộc vào phương thức đã chọn.
EqualTo()	Trả về các mục bằng với khoá hoặc giá trị đã chỉ định, tuỳ thuộc vào phương thức đã chọn.

Không giống như các phương thức theo thứ tự, bạn có thể kết hợp nhiều hàm giới hạn hoặc hàm phạm vi. Ví dụ: bạn có thể kết hợp các phương thức StartAt() và EndAt() để giới hạn kết quả trong một phạm vi giá trị được chỉ định.

Ngay cả khi chỉ có duy nhất một kết quả phù hợp với truy vấn, ảnh chụp nhanh vẫn là một danh sách; nó chỉ chứa một mục duy nhất.

Giới hạn số lượng kết quả

Bạn có thể sử dụng các phương thức LimitToFirst() và LimitToLast() để đặt số lượng phần tử con tối đa cần đồng bộ hoá cho một lệnh gọi lại nhất định. Ví dụ: nếu sử dụng LimitToFirst() để đặt giới hạn là 100, thì ban đầu bạn chỉ nhận được tối đa 100 lệnh gọi lại OnChildAdded. Nếu bạn có ít hơn 100 mục lưu trữ trong cơ sở dữ liệu Firebase, thì lệnh gọi lại OnChildAdded sẽ kích hoạt cho từng mục.

Khi các mục thay đổi, bạn sẽ nhận được lệnh gọi lại OnChildAdded cho các mục nhập truy vấn và lệnh gọi lại OnChildRemoved cho các mục bị loại bỏ để tổng số vẫn là 100.

Ví dụ: mã dưới đây trả về điểm số cao nhất từ một bảng xếp hạng:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Lọc theo khoá hoặc giá trị

Bạn có thể sử dụng StartAt(), EndAt() và EqualTo() để chọn điểm bắt đầu, điểm kết thúc và điểm tương đương tuỳ ý cho truy vấn. Điều này có thể hữu ích cho việc phân trang dữ liệu hoặc tìm các mục có phần tử con có giá trị cụ thể.

Cách sắp xếp dữ liệu truy vấn

Phần này giải thích cách dữ liệu được sắp xếp theo từng phương thức trong lớp Query.

OrderByChild

Khi sử dụng OrderByChild(), dữ liệu chứa khoá con đã chỉ định được sắp xếp như sau:

1. Các phần tử con có giá trị null cho khoá con đã chỉ định sẽ xuất hiện trước.
2. Phần tử con có giá trị false cho khoá con được chỉ định sẽ xuất hiện tiếp theo. Nếu nhiều phần tử con có giá trị false, thì các phần tử con đó sẽ được sắp xếp theo từ điển theo khoá.
3. Phần tử con có giá trị true cho khoá con được chỉ định sẽ xuất hiện tiếp theo. Nếu nhiều phần tử con có giá trị true, thì các phần tử con đó sẽ được sắp xếp theo từ điển theo khoá.
4. Các phần tử con có giá trị số sẽ xuất hiện tiếp theo, được sắp xếp theo thứ tự tăng dần. Nếu nhiều nút con có cùng giá trị số cho nút con đã chỉ định, thì các nút con đó sẽ được sắp xếp theo khoá.
5. Chuỗi đứng sau số và được sắp xếp theo từ điển theo thứ tự tăng dần. Nếu nhiều nút con có cùng giá trị cho nút con được chỉ định, thì các nút con đó sẽ được sắp xếp theo từ điển theo khoá.
6. Đối tượng đứng cuối và được sắp xếp theo từ điển theo khoá theo thứ tự tăng dần.

OrderByKey

Khi sử dụng OrderByKey() để sắp xếp dữ liệu, dữ liệu sẽ được trả về theo thứ tự tăng dần theo khoá.

1. Phần tử con có khoá có thể được phân tích cú pháp dưới dạng số nguyên 32 bit sẽ đứng trước và được sắp xếp theo thứ tự tăng dần.
2. Phần tử con có giá trị chuỗi là khoá tiếp theo, được sắp xếp theo từ điển theo thứ tự tăng dần.

OrderByValue

Khi sử dụng OrderByValue(), phần tử con được sắp xếp theo giá trị. Các tiêu chí sắp xếp giống như trong OrderByChild(), ngoại trừ việc giá trị của nút được dùng thay cho giá trị của khoá con đã chỉ định.

Các bước tiếp theo

• Lưu dữ liệu