Kết nối ứng dụng với Trình mô phỏng Cloud Firestore

Trước khi kết nối ứng dụng với trình mô phỏng Cloud Firestore, hãy đảm bảo rằng bạn hiểu quy trình làm việc Firebase Local Emulator Suite tổng thể, đồng thời cài đặt và định cấu hình Local Emulator Suite cũng như xem các lệnh CLI của bộ mô phỏng này.

Chọn một dự án Firebase

Firebase Local Emulator Suite mô phỏng các sản phẩm cho một dự án Firebase.

Để chọn dự án cần sử dụng, trước khi bạn khởi động trình mô phỏng, hãy chạy firebase use trong thư mục làm việc của bạn trong CLI. Hoặc bạn có thể truyền cờ --project cho từng lệnh trình mô phỏng

Local Emulator Suite hỗ trợ mô phỏng các dự án Firebase thực và demo dự án.

Loại dự án Tính năng Sử dụng với trình mô phỏng
Thực

Dự án Firebase thực là dự án mà bạn đã tạo và định cấu hình (rất có thể thông qua bảng điều khiển Firebase).

Các dự án thực có tài nguyên trực tiếp, chẳng hạn như thực thể cơ sở dữ liệu, vùng lưu trữ vùng lưu trữ, hàm hoặc bất kỳ tài nguyên nào khác mà bạn thiết lập cho dự án Firebase dự án đó.

Khi làm việc với các dự án Firebase thực, bạn có thể chạy trình mô phỏng cho bất kỳ hoặc tất cả sản phẩm được hỗ trợ.

Đối với bất kỳ sản phẩm nào bạn không mô phỏng, ứng dụng và mã của bạn sẽ tương tác với tài nguyên trực tiếp (thực thể cơ sở dữ liệu, vùng lưu trữ, hàm, v.v.).

Demo

Dự án Firebase demo không có cấu hình Firebase thực và không có tài nguyên trực tiếp. Bạn thường truy cập các dự án này thông qua codelab hoặc các hướng dẫn khác.

Mã dự án cho các dự án demo có tiền tố demo-.

Khi làm việc với các dự án Firebase demo, ứng dụng và mã của bạn tương tác với trình mô phỏng chỉ. Nếu ứng dụng của bạn cố gắng tương tác với một tài nguyên mà trình mô phỏng không chạy, thì mã đó sẽ không thành công.

Bạn nên sử dụng các dự án demo bất cứ khi nào có thể. Các lợi ích bao gồm:

  • Dễ thiết lập hơn vì bạn có thể chạy trình mô phỏng mà không cần tạo dự án Firebase
  • An toàn hơn vì nếu mã của bạn vô tình gọi các tài nguyên không được mô phỏng (sản xuất), thì sẽ không có khả năng thay đổi dữ liệu, mức sử dụng và hoá đơn
  • Hỗ trợ ngoại tuyến tốt hơn vì bạn không cần truy cập vào Internet để tải cấu hình SDK xuống.

Gắn mã theo dõi ứng dụng để giao tiếp với trình mô phỏng

Khi khởi động, trình mô phỏng Cloud Firestore sẽ tạo một cơ sở dữ liệu mặc định và một cơ sở dữ liệu có tên cho từng cấu hình firestore trong tệp firebase.json của bạn.

Cơ sở dữ liệu có tên cũng được tạo ngầm để phản hồi mọi lệnh gọi SDK hoặc API REST đến trình mô phỏng tham chiếu đến một cơ sở dữ liệu cụ thể. Các cơ sở dữ liệu được tạo ngầm như vậy hoạt động theo các quy tắc mở.

Để tương tác với cơ sở dữ liệu mặc định và cơ sở dữ liệu có tên trong Emulator Suite UI, trong thanh địa chỉ của trình duyệt, hãy cập nhật URL để chọn cơ sở dữ liệu mặc định hoặc cơ sở dữ liệu có tên.

  • Ví dụ: để duyệt dữ liệu trong thực thể mặc định, hãy cập nhật URL thành localhost:4000/firestore/default/data
  • Để duyệt trong một thực thể có tên là ecommerce, hãy cập nhật thành localhost:4000/firestore/ecommerce/data.

Khởi động Trình mô phỏng ở một phiên bản cụ thể

Trình mô phỏng sẽ khởi động ở phiên bản được chỉ định trong phần firestore.edition của tệp firebase.json. Bạn cũng có thể chỉ định một phiên bản trong phần emulators.firestore.edition của firebase.json. Các giá trị hợp lệ cho phiên bản là standard và enterprise. Nếu bạn chỉ định edition trong cả hai cấu hình, thì emulators.firestore.edition sẽ được ưu tiên.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

