เชื่อมต่อแอปกับโปรแกรมจำลอง Cloud Firestore

ก่อนเชื่อมต่อแอปกับโปรแกรมจำลอง Cloud Firestore โปรดตรวจสอบว่าคุณเข้าใจเวิร์กโฟลว์โดยรวมของ Firebase Local Emulator Suite และติดตั้งและกำหนดค่า Local Emulator Suite รวมถึงตรวจสอบคำสั่ง CLI แล้ว

เลือกโปรเจ็กต์ Firebase

Firebase Local Emulator Suite จะจำลองผลิตภัณฑ์สำหรับโปรเจ็กต์ Firebase รายการเดียว

หากต้องการเลือกโปรเจ็กต์ที่จะใช้ ก่อนเริ่มโปรแกรมจำลอง ให้เรียกใช้ firebase use ในไดเรกทอรีที่ใช้งานอยู่ของ CLI หรือจะส่งแฟล็ก --project ไปยังคำสั่งโปรแกรมจำลองแต่ละคำสั่งก็ได้

Local Emulator Suite รองรับการจำลองโปรเจ็กต์ Firebase จริงและโปรเจ็กต์เดโม

เราขอแนะนำให้คุณใช้โปรเจ็กต์เดโมเมื่อใดก็ตามที่เป็นไปได้ สิทธิประโยชน์มีดังนี้

• ตั้งค่าได้ง่ายขึ้น เนื่องจากคุณสามารถเรียกใช้โปรแกรมจำลองได้โดยไม่ต้องสร้างโปรเจ็กต์ Firebase
• ความปลอดภัยที่เข้มงวดขึ้น เนื่องจากหากโค้ดเรียกใช้ทรัพยากรที่ไม่ได้จำลอง (เวอร์ชันที่ใช้งานจริง) โดยไม่ตั้งใจ จะไม่มีโอกาสเกิดการเปลี่ยนแปลงข้อมูล การใช้งาน และการเรียกเก็บเงิน
• รองรับการใช้งานออฟไลน์ได้ดียิ่งขึ้น เนื่องจากไม่จำเป็นต้องเข้าถึงอินเทอร์เน็ตเพื่อดาวน์โหลดการกำหนดค่า SDK

ใช้เครื่องมือในแอปเพื่อสื่อสารกับโปรแกรมจำลอง

เมื่อเริ่มต้นระบบ โปรแกรมจำลอง Cloud Firestore จะสร้างฐานข้อมูลเริ่มต้นและฐานข้อมูลที่มีชื่อสำหรับการกำหนดค่า firestore แต่ละรายการในไฟล์ firebase.json

นอกจากนี้ ระบบยังสร้างฐานข้อมูลที่มีชื่อโดยนัยเพื่อตอบสนองต่อการเรียก SDK หรือ REST API ไปยังโปรแกรมจำลองที่อ้างอิงฐานข้อมูลที่เฉพาะเจาะจงด้วย ฐานข้อมูลที่สร้างขึ้นโดยนัยดังกล่าวจะทำงานด้วยกฎแบบเปิด

หากต้องการทำงานกับฐานข้อมูลเริ่มต้นและฐานข้อมูลที่ตั้งชื่อแบบอินเทอร์แอกทีฟใน Emulator Suite UI ให้ไปที่แถบที่อยู่ของเบราว์เซอร์ แล้วอัปเดต URL เพื่อเลือกฐานข้อมูลเริ่มต้นหรือฐานข้อมูลที่ตั้งชื่อ

• เช่น หากต้องการเรียกดูข้อมูลในอินสแตนซ์เริ่มต้น ให้อัปเดต URL เป็น localhost:4000/firestore/default/data
• หากต้องการเรียกดูในอินสแตนซ์ชื่อ ecommerce ให้อัปเดตเป็น localhost:4000/firestore/ecommerce/data

เริ่มโปรแกรมจำลองในรุ่นที่เฉพาะเจาะจง

