Truy xuất dữ liệu

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

Trước khi bắt đầu

Trước khi bạn có thể sử dụng Cơ sở dữ liệu theo thời gian thực, bạn cần:

  • Đăng ký dự án Unity của bạn và định cấu hình dự án đó để sử dụng Firebase.

    • Nếu dự án Unity của bạn đã sử dụng Firebase thì tức là dự án đã đã đăng ký và định cấu hình cho Firebase.

    • Nếu không có dự án Unity, bạn có thể tải ứng dụng mẫu.

  • Thêm Firebase Unity SDK (cụ thể là FirebaseDatabase.unitypackage) vào dự án Unity của bạn.

Lưu ý rằng việc thêm Firebase vào dự án Unity bao gồm cả các tác vụ trong Bảng điều khiển của Firebase và trong dự án Unity mở của bạn (ví dụ: bạn tải các tệp cấu hình Firebase xuống từ bảng điều khiển, rồi di chuyển vào dự án Unity).

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 GetValueAsync() hoặc đính kèm vào một sự kiện trên tham chiếu FirebaseDatabase. Trình nghe sự kiện là được gọi một lần cho trạng thái ban đầu của dữ liệu và lặp lại mỗi khi dữ liệu thay đổi.

Nhận một DatabaseReference

Để đọc dữ liệu từ cơ sở dữ liệu, bạn cần có một thực thể của DatabaseReference:

using Firebase;
using Firebase.Database;
using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

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

Bạn có thể sử dụng phương thức GetValueAsync để đọc ảnh chụp nhanh tĩnh của 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 ảnh chụp nhanh chứa tất cả dữ liệu tại vị trí đó, bao gồm cả dữ liệu trẻ em. Nếu không có dữ liệu, ảnh chụp nhanh được trả về là null.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Nghe sự kiện

Bạn có thể thêm trình nghe sự kiện để đăng ký các thay đổi đối với dữ liệu:

Sự kiện Mức sử dụng thông thường
ValueChanged Đọc và theo dõi các thay đổi đối với toàn bộ nội dung của đường dẫn.
ChildAdded 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 ChildChanged và ChildRemoved để theo dõi các thay đổi đối với danh sách.
ChildChanged Theo dõi những thay đổi đối với các mục trong danh sách. Dùng với ChildAdded và ChildRemoved để giám sát các thay đổi đối với danh sách.
ChildRemoved Nghe các mục bị xoá khỏi danh sách. Dùng với ChildAdded và ChildChanged để giám sát các thay đổi đối với danh sách.
ChildMoved 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 sự kiện ChildMoved luôn theo sau Sự kiện ChildChanged đã dẫn đến đơn đặt hàng 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).

Sự kiện Giá trị thay đổi

Bạn có thể sử dụng sự kiện ValueChanged để đăng ký nhận những thay đổi của tại một đường dẫn nhất định. Sự kiện này được kích hoạt một lần khi trình nghe được đượ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 sự kiện được truyền một ảnh chụp nhanh chứa tất cả dữ liệu ở vị trí đó, bao gồm dữ liệu con. Nếu không có dữ liệu, ảnh chụp nhanh được trả về sẽ là null.

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

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

ValueChangedEventArgs chứa DataSnapshot chứa dữ liệu ở vị trí được chỉ định trong cơ sở dữ liệu tại thời điểm diễn ra sự kiện. Đang gọi cho Value trên bản tổng quan nhanh sẽ trả về một Dictionary<string, object> biểu thị dữ liệu. Nếu không có dữ liệu ở vị trí này, lệnh gọi Value sẽ trả về null.

Trong ví dụ này, args.DatabaseError cũng được kiểm tra để xem liệu hoạt động đọc có đã huỷ. 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. DatabaseError sẽ cho biết lý do xảy ra lỗi.

Sau này, bạn có thể huỷ đăng ký tham gia sự kiện bằng cách sử dụng bất kỳ DatabaseReference nào có cùng một đường dẫn. DatabaseReference thực thể là tạm thời và có thể chấp nhận được để truy cập vào bất kỳ đường dẫn và truy vấn nào.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

Sự kiện dành cho trẻ em