SDK Android, nền tảng Apple và Web

Thiết lập cấu hình trong ứng dụng hoặc các lớp kiểm thử để tương tác với Cloud Firestore như sau. Xin lưu ý rằng trong các mẫu sau đây, mã ứng dụng đang kết nối với cơ sở dữ liệu dự án mặc định. Để xem các ví dụ liên quan đến các cơ sở dữ liệu bổ sung Cloud Firestore ngoài cơ sở dữ liệu mặc định, hãy tham khảo hướng dẫn về nhiều cơ sở dữ liệu.

Kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);

Web

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}

Bạn không cần thiết lập gì thêm để kiểm thử Cloud Functions được kích hoạt bằng các sự kiện Firestore bằng trình mô phỏng. Khi cả trình mô phỏng Firestore và Cloud Functions đều đang chạy, chúng sẽ tự động phối hợp với nhau.

Admin SDKs

Các Firebase Admin SDK sẽ tự động kết nối với Cloud Firestore trình mô phỏng khi biến môi trường FIRESTORE_EMULATOR_HOST được thiết lập:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Nếu mã của bạn đang chạy bên trong trình mô phỏng Cloud Functions, thì mã dự án và cấu hình khác sẽ tự động được thiết lập khi gọi initializeApp.

Nếu bạn muốn mã Admin SDK kết nối với một trình mô phỏng dùng chung đang chạy trong một môi trường khác, bạn cần chỉ định cùng một mã dự án mà bạn đã thiết lập bằng Firebase CLI. Bạn có thể truyền trực tiếp mã dự án đến initializeApp hoặc thiết lập biến môi trường GCLOUD_PROJECT.

SDK dành cho quản trị viên Node.js
admin.initializeApp({ projectId: "your-project-id" });
Biến môi trường
export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Trình mô phỏng Cloud Firestore cung cấp một điểm cuối REST để tương tác với cơ sở dữ liệu của bạn. Tất cả các lệnh gọi API REST phải được thực hiện đến điểm cuối http://localhost:8080/v1.

Đường dẫn đầy đủ cho lệnh gọi REST tuân theo mẫu sau:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Ví dụ: để liệt kê tất cả tài liệu trong tập hợp users cho dự án my-project-id, bạn có thể sử dụng curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Xoá cơ sở dữ liệu giữa các bài kiểm thử

Firestore trong môi trường thực tế không cung cấp phương thức SDK nền tảng để xoá cơ sở dữ liệu, nhưng trình mô phỏng Firestore cung cấp cho bạn một điểm cuối REST dành riêng cho mục đích này. Bạn có thể gọi điểm cuối này từ bước thiết lập/huỷ bỏ khung kiểm thử, từ một lớp kiểm thử hoặc từ shell (ví dụ: bằng curl) trước khi bắt đầu kiểm thử. Bạn có thể sử dụng phương pháp này thay vì chỉ tắt quy trình trình mô phỏng.

Trong một phương thức thích hợp, hãy thực hiện thao tác HTTP DELETE, cung cấp Firebase projectID, ví dụ: firestore-emulator-example, đến điểm cuối sau:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Đương nhiên, mã của bạn sẽ phải chờ xác nhận REST rằng quá trình xoá đã hoàn tất hoặc không thành công.

Bạn có thể thực hiện thao tác này từ shell:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Sau khi triển khai một bước như thế này, bạn có thể sắp xếp các bài kiểm thử theo trình tự và kích hoạt các hàm của mình một cách tự tin rằng dữ liệu cũ sẽ bị xoá giữa các lần chạy và bạn đang sử dụng cấu hình kiểm thử cơ sở mới.

Nhập và xuất dữ liệu

Trình mô phỏng cơ sở dữ liệu và Cloud Storage for Firebase cho phép bạn xuất dữ liệu từ một thực thể trình mô phỏng đang chạy. Xác định một tập hợp dữ liệu cơ sở để sử dụng trong các bài kiểm thử đơn vị hoặc quy trình tích hợp liên tục, sau đó xuất tập hợp dữ liệu đó để chia sẻ giữa các thành viên trong nhóm.

firebase emulators:export ./dir

Trong các bài kiểm thử, khi khởi động trình mô phỏng, hãy nhập dữ liệu cơ sở.

firebase emulators:start --import=./dir

Bạn có thể hướng dẫn trình mô phỏng xuất dữ liệu khi tắt, bằng cách chỉ định đường dẫn xuất hoặc chỉ cần sử dụng đường dẫn được truyền đến cờ --import.

