เชื่อมต่อแอปกับโปรแกรมจำลอง 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 จริงคือโปรเจ็กต์ที่คุณสร้างและกำหนดค่า (ส่วนใหญ่ ผ่าน Firebase คอนโซล)

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

เมื่อทำงานกับโปรเจ็กต์ Firebase จริง คุณสามารถเรียกใช้โปรแกรมจำลองสำหรับผลิตภัณฑ์ที่รองรับทั้งหมดหรือบางส่วนก็ได้

สำหรับผลิตภัณฑ์ที่คุณไม่ได้จำลอง แอปและโค้ดจะ โต้ตอบกับทรัพยากรที่ ใช้งานได้ (อินสแตนซ์ฐานข้อมูล บัคเก็ตพื้นที่เก็บข้อมูล ฟังก์ชัน ฯลฯ)

สาธิต

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

รหัสโปรเจ็กต์สำหรับโปรเจ็กต์สาธิตจะมีคำนำหน้า demo-

เมื่อทำงานกับโปรเจ็กต์ Firebase สาธิต แอปและโค้ดจะโต้ตอบกับ โปรแกรมจำลอง เท่านั้น หากแอปพยายามโต้ตอบกับทรัพยากร ที่ไม่มีโปรแกรมจำลองทำงานอยู่ โค้ดนั้นจะทำงานไม่สำเร็จ

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

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

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

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

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

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

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

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

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

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
}
EmulatorSuite.kt
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);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

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

Web

// 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 ทำงานอยู่พร้อมกัน โปรแกรมจำลองทั้ง 2 จะทำงานร่วมกันโดยอัตโนมัติ

Admin SDK

Firebase Admin SDKs จะเชื่อมต่อกับโปรแกรมจำลอง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 SDK ของ Node.js
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 ที่สร้างขึ้นเพื่อวัตถุประสงค์นี้โดยเฉพาะ ซึ่งสามารถเรียกใช้ได้จากขั้นตอนการตั้งค่า/การล้างข้อมูลของเฟรมเวิร์กการทดสอบ จากคลาสทดสอบ หรือจากเชลล์ (เช่น ใช้ curl) ก่อนที่จะเริ่มการทดสอบ คุณสามารถใช้วิธีนี้แทนการปิดกระบวนการโปรแกรมจำลอง

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

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

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

คุณสามารถดำเนินการนี้จากเชลล์ได้ดังนี้

// 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 > คำขอ เพื่อดูรายละเอียดลำดับการประเมินสำหรับคำขอแต่ละรายการ

เครื่องมือตรวจสอบคำขอของโปรแกรมจำลอง 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 และโดยนัยเพื่อตอบสนองต่อการเรียก SDK หรือ REST API

ธุรกรรม

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

ดัชนี

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

จำกัดสูงสุด

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

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