Sự kiện con được kích hoạt để phản hồi các hoạt động cụ thể xảy ra với phần tử con của một nút từ một thao tác, chẳng hạn như phần tử con mới được thêm vào thông qua Phương thức Push() hoặc phần tử con được cập nhật thông qua UpdateChildrenAsync() . Mỗi phương pháp trong số này có thể hữu ích để theo dõi những thay đổi đối với nút cụ thể trong cơ sở dữ liệu. Ví dụ: một trò chơi có thể sử dụng các phương thức này để cùng nhau 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:

      var ref = FirebaseDatabase.DefaultInstance
      .GetReference("GameSessionComments");

      ref.ChildAdded += HandleChildAdded;
      ref.ChildChanged += HandleChildChanged;
      ref.ChildRemoved += HandleChildRemoved;
      ref.ChildMoved += HandleChildMoved;
    }

    void HandleChildAdded(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildChanged(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildRemoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildMoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

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

Sự kiện ChildChanged được thực hiện mỗi khi 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. Đó là thường được dùng cùng với ChildAdded và ChildRemoved sự kiện để phản hồi các thay đổi đối với danh sách mục. Ảnh chụp nhanh được chuyển đến trình nghe sự kiện chứa dữ liệu đã cập nhật cho thành phần con.

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

Sự kiện ChildMoved được kích hoạt bất cứ khi nào ChildChanged sự kiện được tạo ra bởi một bản cập nhật dẫn đến việc sắp xếp lại thứ tự thành phần con. Đó là được dùng với dữ liệu được sắp xếp theo 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 theo giá trị hoặc theo giá trị của phần tử con. Bạn cũng có thể lọc kết quả được sắp xếp cho một số lượng kết quả cụ thể hoặc một dải khoá hoặc giá trị.

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 sắp xếp theo thứ tự để xác định cách sắp xếp kết quả:

Phương thức Cách 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. Gọi một phương thức đặt hàng 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ý theo dõi một điểm số bảng xếp hạng được sắp xếp theo điểm số.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Thao tác này xác định một truy vấn mà khi được kết hợp với trình nghe sự kiện value đã thay đổi đồng bộ hoá ứng dụng khách 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 Xây dựng 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ả theo. Trong trường hợp này, kết quả được sắp xếp theo giá trị của "score" giá trị 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, xem 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 pháp giới hạn hoặc phạm vi nào với theo thứ tự khi tạo truy vấn.

Phương thức Cách sử dụng
LimitToFirst() Đặt số lượng mục tối đa cần trả về từ đầu danh sách kết quả theo thứ tự.
LimitToLast() Đặt số lượng mặt hàng tối đa cần trả về tính từ cuối đơn đặt hàng danh sách kết quả.
StartAt() Trả về các mục lớn hơn hoặc bằng khoá hoặc giá trị đã chỉ định tuỳ theo phương thức đã chọn.
EndAt() Trả về các mục nhỏ hơn hoặc bằng khoá hoặc giá trị được chỉ định tuỳ theo 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ỳ theo 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 phương thức StartAt() và EndAt() để giới hạn kết quả trong phạm vi giá trị được chỉ định.

Ngay cả khi chỉ có một kết quả phù hợp duy nhất cho truy vấn, ảnh chụp nhanh vẫn sẽ 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 giá trị 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 bạn sử dụng LimitToFirst() để đặt giới hạn là 100, ban đầu bạn chỉ nhận được thành 100 lệnh gọi lại ChildAdded. Nếu bạn có ít hơn 100 mục được lưu trữ trong Cơ sở dữ liệu Firebase, lệnh gọi lại ChildAdded sẽ kích hoạt cho từng mặt hàng.

Khi các mục thay đổi, bạn sẽ nhận được lệnh gọi lại ChildAdded cho các mục nhập và lệnh gọi lại ChildRemoved cho các mục bị loại bỏ để thì 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:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score").LimitToLast(1)
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

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

Bạn có thể sử dụng StartAt(), EndAt() và EqualTo() để chọn tuỳ ý điểm bắt đầu, kết thúc và điểm tương đương cho truy vấn. Điều này có thể hữu ích cho 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 được chỉ định sẽ được sắp xếp như sau:

  1. Phần tử con có giá trị null cho khoá con đã chỉ định sẽ xuất hiện đầu tiên.
  2. Khoá con được chỉ định có giá trị false tiếp theo. Nếu nhiều phần tử con có giá trị false, thì chúng sẽ được sắp xếp theo từ điển theo khoá.
  3. Khoá con được chỉ định có giá trị true tiếp theo. Nếu nhiều phần tử con có giá trị true, thì chúng 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 phần tử con có cùng giá trị số cho phần tử con được chỉ định nút, chúng đượ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 đặt hàng. Nếu nhiều phần tử con có cùng giá trị đối với phần tử con được chỉ định nút, các nút này được sắp xếp từ vựng 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ị. Thứ tự tiêu chí sẽ giống như trong OrderByChild(), ngoại trừ giá trị của nút là được dùng thay cho giá trị của khoá con được chỉ định.