firebase emulators:start --import=./dir --export-on-exit

Các tuỳ chọn nhập và xuất dữ liệu này cũng hoạt động với lệnh firebase emulators:exec. Để biết thêm thông tin, hãy tham khảo tài liệu tham khảo về lệnh trình mô phỏng .

Hình dung hoạt động của Quy tắc bảo mật

Khi thực hiện các vòng lặp nguyên mẫu và thử nghiệm, bạn có thể sử dụng các công cụ trực quan hóa và báo cáo do Local Emulator Suite cung cấp.

Sử dụng Trình giám sát yêu cầu

Trình mô phỏng Cloud Firestore cho phép bạn hình dung các yêu cầu của ứng dụng trong Emulator Suite UI, bao gồm cả việc theo dõi quá trình đánh giá cho Firebase Security Rules.

Mở thẻ Firestore > Yêu cầu để xem chi tiết trình tự đánh giá cho từng yêu cầu.

Trình theo dõi yêu cầu của Trình mô phỏng Firestore cho thấy các lượt đánh giá Quy tắc bảo mật

Hình dung báo cáo đánh giá Quy tắc

Khi thêm Quy tắc bảo mật vào nguyên mẫu, bạn có thể gỡ lỗi các quy tắc đó bằng Local Emulator Suite công cụ gỡ lỗi.

Sau khi chạy một bộ kiểm thử, bạn có thể truy cập vào các báo cáo về phạm vi kiểm thử cho biết cách đánh giá từng quy tắc bảo mật.

Để nhận báo cáo, hãy truy vấn một điểm cuối được hiển thị trên trình mô phỏng khi trình mô phỏng đang chạy. Để xem phiên bản thân thiện với trình duyệt, hãy sử dụng URL sau:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

Thao tác này sẽ chia các quy tắc của bạn thành các biểu thức và biểu thức con mà bạn có thể di chuột qua để biết thêm thông tin, bao gồm cả số lượng đánh giá và các giá trị được trả về. Để xem phiên bản JSON thô của dữ liệu này, hãy thêm URL sau vào truy vấn của bạn:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

Ở đây, phiên bản HTML của báo cáo làm nổi bật các đánh giá gây ra lỗi giá trị không xác định và giá trị rỗng:

Sự khác biệt giữa trình mô phỏng Cloud Firestore và môi trường thực tế

Trình mô phỏng Cloud Firestore cố gắng sao chép chính xác hành vi của dịch vụ trong môi trường thực tế với một số hạn chế đáng chú ý.

Hỗ trợ nhiều cơ sở dữ liệu cho Cloud Firestore

Hiện tại, Emulator Suite UI hỗ trợ việc tạo, chỉnh sửa, xoá, giám sát yêu cầu và hình dung bảo mật một cách tương tác cho cơ sở dữ liệu mặc định, nhưng không hỗ trợ các cơ sở dữ liệu có tên bổ sung.

Tuy nhiên, bản thân trình mô phỏng sẽ tạo một cơ sở dữ liệu có tên dựa trên cấu hình trong tệp firebase.json và ngầm phản hồi các lệnh gọi SDK hoặc API REST.

Giao dịch

Trình mô phỏng hiện không triển khai tất cả hành vi giao dịch được thấy trong môi trường thực tế. Khi bạn đang kiểm thử các tính năng liên quan đến nhiều lần ghi đồng thời vào một tài liệu, trình mô phỏng có thể ghi chậm để hoàn tất các yêu cầu ghi. Trong một số trường hợp, khoá có thể mất đến 30 giây để được phát hành. Hãy cân nhắc điều chỉnh thời gian chờ kiểm thử cho phù hợp nếu cần.

Chỉ số

Trình mô phỏng không theo dõi các chỉ mục tổng hợp mà thay vào đó sẽ thực thi mọi truy vấn hợp lệ. Hãy nhớ kiểm thử ứng dụng của bạn dựa trên một thực thể Cloud Firestore thực để xác định những chỉ mục bạn sẽ cần.

Giới hạn

Trình mô phỏng không thực thi tất cả các giới hạn được thực thi trong môi trường thực tế. Ví dụ: trình mô phỏng có thể cho phép các giao dịch sẽ bị dịch vụ trong môi trường thực tế từ chối vì quá lớn. Hãy đảm bảo bạn đã làm quen với các giới hạn được ghi lại và thiết kế ứng dụng của mình để chủ động tránh các giới hạn đó.

Bước tiếp theo