โปรแกรมจำลองจะเริ่มทำงานในรุ่นที่ระบุไว้ในส่วน firestore.edition ของไฟล์ firebase.json นอกจากนี้ คุณยังมีตัวเลือกในการระบุรุ่นในส่วน emulators.firestore.edition ของ firebase.json ด้วย ค่าที่ใช้ได้สำหรับรุ่นคือ standard และ enterprise หากคุณระบุ edition ในการกำหนดค่าทั้ง 2 รายการ emulators.firestore.edition จะมีความสำคัญเหนือกว่า

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

Android, แพลตฟอร์ม Apple และ SDK บนเว็บ

ตั้งค่าการกำหนดค่าในแอปหรือคลาสทดสอบเพื่อโต้ตอบกับ Cloud Firestore ดังนี้ โปรดทราบว่าในตัวอย่างต่อไปนี้ โค้ดของแอปจะเชื่อมต่อกับฐานข้อมูลโปรเจ็กต์เริ่มต้น ดูตัวอย่างที่เกี่ยวข้องกับฐานข้อมูล Cloud Firestore เพิ่มเติมนอกเหนือจากฐานข้อมูลเริ่มต้นได้ที่คู่มือสำหรับฐานข้อมูลหลายรายการ

// 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
}
EmulatorSuite.kt

// 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);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

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

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

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

ไม่จำเป็นต้องตั้งค่าเพิ่มเติมเพื่อทดสอบ Cloud Functions ที่ทริกเกอร์โดยเหตุการณ์ Firestore โดยใช้โปรแกรมจำลอง เมื่อโปรแกรมจำลอง Firestore และ Cloud Functions ทำงานอยู่ทั้งคู่ โปรแกรมจำลองทั้งสองจะทำงานร่วมกันโดยอัตโนมัติ

Admin SDK วินาที

Firebase Admin SDK จะเชื่อมต่อกับโปรแกรมจำลอง Cloud Firestore โดยอัตโนมัติเมื่อตั้งค่าตัวแปรสภาพแวดล้อม FIRESTORE_EMULATOR_HOST ดังนี้

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

หากโค้ดของคุณทำงานภายในโปรแกรมจำลอง Cloud Functions ระบบจะตั้งค่ารหัสโปรเจ็กต์และการกำหนดค่าอื่นๆ โดยอัตโนมัติเมื่อเรียกใช้ initializeApp

หากต้องการให้โค้ด Admin SDK เชื่อมต่อกับโปรแกรมจำลองที่ใช้ร่วมกันซึ่งทำงานในสภาพแวดล้อมอื่น คุณต้องระบุรหัสโปรเจ็กต์เดียวกับที่ตั้งค่าไว้โดยใช้ Firebase CLI คุณสามารถส่งรหัสโปรเจ็กต์ไปยัง initializeApp โดยตรงหรือตั้งค่าตัวแปรสภาพแวดล้อม GCLOUD_PROJECT

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

โปรแกรมจำลอง Cloud Firestore มีปลายทาง REST สำหรับการโต้ตอบกับฐานข้อมูล การเรียก REST API ทั้งหมดควรทำไปยังปลายทาง http://localhost:8080/v1

เส้นทางแบบเต็มสำหรับการเรียก REST จะเป็นไปตามรูปแบบต่อไปนี้

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

ตัวอย่างเช่น หากต้องการแสดงรายการเอกสารทั้งหมดในคอลเล็กชัน users สำหรับโปรเจ็กต์ my-project-id คุณสามารถใช้ curl:

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

ล้างฐานข้อมูลระหว่างการทดสอบ

Firestore เวอร์ชันที่ใช้งานจริงไม่มีเมธอด SDK ของแพลตฟอร์มสำหรับการล้างฐานข้อมูล แต่โปรแกรมจำลอง Firestore มีปลายทาง REST สำหรับวัตถุประสงค์นี้โดยเฉพาะ ซึ่งสามารถเรียกใช้จากขั้นตอน setup/tearDown ของเฟรมเวิร์กการทดสอบ จากคลาสทดสอบ หรือจาก Shell (เช่น ด้วย curl) ก่อนที่จะเริ่มการทดสอบ คุณสามารถใช้วิธีนี้เป็นทางเลือกแทนการปิดกระบวนการของโปรแกรมจำลอง

ดำเนินการ HTTP DELETE ด้วยวิธีที่เหมาะสม โดยระบุ Firebase projectID เช่น firestore-emulator-example ไปยังปลายทางต่อไปนี้

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

โดยปกติแล้ว โค้ดของคุณควรรอการยืนยัน REST ว่าการล้างเสร็จสมบูรณ์หรือล้มเหลว

คุณสามารถดำเนินการนี้ได้จาก Shell โดยทำดังนี้

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

เมื่อใช้ขั้นตอนเช่นนี้ คุณจะจัดลำดับการทดสอบและทริกเกอร์ฟังก์ชันได้อย่างมั่นใจว่าข้อมูลเก่าจะถูกล้างระหว่างการเรียกใช้ และคุณกำลังใช้การกำหนดค่าการทดสอบพื้นฐานใหม่

นำเข้าและส่งออกข้อมูล

โปรแกรมจำลองฐานข้อมูลและ Cloud Storage for Firebase ช่วยให้คุณส่งออกข้อมูลจากอินสแตนซ์โปรแกรมจำลองที่ทำงานอยู่ได้ กำหนดชุดข้อมูลพื้นฐานเพื่อใช้ใน Unit Test หรือเวิร์กโฟลว์การรวมอย่างต่อเนื่อง จากนั้นส่งออกเพื่อแชร์กับทีม

firebase emulators:export ./dir

ในการทดสอบ ให้เริ่มโปรแกรมจำลองและนำเข้าข้อมูลพื้นฐาน

firebase emulators:start --import=./dir

คุณสามารถสั่งให้โปรแกรมจำลองส่งออกข้อมูลเมื่อปิดระบบ โดยระบุเส้นทางการส่งออกหรือใช้เส้นทางที่ส่งไปยังแฟล็ก --import

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

ตัวเลือกการนำเข้าและส่งออกข้อมูลเหล่านี้ใช้ได้กับคำสั่ง firebase emulators:exec ด้วยเช่นกัน ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลอ้างอิงคำสั่งโปรแกรมจำลอง

แสดงภาพกิจกรรมของกฎความปลอดภัย

ขณะที่ทำงานผ่านลูปต้นแบบและการทดสอบ คุณสามารถใช้เครื่องมือแสดงภาพและรายงานที่ Local Emulator Suite มีให้

ใช้เครื่องมือตรวจสอบคำขอ

โปรแกรมจำลอง Cloud Firestore ช่วยให้คุณเห็นภาพคำขอของไคลเอ็นต์ใน Emulator Suite UI รวมถึงการติดตามการประเมินสำหรับ Firebase Security Rules

เปิดแท็บ Firestore > คำขอเพื่อดูลำดับการประเมินโดยละเอียดสำหรับคำขอแต่ละรายการ

แสดงรายงานการประเมินกฎเป็นภาพ

เมื่อเพิ่มกฎความปลอดภัยลงในต้นแบบ คุณจะแก้ไขข้อบกพร่องได้ด้วยเครื่องมือแก้ไขข้อบกพร่องของ Local Emulator Suite

หลังจากเรียกใช้ชุดการทดสอบแล้ว คุณจะเข้าถึงรายงานความครอบคลุมของการทดสอบที่แสดงวิธีประเมินกฎความปลอดภัยแต่ละข้อได้

หากต้องการรับรายงาน ให้ค้นหาปลายทางที่แสดงในโปรแกรมจำลองขณะที่ทำงานอยู่ หากต้องการเวอร์ชันที่เหมาะกับเบราว์เซอร์ ให้ใช้ URL ต่อไปนี้

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

ซึ่งจะแบ่งกฎออกเป็นนิพจน์และนิพจน์ย่อยที่คุณสามารถวางเมาส์เหนือเพื่อดูข้อมูลเพิ่มเติม รวมถึงจำนวนการประเมินและค่าที่แสดงผล สำหรับข้อมูลนี้ในเวอร์ชัน JSON ดิบ ให้รวม URL ต่อไปนี้ไว้ในการค้นหา

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

ในที่นี้ รายงานเวอร์ชัน HTML จะไฮไลต์การประเมินที่แสดงข้อผิดพลาดค่าที่ไม่ได้กำหนดและค่า Null ดังนี้

ความแตกต่างระหว่างโปรแกรมจำลอง Cloud Firestore กับเวอร์ชันที่ใช้งานจริง

โปรแกรมจำลอง Cloud Firestore พยายามจำลองลักษณะการทำงานของบริการเวอร์ชันที่ใช้งานจริงอย่างถูกต้องโดยมีข้อจำกัดที่สำคัญบางประการ

การรองรับหลายฐานข้อมูลสำหรับ Cloud Firestore

ปัจจุบัน Emulator Suite UI รองรับการสร้าง การแก้ไข การลบ การตรวจสอบคำขอ และการแสดงภาพความปลอดภัยแบบอินเทอร์แอกทีฟสำหรับฐานข้อมูลเริ่มต้น แต่ไม่รองรับฐานข้อมูลที่มีชื่อเพิ่มเติม

อย่างไรก็ตาม โปรแกรมจำลองจะสร้างฐานข้อมูลที่มีชื่อตามการกำหนดค่าในไฟล์ firebase.json และโดยนัยเพื่อตอบสนองต่อการเรียก API ของ SDK หรือ REST API

ธุรกรรม

ปัจจุบันโปรแกรมจำลองไม่ได้ใช้ลักษณะการทำงานของธุรกรรมทั้งหมดที่เห็นในเวอร์ชันที่ใช้งานจริง เมื่อคุณทดสอบฟีเจอร์ที่เกี่ยวข้องกับการเขียนพร้อมกันหลายรายการในเอกสารเดียว โปรแกรมจำลองอาจเขียนคำขอให้เสร็จสมบูรณ์ได้ช้า ในบางกรณี ระบบอาจใช้เวลาถึง 30 วินาทีในการปลดล็อก พิจารณาปรับระยะหมดเวลาทดสอบตามความเหมาะสม หากจำเป็น

ดัชนี

โปรแกรมจำลองจะไม่ติดตามดัชนีแบบผสม แต่จะดำเนินการค้นหาที่ถูกต้องแทน อย่าลืมทดสอบแอปกับอินสแตนซ์ Cloud Firestore จริงเพื่อพิจารณาว่าคุณต้องใช้ดัชนีใด

จำกัดสูงสุด

โปรแกรมจำลองไม่ได้บังคับใช้ขีดจำกัดทั้งหมดที่บังคับใช้ในเวอร์ชันที่ใช้งานจริง ตัวอย่างเช่น โปรแกรมจำลองอาจอนุญาตธุรกรรมที่บริการเวอร์ชันที่ใช้งานจริงจะปฏิเสธเนื่องจากมีขนาดใหญ่เกินไป ตรวจสอบว่าคุณคุ้นเคยกับขีดจำกัดที่ระบุไว้ และออกแบบแอปเพื่อหลีกเลี่ยงขีดจำกัดดังกล่าวในเชิงรุก

ฉันควรทำอย่างไรต่อไป

• ดูชุดวิดีโอที่คัดสรรมาและตัวอย่างวิธีการโดยละเอียดได้ที่เพลย์ลิสต์การฝึกอบรมเกี่ยวกับโปรแกรมจำลอง Firebase
• ตรวจสอบกรณีการใช้งานขั้นสูงที่เกี่ยวข้องกับการทดสอบกฎความปลอดภัยและ Firebase Test SDK: ทดสอบกฎความปลอดภัย (Firestore)
• เนื่องจากฟังก์ชันที่ทริกเกอร์เป็นการผสานรวมทั่วไปกับ Cloud Firestore โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับโปรแกรมจำลอง Cloud Functions for Firebase ที่หัวข้อ เรียกใช้ฟังก์ชันในเครื่อง