หน้านี้อธิบายขั้นตอนที่จำเป็นในการสร้างส่วนขยาย Firebase แบบง่าย ซึ่งคุณสามารถติดตั้งในโปรเจ็กต์ของคุณหรือแชร์กับผู้อื่นได้ ตัวอย่างง่ายๆ ของส่วนขยาย Firebase นี้จะคอยดูฐานข้อมูลเรียลไทม์ของคุณเพื่อค้นหาข้อความและแปลงเป็นตัวพิมพ์ใหญ่
1. ตั้งค่าสภาพแวดล้อมของคุณและเริ่มต้นโปรเจ็กต์
ก่อนที่คุณจะเริ่มสร้างส่วนขยายได้ คุณจะต้องตั้งค่าสภาพแวดล้อมบิลด์ด้วยเครื่องมือที่จำเป็น
ติดตั้ง Node.js 16 หรือใหม่กว่า วิธีหนึ่งในการติดตั้ง Node คือการใช้ nvm (หรือ nvm-windows )
ติดตั้งหรืออัปเดตเป็น Firebase CLI เวอร์ชันล่าสุด หากต้องการติดตั้งหรืออัพเดตโดยใช้
npm
ให้รันคำสั่งนี้:npm install -g firebase-tools
ตอนนี้ใช้ Firebase CLI เพื่อเริ่มต้นโปรเจ็กต์ส่วนขยายใหม่:
สร้างไดเร็กทอรีสำหรับส่วนขยายของคุณและ
cd
ลงไป:mkdir rtdb-uppercase-messages && cd rtdb-uppercase-messages
เรียกใช้คำสั่ง
ext:dev:init
ของ Firebase CLI:firebase ext:dev:init
เมื่อได้รับแจ้ง ให้เลือก JavaScript เป็นภาษาสำหรับฟังก์ชันต่างๆ (แต่โปรดทราบว่าคุณสามารถใช้ TypeScript ได้เมื่อคุณพัฒนาส่วนขยายของคุณเอง) และเมื่อระบบขอให้ติดตั้งการอ้างอิง ให้ตอบว่า "ใช่" (ยอมรับค่าเริ่มต้นสำหรับตัวเลือกอื่นๆ) คำสั่งนี้จะตั้งค่าโครงสร้างโค้ดเบสสำหรับส่วนขยายใหม่ ซึ่งคุณสามารถเริ่มพัฒนาส่วนขยายของคุณได้
ใช้ firebase ext:dev:init
เพื่อเริ่มต้นไดเร็กทอรีส่วนขยายใหม่
2. ลองใช้ส่วนขยายตัวอย่างโดยใช้โปรแกรมจำลอง
เมื่อ Firebase CLI เริ่มต้นไดเร็กทอรีส่วนขยายใหม่ มันจะสร้างฟังก์ชันตัวอย่างง่ายๆ และไดเร็กทอรี integration-tests
มีไฟล์ที่จำเป็นในการเรียกใช้ส่วนขยายโดยใช้ชุดโปรแกรมจำลอง Firebase
ลองเรียกใช้ส่วนขยายตัวอย่างในโปรแกรมจำลอง:
เปลี่ยนเป็นไดเร็กทอรี
integration-tests
:cd functions/integration-tests
เริ่มโปรแกรมจำลองด้วยโครงการสาธิต:
firebase emulators:start --project=demo-test
โปรแกรมจำลองจะโหลดส่วนขยายลงในโปรเจ็กต์ "จำลอง" ที่กำหนดไว้ล่วงหน้า (
demo-test
) ส่วนขยายจนถึงตอนนี้ประกอบด้วยฟังก์ชันที่เรียกใช้ HTTP เดียวคือgreetTheWorld
ซึ่งส่งคืนข้อความ "สวัสดีชาวโลก" เมื่อเข้าถึงขณะที่โปรแกรมจำลองยังคงทำงานอยู่ ให้ลองใช้ฟังก์ชัน
greetTheWorld
ของส่วนขยายโดยไปที่ URL ที่โปรแกรมพิมพ์ออกมาเมื่อคุณเริ่มใช้งานเบราว์เซอร์ของคุณแสดงข้อความ "Hello World from Greet-the-World"
ซอร์สโค้ดสำหรับฟังก์ชันนี้อยู่ในไดเร็กทอรี
functions
ของส่วนขยาย เปิดซอร์สในตัวแก้ไขหรือ IDE ที่คุณเลือก:ฟังก์ชั่น/index.js
const functions = require("firebase-functions"); exports.greetTheWorld = functions.https.onRequest((req, res) => { // Here we reference a user-provided parameter // (its value is provided by the user during installation) const consumerProvidedGreeting = process.env.GREETING; // And here we reference an auto-populated parameter // (its value is provided by Firebase after installation) const instanceId = process.env.EXT_INSTANCE_ID; const greeting = `${consumerProvidedGreeting} World from ${instanceId}`; res.send(greeting); });
ขณะที่โปรแกรมจำลองกำลังทำงานอยู่ โปรแกรมจะโหลดการเปลี่ยนแปลงใดๆ ที่คุณทำกับโค้ดฟังก์ชันของคุณซ้ำโดยอัตโนมัติ ลองเปลี่ยนแปลงฟังก์ชัน
greetTheWorld
เล็กน้อย:ฟังก์ชั่น/index.js
const greeting = `${consumerProvidedGreeting} everyone, from ${instanceId}`;
บันทึกการเปลี่ยนแปลงของคุณ โปรแกรมจำลองจะโหลดโค้ดของคุณใหม่ และตอนนี้เมื่อคุณไปที่ URL ของฟังก์ชัน คุณจะเห็นคำทักทายที่อัปเดต
การใช้โปรแกรมจำลองส่วนขยายสามารถเร่งการพัฒนาโดยให้คุณทดสอบและวนซ้ำโค้ดของคุณได้อย่างรวดเร็ว
ข้อมูลมากกว่านี้
เรียนรู้เพิ่มเติมเกี่ยวกับ การใช้โปรแกรมจำลองส่วนขยาย
3. เพิ่มข้อมูลพื้นฐานลงใน extension.yaml
ตอนนี้คุณได้ตั้งค่าสภาพแวดล้อมการพัฒนาและใช้งานโปรแกรมจำลองส่วนขยายแล้ว คุณสามารถเริ่มเขียนส่วนขยายของคุณเองได้
ในขั้นตอนแรกเล็กๆ น้อยๆ ให้แก้ไขข้อมูลเมตาของส่วนขยายที่กำหนดไว้ล่วงหน้าเพื่อให้สะท้อนถึงส่วนขยายที่คุณต้องการเขียนแทน greet-the-world
ข้อมูลเมตานี้ถูกจัดเก็บไว้ในไฟล์ extension.yaml
เปิด
extension.yaml
ในโปรแกรมแก้ไข และแทนที่เนื้อหาทั้งหมดของไฟล์ด้วยเนื้อหาต่อไปนี้:name: rtdb-uppercase-messages version: 0.0.1 specVersion: v1beta # Firebase Extensions specification version; don't change # Friendly display name for your extension (~3-5 words) displayName: Convert messages to upper case # Brief description of the task your extension performs (~1 sentence) description: >- Converts messages in RTDB to upper case author: authorName: Your Name url: https://your-site.example.com license: Apache-2.0 # Required license # Public URL for the source code of your extension sourceUrl: https://github.com/your-name/your-repo
โปรดสังเกตรูปแบบการตั้งชื่อที่ใช้ในฟิลด์
name
: ส่วนขยาย Firebase อย่างเป็นทางการจะมีการตั้งชื่อโดยมีคำนำหน้าระบุผลิตภัณฑ์ Firebase หลักที่ส่วนขยายใช้งาน ตามด้วยคำอธิบายว่าส่วนขยายทำอะไรได้บ้าง คุณควรใช้แบบแผนเดียวกันในส่วนขยายของคุณเองเนื่องจากคุณได้เปลี่ยนชื่อส่วนขยายของคุณ คุณควรอัปเดตการกำหนดค่าโปรแกรมจำลองของคุณด้วยชื่อใหม่:
- ใน
functions/integration-tests/firebase.json
ให้เปลี่ยนgreet-the-world
เป็นrtdb-uppercase-messages
- เปลี่ยนชื่อ
functions/integration-tests/extensions/greet-the-world.env
เป็นfunctions/integration-tests/extensions/rtdb-uppercase-messages.env
- ใน
ยังคงมีส่วนขยายของ greet-the-world
ที่เหลืออยู่ในโค้ดส่วนขยายของคุณ แต่ตอนนี้ทิ้งไว้ก่อน คุณจะอัปเดตสิ่งเหล่านั้นในสองสามส่วนถัดไป
ไฟล์
extension.yaml
มีข้อมูลเมตาเกี่ยวกับส่วนขยายของคุณ ข้อมูลเมตาพื้นฐานที่สุดคือชื่อส่วนขยายของคุณและคำอธิบายว่าส่วนขยายทำอะไรตั้งชื่อส่วนขยายของคุณด้วยรูปแบบต่อไปนี้:
<firebase-product>-<description-of-tasks-performed>
ข้อมูลมากกว่านี้
การอ้างอิง extension.yaml
มีข้อกำหนดเฉพาะของไฟล์ อย่างไรก็ตาม เอกสารนี้จะกล่าวถึงการใช้งานเฉพาะของไฟล์นี้ตามที่คุณต้องการใช้งาน
4. เขียน Cloud Function และประกาศเป็นทรัพยากรส่วนขยาย
ตอนนี้คุณสามารถเริ่มต้นเขียนโค้ดได้แล้ว ในขั้นตอนนี้ คุณจะเขียน Cloud Function ที่ทำหน้าที่หลักของส่วนขยายของคุณ ซึ่งก็คือดูฐานข้อมูลเรียลไทม์เพื่อหาข้อความและแปลงเป็นตัวพิมพ์ใหญ่
เปิดซอร์สสำหรับฟังก์ชันของส่วนขยาย (ในไดเร็กทอรี
functions
ของส่วนขยาย) ในตัวแก้ไขหรือ IDE ที่คุณเลือก แทนที่เนื้อหาด้วยสิ่งต่อไปนี้:ฟังก์ชั่น/index.js
import { database, logger } from "firebase-functions/v1"; const app = initializeApp(); // Listens for new messages added to /messages/{pushId}/original and creates an // uppercase version of the message to /messages/{pushId}/uppercase // for all databases in 'us-central1' export const makeuppercase = database .ref("/messages/{pushId}/uppercase") .onCreate(async (snapshot, context) => { // Grab the current value of what was written to the Realtime Database. const original = snapshot.val(); // Convert it to upper case. logger.log("Uppercasing", context.params.pushId, original); const uppercase = original.toUpperCase(); // Setting an "uppercase" sibling in the Realtime Database. const upperRef = snapshot.ref.parent.child("upper"); await upperRef.set(uppercase); });
ฟังก์ชันเก่าที่คุณแทนที่นั้นเป็นฟังก์ชันที่เรียกใช้ HTTP ซึ่งทำงานเมื่อมีการเข้าถึงตำแหน่งข้อมูล HTTP ฟังก์ชันใหม่จะถูกกระตุ้นโดยเหตุการณ์ฐานข้อมูลแบบเรียลไทม์ โดยจะคอยเฝ้าดูรายการใหม่ในเส้นทางเฉพาะ และเมื่อตรวจพบ รายการนั้นจะเขียนเวอร์ชันตัวพิมพ์ใหญ่ของค่ากลับไปยังฐานข้อมูล
อย่างไรก็ตาม ไฟล์ใหม่นี้ใช้ไวยากรณ์โมดูล ECMAScript (
import
andexport
) แทน CommonJS (require
) หากต้องการใช้โมดูล ES ใน Node ให้ระบุ"type": "module"
ในfunctions/package.json
:{ "name": "rtdb-uppercase-messages", "main": "index.js", "type": "module", … }
ทุกฟังก์ชันในส่วนขยายของคุณจะต้องประกาศในไฟล์
extension.yaml
ส่วนขยายตัวอย่างประกาศว่าgreetTheWorld
เป็นฟังก์ชันคลาวด์เพียงฟังก์ชันเดียวของส่วนขยาย ตอนนี้คุณได้แทนที่ด้วยmakeuppercase
แล้ว คุณต้องอัปเดตการประกาศด้วยเปิด
extension.yaml
และเพิ่มช่องresources
:resources: - name: makeuppercase type: firebaseextensions.v1beta.function properties: eventTrigger: eventType: providers/google.firebase.database/eventTypes/ref.create # DATABASE_INSTANCE (project's default instance) is an auto-populated # parameter value. You can also specify an instance. resource: projects/_/instances/${DATABASE_INSTANCE}/refs/messages/{pushId}/original runtime: "nodejs18"
เนื่องจากขณะนี้ส่วนขยายของคุณใช้ Realtime Database เป็นทริกเกอร์ คุณจึงต้องอัปเดตการกำหนดค่าโปรแกรมจำลองเพื่อเรียกใช้โปรแกรมจำลอง RTDB ควบคู่ไปกับโปรแกรมจำลอง Cloud Functions:
หากโปรแกรมจำลองยังคงทำงานอยู่ ให้หยุดโดยกด Ctrl-C
จากไดเร็กทอรี
functions/integration-tests
ให้รันคำสั่งต่อไปนี้:firebase init emulators
เมื่อระบบถาม ให้ข้ามการตั้งค่าโปรเจ็กต์เริ่มต้น จากนั้นเลือกตัวจำลองฟังก์ชันและฐานข้อมูล ยอมรับพอร์ตเริ่มต้นและอนุญาตให้เครื่องมือตั้งค่าดาวน์โหลดไฟล์ที่จำเป็น
รีสตาร์ทเครื่องจำลอง:
firebase emulators:start --project=demo-test
ลองใช้ส่วนขยายที่อัปเดตของคุณ:
เปิด UI โปรแกรมจำลองฐานข้อมูลโดยใช้ลิงก์ที่โปรแกรมจำลองพิมพ์เมื่อคุณเริ่มใช้งาน
แก้ไขโหนดรูทของฐานข้อมูล:
- สนาม:
messages
- ประเภท:
json
- ค่า:
{"11": {"original": "recipe"}}
หากทุกอย่างถูกต้องตั้งค่าอย่างถูกต้อง เมื่อคุณบันทึกการเปลี่ยนแปลงฐานข้อมูล
makeuppercase
ของส่วนขยายควรทริกเกอร์และเพิ่มบันทึกลูกในข้อความ 11 โดยมีเนื้อหา"upper": "RECIPE"
ดูบันทึกและแท็บฐานข้อมูลของ UI จำลองเพื่อยืนยันผลลัพธ์ที่คาดหวัง- สนาม:
ลองเพิ่มลูกๆ ให้กับโหนด
messages
({"original":"any text"}
) เมื่อใดก็ตามที่คุณเพิ่มระเบียนใหม่ ส่วนขยายควรเพิ่มฟิลด์uppercase
ที่มีเนื้อหาตัวพิมพ์ใหญ่ของฟิลด์original
ตอนนี้คุณมีส่วนขยายที่สมบูรณ์แต่เรียบง่ายซึ่งทำงานบนอินสแตนซ์ RTDB ในส่วนต่อๆ ไป คุณจะปรับแต่งส่วนขยายนี้ด้วยคุณลักษณะเพิ่มเติมบางอย่าง จากนั้น คุณจะได้รับส่วนขยายที่พร้อมที่จะแจกจ่ายให้กับผู้อื่น และสุดท้าย เรียนรู้วิธีเผยแพร่ส่วนขยายของคุณบน Extensions Hub
- ฟังก์ชันที่ประกอบขึ้นเป็นตรรกะของส่วนขยายของคุณจะต้องถูกกำหนดเป็นโค้ด Cloud Functions และประกาศเป็นทรัพยากรส่วนขยายในไฟล์
extension.yaml
- คุณสามารถเขียนฟังก์ชันที่ทริกเกอร์เมื่อมีการเข้าถึงปลายทาง HTTP หรือเพื่อตอบสนองต่อเหตุการณ์ที่ปล่อยออกมาจากผลิตภัณฑ์ Firebase, ผลิตภัณฑ์ Google Cloud และส่วนขยายอื่นๆ
ข้อมูลมากกว่านี้
- เรียนรู้เพิ่มเติมเกี่ยวกับ การเขียน Cloud Functions สำหรับส่วนขยาย รวมถึงข้อมูลเพิ่มเติมเกี่ยวกับทริกเกอร์เหตุการณ์ที่รองรับ
- การอ้างอิง
extension.yaml
มีข้อกำหนดเฉพาะของไฟล์ อย่างไรก็ตาม เอกสารนี้จะกล่าวถึงการใช้งานเฉพาะของไฟล์นี้ตามที่คุณต้องการใช้งาน - เอกสารประกอบฟังก์ชันคลาวด์สำหรับ Firebase มีข้อมูลทั่วไปเกี่ยวกับการใช้ฟังก์ชันคลาวด์ ซึ่งไม่เฉพาะเจาะจงกับส่วนขยาย Firebase
5. ประกาศ API และบทบาท
Firebase ให้สิทธิ์แต่ละอินสแตนซ์ของส่วนขยายที่ติดตั้งโดยจำกัดการเข้าถึงโปรเจ็กต์และข้อมูลโดยใช้บัญชีบริการต่ออินสแตนซ์ แต่ละบัญชีมีชุดสิทธิ์ขั้นต่ำที่จำเป็นในการดำเนินการ ด้วยเหตุนี้ คุณต้องประกาศบทบาท IAM ใดๆ ที่ส่วนขยายของคุณต้องการอย่างชัดเจน เมื่อผู้ใช้ติดตั้งส่วนขยายของคุณ Firebase จะสร้างบัญชีบริการโดยได้รับบทบาทเหล่านี้และใช้เพื่อเรียกใช้ส่วนขยาย
คุณไม่จำเป็นต้องประกาศบทบาทเพื่อทริกเกอร์เหตุการณ์ของผลิตภัณฑ์ แต่คุณต้องประกาศบทบาทเพื่อโต้ตอบกับกิจกรรมดังกล่าว เนื่องจากฟังก์ชันที่คุณเพิ่มในขั้นตอนสุดท้ายเขียนลงใน Realtime Database คุณจึงต้องเพิ่มการประกาศต่อไปนี้ใน extension.yaml
:
roles:
- role: firebasedatabase.admin
reason: Allows the extension to write to RTDB.
ในทำนองเดียวกัน คุณประกาศ Google API ที่ส่วนขยายใช้ใน apis
เมื่อผู้ใช้ติดตั้งส่วนขยายของคุณ ระบบจะถามว่าต้องการเปิดใช้ API เหล่านี้สำหรับโปรเจ็กต์ของตนโดยอัตโนมัติหรือไม่ โดยทั่วไปสิ่งนี้จำเป็นสำหรับ Google API ที่ไม่ใช่ Firebase เท่านั้น และไม่จำเป็นสำหรับคำแนะนำนี้
- ประกาศบทบาท IAM ที่ส่วนขยายของคุณต้องการในช่อง
roles
ของextensions.yaml
เมื่อติดตั้งแล้ว ส่วนขยายจะได้รับบทบาทเหล่านี้โดยอัตโนมัติ - ประกาศ Google API ใดๆ ที่ส่วนขยายของคุณต้องการในช่อง
apis
ของextensions.yaml
เมื่อผู้ใช้ติดตั้งส่วนขยายของคุณ พวกเขาสามารถเลือกเปิดใช้งาน API เหล่านี้สำหรับโปรเจ็กต์ของตนได้โดยอัตโนมัติ - เพื่อวัตถุประสงค์ในการจัดทำเอกสาร ให้ประกาศ API ที่ไม่ใช่ของ Google ว่าส่วนขยายของคุณต้องการในช่อง
externalServices
ของextensions.yaml
ข้อมูลมากกว่านี้
- เรียนรู้เพิ่มเติมเกี่ยวกับ การตั้งค่าการเข้าถึงที่เหมาะสมสำหรับส่วนขยาย
- การอ้างอิง
extension.yaml
มีข้อกำหนดเฉพาะของไฟล์ อย่างไรก็ตาม เอกสารนี้จะกล่าวถึงการใช้งานเฉพาะของไฟล์นี้ตามที่คุณต้องการใช้งาน
6. กำหนดพารามิเตอร์ที่ผู้ใช้กำหนดได้
ฟังก์ชันที่คุณสร้างในสองขั้นตอนสุดท้ายจะเฝ้าดูตำแหน่ง RTDB เฉพาะสำหรับข้อความขาเข้า บางครั้งการดูสถานที่ใดสถานที่หนึ่งก็เป็นสิ่งที่คุณต้องการจริงๆ เช่น เมื่อส่วนขยายของคุณทำงานบนโครงสร้างฐานข้อมูลที่คุณใช้สำหรับส่วนขยายของคุณโดยเฉพาะ อย่างไรก็ตาม โดยส่วนใหญ่ คุณจะต้องกำหนดค่าเหล่านี้โดยผู้ใช้ที่ติดตั้งส่วนขยายของคุณในโปรเจ็กต์ของตน ด้วยวิธีนี้ผู้ใช้สามารถใช้ส่วนขยายของคุณเพื่อทำงานกับการตั้งค่าฐานข้อมูลที่มีอยู่ได้
ทำให้เส้นทางที่ส่วนขยายเฝ้าดูข้อความใหม่ที่ผู้ใช้สามารถกำหนดค่าได้:
ในไฟล์
extension.yaml
ให้เพิ่มส่วนparams
:- param: MESSAGE_PATH label: Message path description: >- What is the path at which the original text of a message can be found? type: string default: /messages/{pushId}/original required: true immutable: false
นี่เป็นการกำหนดพารามิเตอร์สตริงใหม่ที่ผู้ใช้จะได้รับแจ้งให้ตั้งค่าเมื่อติดตั้งส่วนขยายของคุณ
ยังอยู่ในไฟล์
extension.yaml
ให้กลับไปที่การประกาศmakeuppercase
ของคุณ และเปลี่ยนฟิลด์resource
เป็นดังนี้:resource: projects/_/instances/${DATABASE_INSTANCE}/refs/${param:MESSAGE_PATH}
โทเค็น
${param:MESSAGE_PATH}
เป็นการอ้างอิงถึงพารามิเตอร์ที่คุณเพิ่งกำหนด เมื่อส่วนขยายของคุณทำงาน โทเค็นนี้จะถูกแทนที่ด้วยค่าใดก็ตามที่ผู้ใช้กำหนดค่าสำหรับพารามิเตอร์นั้น โดยผลลัพธ์ที่ฟังก์ชันmakeuppercase
จะรับฟังเส้นทางที่ผู้ใช้ระบุ คุณสามารถใช้ไวยากรณ์นี้เพื่ออ้างอิงพารามิเตอร์ที่ผู้ใช้กำหนดได้ทุกที่ในextension.yaml
(และในPOSTINSTALL.md
—จะมีรายละเอียดเพิ่มเติมในภายหลัง)คุณยังสามารถเข้าถึงพารามิเตอร์ที่ผู้ใช้กำหนดได้จากโค้ดฟังก์ชันของคุณ
ในฟังก์ชันที่คุณเขียนไว้ในส่วนสุดท้าย คุณได้ฮาร์ดโค้ดเส้นทางเพื่อดูการเปลี่ยนแปลง เปลี่ยนคำจำกัดความของทริกเกอร์เพื่ออ้างอิงค่าที่ผู้ใช้กำหนดแทน:
ฟังก์ชั่น/index.js
export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate
โปรดทราบว่าในส่วนขยาย Firebase การเปลี่ยนแปลงนี้มีไว้เพื่อประโยชน์ของเอกสารเท่านั้น: เมื่อมีการปรับใช้ฟังก์ชันคลาวด์เป็นส่วนหนึ่งของส่วนขยาย ฟังก์ชันจะใช้คำจำกัดความของทริกเกอร์จากไฟล์
extension.yaml
และละเว้นค่าที่ระบุในคำจำกัดความของฟังก์ชัน อย่างไรก็ตาม เป็นความคิดที่ดีที่จะบันทึกรหัสของคุณว่าค่านี้มาจากไหนคุณอาจพบว่าการเปลี่ยนแปลงโค้ดที่ไม่มีผลกระทบต่อรันไทม์เป็นเรื่องน่าผิดหวัง แต่บทเรียนสำคัญที่ต้องเรียนรู้คือคุณสามารถเข้าถึงพารามิเตอร์ที่ผู้ใช้กำหนดในโค้ดฟังก์ชันของคุณ และใช้เป็นค่าปกติในลอจิกของฟังก์ชันได้ เพื่อเป็นการยกย่องความสามารถนี้ ให้เพิ่มคำสั่งบันทึกต่อไปนี้เพื่อแสดงว่าคุณกำลังเข้าถึงค่าที่ผู้ใช้กำหนดไว้:
ฟังก์ชั่น/index.js
export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate( async (snapshot, context) => { logger.log("Found new message at ", snapshot.ref); // Grab the current value of what was written to the Realtime Database. ...
โดยปกติ ผู้ใช้จะได้รับแจ้งให้ระบุค่าสำหรับพารามิเตอร์เมื่อติดตั้งส่วนขยาย อย่างไรก็ตาม เมื่อคุณใช้โปรแกรมจำลองสำหรับการทดสอบและการพัฒนา คุณจะข้ามขั้นตอนการติดตั้ง ดังนั้นคุณจึงต้องระบุค่าสำหรับพารามิเตอร์ที่ผู้ใช้กำหนดโดยใช้ไฟล์
env
แทนเปิด
functions/integration-tests/extensions/rtdb-uppercase-messages.env
และแทนที่คำจำกัดความGREETING
ด้วยสิ่งต่อไปนี้:MESSAGE_PATH=/msgs/{pushId}/original
โปรดสังเกตว่าเส้นทางด้านบนแตกต่างจากเส้นทางเริ่มต้นและจากเส้นทางที่คุณกำหนดไว้ก่อนหน้านี้ นี่เป็นเพียงเพื่อพิสูจน์ตัวเองเมื่อคุณลองใช้ส่วนขยายที่อัปเดตว่าคำจำกัดความของคุณมีผล
ตอนนี้ให้รีสตาร์ทโปรแกรมจำลองและไปที่ UI โปรแกรมจำลองฐานข้อมูลอีกครั้ง
แก้ไขโหนดรูทของฐานข้อมูล โดยใช้เส้นทางที่คุณกำหนดไว้ด้านบน:
- สนาม:
msgs
- ประเภท:
json
- ค่า:
{"11": {"original": "recipe"}}
เมื่อคุณบันทึกการเปลี่ยนแปลงฐานข้อมูล ฟังก์ชัน
makeuppercase
ของส่วนขยายควรทริกเกอร์เหมือนเมื่อก่อน แต่ตอนนี้ควรพิมพ์พารามิเตอร์ที่ผู้ใช้กำหนดลงในบันทึกของคอนโซลด้วย- สนาม:
- คุณสามารถให้ผู้ใช้สามารถปรับแต่งส่วนขยายของคุณตามความต้องการได้โดยการประกาศพารามิเตอร์ที่ผู้ใช้กำหนดในไฟล์
extension.yaml
ผู้ใช้จะได้รับแจ้งให้กำหนดค่าเหล่านี้เมื่อติดตั้งส่วนขยายของคุณ - คุณสามารถอ้างอิงค่าพารามิเตอร์ที่ผู้ใช้กำหนดภายในไฟล์
extension.yaml
และในไฟล์POSTINSTALL.md
โดยใช้ไวยากรณ์ต่อไปนี้:${param:PARAMETER_NAME}
- คุณสามารถเข้าถึงค่าพารามิเตอร์ที่ผู้ใช้กำหนดภายในโค้ด Cloud Functions ของคุณเป็นตัวแปรสภาพแวดล้อม:
process.env.PARAMETER_NAME
- เมื่อทดสอบโดยใช้โปรแกรมจำลอง ให้กำหนดพารามิเตอร์ผู้ใช้ในไฟล์
<extension-name>.env
ข้อมูลมากกว่านี้
เรียนรู้เพิ่มเติมเกี่ยวกับ การตั้งค่าและการใช้พารามิเตอร์ในส่วนขยายของคุณ
7. จัดให้มี hooks เหตุการณ์สำหรับตรรกะที่ผู้ใช้กำหนด
ในฐานะผู้เขียนส่วนขยาย คุณคงได้เห็นแล้วว่าผลิตภัณฑ์ Firebase สามารถทริกเกอร์ตรรกะที่ให้ส่วนขยายของคุณได้อย่างไร: การสร้างบันทึกใหม่ใน Realtime Database จะทริกเกอร์ฟังก์ชัน makeuppercase
ของคุณ ส่วนขยายของคุณสามารถมีความสัมพันธ์แบบอะนาล็อกกับผู้ใช้ที่ติดตั้งส่วนขยายของคุณ: ส่วนขยาย ของคุณสามารถทริกเกอร์ตรรกะที่ ผู้ใช้ กำหนด
ส่วนขยายสามารถจัดให้มี hooks แบบซิงโครนัส , hooks แบบอะซิงโครนัส หรือทั้งสองอย่าง Hooks แบบซิงโครนัสทำให้ผู้ใช้สามารถทำงานที่ขัดขวางการทำงานของส่วนขยายอย่างใดอย่างหนึ่ง สิ่งนี้อาจมีประโยชน์ เช่น เพื่อให้ผู้ใช้สามารถดำเนินการประมวลผลล่วงหน้าแบบกำหนดเองก่อนที่ส่วนขยายจะทำงาน
ในคู่มือนี้ คุณจะเพิ่มฮุกแบบอะซิงโครนัสให้กับส่วนขยายของคุณ ซึ่งจะทำให้ผู้ใช้สามารถกำหนดขั้นตอนการประมวลผลของตนเองที่จะเรียกใช้หลังจากที่ส่วนขยายของคุณเขียนข้อความตัวพิมพ์ใหญ่ไปยังฐานข้อมูลเรียลไทม์ Hooks แบบอะซิงโครนัสใช้ Eventarc เพื่อทริกเกอร์ฟังก์ชันที่ผู้ใช้กำหนด ส่วนขยายจะประกาศประเภทของเหตุการณ์ที่ปล่อยออกมา และเมื่อผู้ใช้ติดตั้งส่วนขยาย ผู้ใช้จะเลือกประเภทเหตุการณ์ที่พวกเขาสนใจ หากพวกเขาเลือกอย่างน้อยหนึ่งเหตุการณ์ Firebase จะจัดเตรียมช่องทาง Eventarc สำหรับส่วนขยายโดยเป็นส่วนหนึ่งของกระบวนการติดตั้ง . จากนั้นผู้ใช้สามารถปรับใช้ฟังก์ชันคลาวด์ของตนเองที่รับฟังช่องทางนั้นและทริกเกอร์เมื่อส่วนขยายเผยแพร่กิจกรรมใหม่
ทำตามขั้นตอนเหล่านี้เพื่อเพิ่มเบ็ดแบบอะซิงโครนัส:
ในไฟล์
extension.yaml
ให้เพิ่มส่วนต่อไปนี้ ซึ่งประกาศประเภทเหตุการณ์เดียวที่ส่วนขยายปล่อยออกมา:events: - type: test-publisher.rtdb-uppercase-messages.v1.complete description: >- Occurs when message uppercasing completes. The event subject will contain the RTDB URL of the uppercase message.
ประเภทเหตุการณ์ต้องไม่ซ้ำกันในระดับสากล เพื่อให้แน่ใจว่าจะไม่ซ้ำกัน ให้ตั้งชื่อกิจกรรมของคุณโดยใช้รูปแบบต่อไปนี้เสมอ:
<publisher-id>.<extension-id>.<version>.<description>
(คุณยังไม่มีรหัสผู้เผยแพร่ ดังนั้นให้ใช้test-publisher
ในตอนนี้)ในตอนท้ายของฟังก์ชัน
makeuppercase
ให้เพิ่มโค้ดที่เผยแพร่เหตุการณ์ประเภทที่คุณเพิ่งประกาศ:ฟังก์ชั่น/index.js
// Import the Eventarc library: import { initializeApp } from "firebase-admin/app"; import { getEventarc } from "firebase-admin/eventarc"; const app = initializeApp(); // In makeuppercase, after upperRef.set(uppercase), add: // Set eventChannel to a newly-initialized channel, or `undefined` if events // aren't enabled. const eventChannel = process.env.EVENTARC_CHANNEL && getEventarc().channel(process.env.EVENTARC_CHANNEL, { allowedEventTypes: process.env.EXT_SELECTED_EVENTS, }); // If events are enabled, publish a `complete` event to the configured // channel. eventChannel && eventChannel.publish({ type: "test-publisher.rtdb-uppercase-messages.v1.complete", subject: upperRef.toString(), data: { "original": original, "uppercase": uppercase, }, });
โค้ดตัวอย่างนี้ใช้ประโยชน์จากข้อเท็จจริงที่ว่าตัวแปรสภาพแวดล้อม
EVENTARC_CHANNEL
ถูกกำหนดไว้เฉพาะเมื่อผู้ใช้เปิดใช้งานประเภทเหตุการณ์อย่างน้อยหนึ่งประเภท หากไม่ได้กำหนดEVENTARC_CHANNEL
โค้ดจะไม่พยายามเผยแพร่กิจกรรมใดๆคุณสามารถแนบข้อมูลเพิ่มเติมกับกิจกรรม Eventarc ได้ ในตัวอย่างด้านบน กิจกรรมมีช่อง
subject
ที่มีการอ้างอิงถึงค่าที่สร้างขึ้นใหม่ และเพย์โหลดdata
ที่มีข้อความต้นฉบับและตัวพิมพ์ใหญ่ ฟังก์ชันที่ผู้ใช้กำหนดซึ่งทริกเกอร์ปิดเหตุการณ์สามารถใช้ข้อมูลนี้ได้โดยปกติแล้ว ตัวแปรสภาพแวดล้อม
EVENTARC_CHANNEL
และEXT_SELECTED_EVENTS
จะถูกกำหนดตามตัวเลือกที่ผู้ใช้เลือกระหว่างการติดตั้ง สำหรับการทดสอบด้วยโปรแกรมจำลอง ให้กำหนดตัวแปรเหล่านี้ด้วยตนเองในไฟล์rtdb-uppercase-messages.env
:EVENTARC_CHANNEL=locations/us-central1/channels/firebase EXT_SELECTED_EVENTS=test-publisher.rtdb-uppercase-messages.v1.complete
ณ จุดนี้ คุณได้ทำตามขั้นตอนที่จำเป็นในการเพิ่ม hook เหตุการณ์แบบอะซิงโครนัสให้กับส่วนขยายของคุณแล้ว
หากต้องการลองใช้คุณลักษณะใหม่นี้ที่คุณเพิ่งใช้งาน ให้สมมติบทบาทของผู้ใช้ที่กำลังติดตั้งส่วนขยายในไม่กี่ขั้นตอนถัดไป:
จากไดเร็กทอรี
functions/integration-tests
ให้เริ่มต้นโปรเจ็กต์ Firebase ใหม่:firebase init functions
เมื่อได้รับแจ้ง ให้ปฏิเสธที่จะตั้งค่าโปรเจ็กต์เริ่มต้น เลือก JavaScript เป็นภาษาของ Cloud Functions และติดตั้งการขึ้นต่อกันที่จำเป็น โปรเจ็กต์นี้แสดงถึงโปรเจ็กต์ ของผู้ใช้ ซึ่งมีการติดตั้งส่วนขยายของคุณ
แก้ไข
integration-tests/functions/index.js
และวางโค้ดต่อไปนี้:import { logger } from "firebase-functions/v1"; import { onCustomEventPublished } from "firebase-functions/v2/eventarc"; import { initializeApp } from "firebase-admin/app"; import { getDatabase } from "firebase-admin/database"; const app = initializeApp(); export const extraemphasis = onCustomEventPublished( "test-publisher.rtdb-uppercase-messages.v1.complete", async (event) => { logger.info("Received makeuppercase completed event", event); const refUrl = event.subject; const ref = getDatabase().refFromURL(refUrl); const upper = (await ref.get()).val(); return ref.set(`${upper}!!!`); } );
นี่คือตัวอย่างฟังก์ชันหลังการประมวลผลที่ผู้ใช้อาจเขียน ในกรณีนี้ ฟังก์ชันจะรับฟังส่วนขยายเพื่อเผยแพร่เหตุการณ์
complete
และเมื่อถูกทริกเกอร์ จะเพิ่มเครื่องหมายอัศเจรีย์ 3 อันให้กับข้อความที่เป็นตัวพิมพ์ใหญ่ใหม่รีสตาร์ทเครื่องจำลอง โปรแกรมจำลองจะโหลดฟังก์ชันของส่วนขยายตลอดจนฟังก์ชันหลังการประมวลผลที่ "ผู้ใช้" กำหนดไว้
ไปที่ UI โปรแกรมจำลองฐานข้อมูลและแก้ไขโหนดรูทของฐานข้อมูล โดยใช้เส้นทางที่คุณกำหนดไว้ด้านบน:
- สนาม:
msgs
- ประเภท:
json
- ค่า:
{"11": {"original": "recipe"}}
เมื่อคุณบันทึกการเปลี่ยนแปลงฐานข้อมูล ฟังก์ชัน
makeuppercase
ของส่วนขยายและฟังก์ชันextraemphasis
ของผู้ใช้ควรทริกเกอร์ตามลำดับ ส่งผลให้ฟิลด์upper
ได้รับค่าRECIPE!!!
.- สนาม:
- ส่วนขยายของคุณสามารถรวม hooks ที่ให้ผู้ใช้แทรกตรรกะของตนเองลงในการดำเนินการพื้นฐานของส่วนขยายของคุณ
- Hooks ของผู้ใช้สามารถซิงโครนัสได้ ซึ่งจะบล็อกการดำเนินการของส่วนขยายจนกว่าจะเสร็จสมบูรณ์ ส่วนขยายมักใช้ hooks แบบซิงโครนัสเพื่อดำเนินการประมวลผลล่วงหน้าที่ผู้ใช้กำหนด
- User hooks ยังสามารถเป็นแบบอะซิงโครนัสได้ ดังตัวอย่างด้านบน hooks แบบอะซิงโครนัสสามารถใช้เพื่อเรียกใช้ตรรกะที่ผู้ใช้กำหนดซึ่งไม่สำคัญสำหรับส่วนขยายในการทำงานอย่างถูกต้อง
ข้อมูลมากกว่านี้
เรียนรู้เพิ่มเติมเกี่ยวกับ การเพิ่ม hooks สำหรับตรรกะที่ผู้ใช้กำหนด รวมถึง hooks ทั้งแบบอะซิงโครนัสและซิงโครนัส
8. เพิ่มตัวจัดการเหตุการณ์วงจรชีวิต
ส่วนขยายที่คุณเขียนจนถึงขณะนี้จะประมวลผลข้อความในขณะที่สร้างขึ้น แต่จะเกิดอะไรขึ้นถ้าผู้ใช้ของคุณมีฐานข้อมูลข้อความอยู่แล้วเมื่อติดตั้งส่วนขยาย ส่วนขยาย Firebase มีฟีเจอร์ที่เรียกว่า hooks เหตุการณ์วงจรการใช้ งานที่คุณสามารถใช้เพื่อทริกเกอร์การดำเนินการเมื่อมีการติดตั้ง อัปเดต หรือกำหนดค่าส่วนขยายใหม่ ในส่วนนี้ คุณจะใช้ hooks เหตุการณ์วงจรการใช้งานเพื่อทดแทนฐานข้อมูลข้อความที่มีอยู่ของโปรเจ็กต์ด้วยข้อความตัวพิมพ์ใหญ่เมื่อผู้ใช้ติดตั้งส่วนขยายของคุณ
Firebase Extensions ใช้งาน Cloud Tasks เพื่อเรียกใช้ตัวจัดการเหตุการณ์วงจรการใช้งานของคุณ คุณกำหนดตัวจัดการเหตุการณ์โดยใช้ฟังก์ชันคลาวด์ เมื่อใดก็ตามที่อินสแตนซ์ของส่วนขยายของคุณไปถึงเหตุการณ์วงจรการใช้งานที่รองรับ หากคุณได้กำหนดตัวจัดการ อินสแตนซ์นั้นจะเพิ่มตัวจัดการลงในคิว Cloud Tasks จากนั้น Cloud Tasks จะดำเนินการจัดการแบบอะซิงโครนัส ในขณะที่ตัวจัดการเหตุการณ์วงจรการทำงานกำลังทำงานอยู่ คอนโซล Firebase จะรายงานให้ผู้ใช้ทราบว่าอินสแตนซ์ส่วนขยายมีงานการประมวลผลอยู่ระหว่างดำเนินการ ขึ้นอยู่กับฟังก์ชันตัวจัดการของคุณในการรายงานสถานะที่กำลังดำเนินอยู่และงานเสร็จสมบูรณ์กลับไปยังผู้ใช้
หากต้องการเพิ่มตัวจัดการเหตุการณ์วงจรการใช้งานที่ทดแทนข้อความที่มีอยู่ ให้ทำดังต่อไปนี้:
กำหนด Cloud Function ใหม่ที่ถูกกระตุ้นโดยเหตุการณ์คิวงาน:
ฟังก์ชั่น/index.js
import { tasks } from "firebase-functions/v1"; import { getDatabase } from "firebase-admin/database"; import { getExtensions } from "firebase-admin/extensions"; import { getFunctions } from "firebase-admin/functions"; export const backfilldata = tasks.taskQueue().onDispatch(async () => { const batch = await getDatabase() .ref(process.env.MESSAGE_PATH) .parent.parent.orderByChild("upper") .limitToFirst(20) .get(); const promises = []; for (const key in batch.val()) { const msg = batch.child(key); if (msg.hasChild("original") && !msg.hasChild("upper")) { const upper = msg.child("original").val().toUpperCase(); promises.push(msg.child("upper").ref.set(upper)); } } await Promise.all(promises); if (promises.length > 0) { const queue = getFunctions().taskQueue( "backfilldata", process.env.EXT_INSTANCE_ID ); return queue.enqueue({}); } else { return getExtensions() .runtime() .setProcessingState("PROCESSING_COMPLETE", "Backfill complete."); } });
โปรดสังเกตว่าฟังก์ชันจะประมวลผลเรกคอร์ดเพียงไม่กี่รายการเท่านั้นก่อนที่จะเพิ่มตัวเองกลับไปยังคิวงาน นี่เป็นกลยุทธ์ที่ใช้กันทั่วไปเพื่อจัดการกับงานการประมวลผลที่ไม่สามารถทำได้ภายในกรอบเวลาหมดเวลาของฟังก์ชันคลาวด์ เนื่องจากคุณไม่สามารถคาดเดาได้ว่าผู้ใช้อาจมีข้อความอยู่ในฐานข้อมูลอยู่แล้วเมื่อติดตั้งส่วนขยายของคุณจำนวนเท่าใด กลยุทธ์นี้จึงเหมาะสม
ในไฟล์
extension.yaml
ให้ประกาศฟังก์ชันทดแทนของคุณเป็นทรัพยากรส่วนขยายที่มีคุณสมบัติtaskQueueTrigger
ดังนี้resources: - name: makeuppercase ... - name: backfilldata type: firebaseextensions.v1beta.function description: >- Backfill existing messages with uppercase versions properties: runtime: "nodejs18" taskQueueTrigger: {}
จากนั้นประกาศฟังก์ชันเป็นตัวจัดการสำหรับเหตุการณ์
onInstall
lifecycle:lifecycleEvents: onInstall: function: backfilldata processingMessage: Uppercasing existing messages
แม้ว่าการทดแทนข้อความที่มีอยู่จะดี แต่ส่วนขยายก็ยังสามารถทำงานได้หากไม่มี ในสถานการณ์เช่นนี้ คุณควรทำให้การรันตัวจัดการเหตุการณ์รอบการใช้งานเป็นทางเลือก
โดยเพิ่มพารามิเตอร์ใหม่ลงใน
extension.yaml
:- param: DO_BACKFILL label: Backfill existing messages description: >- Generate uppercase versions of existing messages? type: select required: true options: - label: Yes value: true - label: No value: false
จากนั้นที่จุดเริ่มต้นของฟังก์ชันทดแทน ให้ตรวจสอบค่าของพารามิเตอร์
DO_BACKFILL
และออกก่อนกำหนดหากไม่ได้ตั้งค่าไว้:ฟังก์ชั่น/index.js
if (!process.env.DO_BACKFILL) { return getExtensions() .runtime() .setProcessingState("PROCESSING_COMPLETE", "Backfill skipped."); }
จากการเปลี่ยนแปลงข้างต้น ส่วนขยายจะแปลงข้อความที่มีอยู่เป็นตัวพิมพ์ใหญ่เมื่อติดตั้งแล้ว
จนถึงจุดนี้ คุณได้ใช้โปรแกรมจำลองส่วนขยายเพื่อพัฒนาส่วนขยายของคุณและทดสอบการเปลี่ยนแปลงที่กำลังดำเนินอยู่ อย่างไรก็ตาม โปรแกรมจำลองส่วนขยายจะข้ามขั้นตอนการติดตั้ง ดังนั้นเพื่อทดสอบตัวจัดการเหตุการณ์ onInstall
คุณจะต้องติดตั้งส่วนขยายในโปรเจ็กต์จริง แต่นั่นก็เป็นเช่นนั้น เนื่องจากด้วยการเพิ่มฟีเจอร์ทดแทนอัตโนมัตินี้ ส่วนขยายบทแนะนำจึงเสร็จสมบูรณ์ด้วยโค้ดแล้ว!
เหตุการณ์วงจรการใช้งานจะถูกทริกเกอร์เมื่อผู้ใช้ทำงานการจัดการส่วนขยายบางอย่าง:
- การติดตั้งอินสแตนซ์ของส่วนขยาย
- การอัปเดตอินสแตนซ์ของส่วนขยายเป็นเวอร์ชันใหม่
- การกำหนดค่าอินสแตนซ์ของส่วนขยายใหม่
คุณสามารถกำหนดฟังก์ชันที่จะทริกเกอร์เหตุการณ์วงจรการใช้งานของส่วนขยายได้
ใช้รันไทม์ API ส่วนขยายของ Admin SDK เพื่อรายงานสถานะของตัวจัดการเหตุการณ์วงจรการใช้งานกลับไปยังผู้ใช้ ผู้ใช้จะเห็นสถานะการประมวลผลปัจจุบันของส่วนขยายในคอนโซล Firebase
ฟังก์ชันที่ทำงานบนฐานข้อมูลทั้งหมดของคุณ (เช่น การดำเนินการทดแทน) มักจะไม่เสร็จสมบูรณ์ก่อนที่ฟังก์ชันคลาวด์จะหมดเวลา คุณสามารถหลีกเลี่ยงปัญหานี้ได้โดยการแบ่งงานของคุณออกเป็นการเรียกใช้ฟังก์ชันต่างๆ
หากส่วนขยายของคุณมีตัวจัดการเหตุการณ์วงจรการใช้งานที่ไม่สำคัญสำหรับส่วนขยายในการทำงาน คุณควรกำหนดค่าการดำเนินการของตัวจัดการที่ผู้ใช้กำหนดได้
ข้อมูลมากกว่านี้
เรียนรู้เพิ่มเติมเกี่ยวกับ การจัดการเหตุการณ์วงจรชีวิตของส่วนขยายของคุณ
9. ปรับใช้ในโปรเจ็กต์ Firebase จริง
แม้ว่าโปรแกรมจำลองส่วนขยายจะเป็นเครื่องมือที่ยอดเยี่ยมสำหรับการวนซ้ำส่วนขยายอย่างรวดเร็วระหว่างการพัฒนา แต่ ณ จุดหนึ่ง คุณคงอยากจะลองใช้มันในโปรเจ็กต์จริง
ในการทำเช่นนั้น ขั้นแรกให้ตั้งค่าโปรเจ็กต์ใหม่โดยเปิดใช้งานบริการบางอย่าง:
- ใน คอนโซล Firebase ให้เพิ่มโปรเจ็กต์ใหม่
- อัปเกรดโปรเจ็กต์ของคุณ เป็นแผน Blaze แบบจ่ายตามการใช้งาน Cloud Functions for Firebase กำหนดให้โปรเจ็กต์ของคุณต้องมีบัญชีสำหรับการเรียกเก็บเงิน ดังนั้นคุณจึงต้องมีบัญชีสำหรับการเรียกเก็บเงินเพื่อติดตั้งส่วนขยายด้วย
- ในโปรเจ็กต์ใหม่ของคุณ ให้เปิดใช้งานฐานข้อมูลแบบเรียลไทม์
- เนื่องจากคุณต้องการทดสอบความสามารถของส่วนขยายในการทดแทนข้อมูลที่มีอยู่ในการติดตั้ง ให้นำเข้าข้อมูลตัวอย่างบางส่วนไปยังอินสแตนซ์ฐานข้อมูลแบบเรียลไทม์ของคุณ:
- ดาวน์โหลด ข้อมูล Seed RTDB บางส่วน
- ในหน้าฐานข้อมูลเรียลไทม์ของคอนโซล Firebase คลิก (เพิ่มเติม) > นำเข้า JSON และเลือกไฟล์ที่คุณเพิ่งดาวน์โหลด
หากต้องการเปิดใช้งานฟังก์ชันทดแทนเพื่อใช้เมธอด
orderByChild
ให้กำหนดค่าฐานข้อมูลเพื่อสร้างดัชนีข้อความตามค่าของupper
:{ "rules": { ".read": false, ".write": false, "messages": { ".indexOn": "upper" } } }
ตอนนี้ติดตั้งส่วนขยายของคุณจากแหล่งท้องถิ่นลงในโปรเจ็กต์ใหม่:
สร้างไดเรกทอรีใหม่สำหรับโครงการ Firebase ของคุณ:
mkdir ~/extensions-live-test && cd ~/extensions-live-test
เริ่มต้นโครงการ Firebase ในไดเร็กทอรีการทำงาน:
firebase init database
เมื่อได้รับแจ้ง ให้เลือกโปรเจ็กต์ที่คุณเพิ่งสร้างขึ้น
ติดตั้งส่วนขยายในโครงการ Firebase ในพื้นที่ของคุณ:
firebase ext:install /path/to/rtdb-uppercase-messages
ที่นี่คุณจะเห็นว่าประสบการณ์ผู้ใช้เป็นอย่างไรเมื่อติดตั้งส่วนขยายโดยใช้เครื่องมือ Firebase CLI อย่าลืมเลือก "ใช่" เมื่อเครื่องมือกำหนดค่าถามว่าคุณต้องการทดแทนฐานข้อมูลที่มีอยู่หรือไม่
หลังจากคุณเลือกตัวเลือกการกำหนดค่าแล้ว Firebase CLI จะบันทึกการกำหนดค่าของคุณในไดเร็กทอรี
extensions
และบันทึกตำแหน่งต้นทางของส่วนขยายในไฟล์firebase.json
ทั้งสองระเบียนนี้เรียกรวมกันว่ารายการ ส่วนขยาย ผู้ใช้สามารถใช้ไฟล์ Manifest เพื่อบันทึกการกำหนดค่าส่วนขยายและปรับใช้กับโปรเจ็กต์ต่างๆปรับใช้การกำหนดค่าส่วนขยายของคุณกับโปรเจ็กต์สดของคุณ:
firebase deploy --only extensions
หากทุกอย่างเป็นไปด้วยดี Firebase CLI ควรอัปโหลดส่วนขยายของคุณไปยังโปรเจ็กต์ของคุณและติดตั้ง หลังจากการติดตั้งเสร็จสมบูรณ์ งานทดแทนจะทำงาน และฐานข้อมูลของคุณจะได้รับการอัปเดตด้วยข้อความตัวพิมพ์ใหญ่ภายในไม่กี่นาที เพิ่มโหนดใหม่ลงในฐานข้อมูลข้อความ และตรวจสอบให้แน่ใจว่าส่วนขยายใช้งานได้กับข้อความใหม่ด้วย
- ผู้ใช้สามารถสร้างรายการส่วนขยายได้โดยใช้คำสั่ง
firebase ext:install
คุณยังสามารถใช้คำสั่งนี้เพื่อติดตั้งส่วนขยายจากแหล่งในเครื่องได้ - ปรับใช้การกำหนดค่าส่วนขยายจากไฟล์ Manifest ไปยังโปรเจ็กต์ที่ใช้งานจริงโดยใช้
firebase deploy
- แม้ว่าจะไม่ได้สาธิตที่นี่ แต่ผู้ใช้ยังสามารถติดตั้งส่วนขยายในโครงการของตนได้จาก Extensions Hub
ข้อมูลมากกว่านี้
ดูเอกสารประกอบผู้ใช้เกี่ยวกับ การจัดการการกำหนดค่าโครงการด้วยรายการส่วนขยาย
10.เขียนเอกสาร
ก่อนที่คุณจะแชร์ส่วนขยายกับผู้ใช้ ตรวจสอบให้แน่ใจว่าคุณได้จัดเตรียมเอกสารเพียงพอเพื่อให้พวกเขาประสบความสำเร็จ
เมื่อคุณเริ่มต้นโปรเจ็กต์ส่วนขยาย Firebase CLI จะสร้างเวอร์ชัน Stub ของเอกสารที่จำเป็นขั้นต่ำ อัปเดตไฟล์เหล่านี้เพื่อให้สะท้อนถึงส่วนขยายที่คุณสร้างขึ้นอย่างถูกต้อง
extension.yaml
คุณได้อัปเดตไฟล์นี้แล้วในขณะที่พัฒนาส่วนขยายนี้ ดังนั้นคุณจึงไม่จำเป็นต้องอัปเดตเพิ่มเติมอีกในขณะนี้
อย่างไรก็ตาม อย่ามองข้ามความสำคัญของเอกสารประกอบที่อยู่ในไฟล์นี้ นอกเหนือจากข้อมูลระบุที่สำคัญของส่วนขยาย เช่น ชื่อ คำอธิบาย ผู้แต่ง ตำแหน่งที่เก็บอย่างเป็นทางการแล้ว ไฟล์ extension.yaml
ยังมีเอกสารประกอบที่ผู้ใช้เห็นสำหรับทุกทรัพยากรและพารามิเตอร์ที่ผู้ใช้กำหนดค่าได้ ข้อมูลนี้จะแสดงต่อผู้ใช้ในคอนโซล Firebase, Extensions Hub และ Firebase CLI
ติดตั้งล่วงหน้า.md
ในไฟล์นี้ ให้ข้อมูลที่ผู้ใช้ต้องการก่อนที่จะติดตั้งส่วนขยายของคุณ: อธิบายสั้นๆ ว่าส่วนขยายทำอะไร อธิบายข้อกำหนดเบื้องต้น และให้ข้อมูลผู้ใช้เกี่ยวกับผลกระทบในการเรียกเก็บเงินของการติดตั้งส่วนขยาย หากคุณมีเว็บไซต์ที่มีข้อมูลเพิ่มเติม นี่ก็เป็นสถานที่ที่ดีในการลิงก์เช่นกัน
ข้อความของไฟล์นี้จะแสดงต่อผู้ใช้ใน Extensions Hub และโดยคำสั่ง firebase ext:info
นี่คือตัวอย่างของไฟล์ PREINSTALL:
Use this extension to automatically convert strings to upper case when added to
a specified Realtime Database path.
This extension expects a database layout like the following example:
"messages": {
MESSAGE_ID: {
"original": MESSAGE_TEXT
},
MESSAGE_ID: {
"original": MESSAGE_TEXT
},
}
When you create new string records, this extension creates a new sibling record
with upper-cased text:
MESSAGE_ID: {
"original": MESSAGE_TEXT,
"upper": UPPERCASE_MESSAGE_TEXT,
}
#### Additional setup
Before installing this extension, make sure that you've
[set up Realtime Database](https://firebase.google.com/docs/database/quickstart)
in your Firebase project.
#### Billing
To install an extension, your project must be on the
[Blaze (pay as you go) plan](https://firebase.google.com/pricing).
- This extension uses other Firebase and Google Cloud Platform services, which
have associated charges if you exceed the service's no-cost tier:
- Realtime Database
- Cloud Functions (Node.js 10+ runtime)
[See FAQs](https://firebase.google.com/support/faq#extensions-pricing)
- If you enable events,
[Eventarc fees apply](https://cloud.google.com/eventarc/pricing).
POSTINSTALL.md
ไฟล์นี้มีข้อมูลที่เป็นประโยชน์สำหรับผู้ใช้หลังจากที่พวกเขาติดตั้งส่วนขยายของคุณสำเร็จแล้ว เช่น ขั้นตอนการตั้งค่าติดตามผล ตัวอย่างของส่วนขยายที่ใช้งานจริง เป็นต้น
เนื้อหาของ POSTINSTALL.md จะแสดงในคอนโซล Firebase หลังจากกำหนดค่าและติดตั้งส่วนขยายแล้ว คุณสามารถอ้างอิงพารามิเตอร์ผู้ใช้ในไฟล์นี้ได้ และจะถูกแทนที่ด้วยค่าที่กำหนดค่าไว้
นี่คือตัวอย่างไฟล์หลังการติดตั้งสำหรับส่วนขยายบทช่วยสอน:
### See it in action
You can test out this extension right away!
1. Go to your
[Realtime Database dashboard](https://console.firebase.google.com/project/${param:PROJECT_ID}/database/${param:PROJECT_ID}/data) in the Firebase console.
1. Add a message string to a path that matches the pattern `${param:MESSAGE_PATH}`.
1. In a few seconds, you'll see a sibling node named `upper` that contains the
message in upper case.
### Using the extension
We recommend adding data by pushing -- for example,
`firebase.database().ref().push()` -- because pushing assigns an automatically
generated ID to the node in the database. During retrieval, these nodes are
guaranteed to be ordered by the time they were added. Learn more about reading
and writing data for your platform (iOS, Android, or Web) in the
[Realtime Database documentation](https://firebase.google.com/docs/database/).
### Monitoring
As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions#monitor)
of your installed extension, including checks on its health, usage, and logs.
CHANGELOG.md
คุณควรบันทึกการเปลี่ยนแปลงที่คุณทำระหว่างการเผยแพร่ส่วนขยายในไฟล์ CHANGELOG.md
เนื่องจากไม่เคยมีการเผยแพร่ส่วนขยายตัวอย่างมาก่อน บันทึกการเปลี่ยนแปลงจึงมีเพียงรายการเดียว:
## Version 0.0.1
Initial release of the _Convert messages to upper case_ extension.
README.md
ส่วนขยายส่วนใหญ่ยังมีไฟล์ Readme เพื่อประโยชน์ของผู้ใช้ที่เข้าชมพื้นที่เก็บข้อมูลของส่วนขยาย คุณสามารถเขียนไฟล์นี้ด้วยมือหรือสร้าง read me โดยใช้คำสั่ง
เพื่อวัตถุประสงค์ของคู่มือนี้ ให้ข้ามการเขียนไฟล์ Readme ไป
เอกสารเพิ่มเติม
เอกสารที่กล่าวถึงข้างต้นคือชุดเอกสารขั้นต่ำที่คุณควรจัดเตรียมให้กับผู้ใช้ ส่วนขยายจำนวนมากต้องการเอกสารที่มีรายละเอียดเพิ่มเติมเพื่อให้ผู้ใช้ใช้งานได้สำเร็จ ในกรณีนี้ คุณควรเขียนเอกสารเพิ่มเติมและโฮสต์ไว้ที่ไหนสักแห่งที่คุณสามารถชี้ให้ผู้ใช้ไปได้
เพื่อวัตถุประสงค์ของคู่มือนี้ ให้ข้ามการเขียนเอกสารที่มีรายละเอียดมากขึ้น
- อย่างน้อยที่สุด ทุกส่วนขยายควรมีเอกสารประกอบผู้ใช้ในไฟล์ต่อไปนี้:
extension.yaml
,PREINSTALL.md
,POSTINSTALL.md
และCHANGELOG.md
- คุณควรจัดเตรียมเอกสารรายละเอียดเพิ่มเติมให้กับผู้ใช้เมื่อจำเป็น
ข้อมูลมากกว่านี้
ดู เอกสารประกอบในการเขียนเอกสาร
11. เผยแพร่บน Extensions Hub
เมื่อส่วนขยายของคุณได้รับโค้ดครบถ้วนและได้รับการจัดทำเป็นเอกสารแล้ว คุณก็พร้อมที่จะแบ่งปันกับผู้คนทั่วโลกบน Extensions Hub แต่เนื่องจากนี่เป็นเพียงบทช่วยสอน คุณอย่าทำอย่างนั้นจริงๆ เริ่มเขียนส่วนขยายของคุณเองโดยใช้สิ่งที่คุณได้เรียนรู้ที่นี่และในเอกสารประกอบของผู้เผยแพร่ส่วนขยาย Firebase Extensions ที่เหลือ และโดยการตรวจสอบแหล่งที่มาของส่วนขยายอย่างเป็นทางการที่เขียนโดย Firebase
เมื่อคุณพร้อมที่จะเผยแพร่ผลงานของคุณบน Extensions Hub ต่อไปนี้คือวิธีดำเนินการ:
- หากคุณกำลังเผยแพร่ส่วนขยายแรกของคุณ ให้ลงทะเบียนเป็นผู้เผยแพร่ส่วนขยาย เมื่อคุณลงทะเบียนเป็นผู้เผยแพร่ส่วนขยาย คุณจะสร้างรหัสผู้เผยแพร่ที่ช่วยให้ผู้ใช้สามารถระบุตัวคุณได้อย่างรวดเร็วในฐานะผู้เขียนส่วนขยายของคุณ
โฮสต์ซอร์สโค้ดของส่วนขยายของคุณในตำแหน่งที่สาธารณะสามารถตรวจสอบได้ เมื่อโค้ดของคุณพร้อมใช้งานจากแหล่งที่มาที่ตรวจสอบได้ Firebase จะสามารถเผยแพร่ส่วนขยายของคุณได้โดยตรงจากตำแหน่งนี้ การทำเช่นนี้ช่วยให้แน่ใจว่าคุณกำลังเผยแพร่ส่วนขยายเวอร์ชันที่เผยแพร่ในปัจจุบัน และช่วยเหลือผู้ใช้โดยอนุญาตให้พวกเขาตรวจสอบโค้ดที่พวกเขากำลังติดตั้งในโครงการของตน
ในปัจจุบันนี้หมายถึงการทำให้ส่วนขยายของคุณพร้อมใช้งานในพื้นที่เก็บข้อมูล GitHub สาธารณะ
อัปโหลดส่วนขยายของคุณไปยัง Extensions Hub โดยใช้คำสั่ง
firebase ext:dev:upload
ไปที่แดชบอร์ดผู้เผยแพร่ของคุณในคอนโซล Firebase ค้นหาส่วนขยายที่คุณเพิ่งอัปโหลด แล้วคลิก "เผยแพร่ไปยัง Extensions Hub" การดำเนินการนี้จะต้องได้รับการตรวจสอบจากเจ้าหน้าที่ตรวจสอบของเรา ซึ่งอาจใช้เวลาสองสามวัน หากได้รับอนุมัติ ส่วนขยายจะถูกเผยแพร่ไปยัง Extensions Hub หากถูกปฏิเสธ คุณจะได้รับข้อความอธิบายเหตุผล จากนั้นคุณสามารถแก้ไขปัญหาที่ได้รับรายงานแล้วส่งเข้ารับการตรวจสอบอีกครั้ง
- หากต้องการแชร์ส่วนขยายบน Extensions Hub คุณต้องลงทะเบียนเป็นผู้เผยแพร่
- จำเป็นต้องมีการเผยแพร่จากแหล่งที่ตรวจสอบได้ และช่วยให้ผู้ใช้มั่นใจได้ว่าโค้ดที่พวกเขากำลังติดตั้งนั้นเป็นโค้ดเดียวกับที่สามารถตรวจสอบได้บน GitHub
- ใช้คำสั่ง
firebase ext:dev:upload
เพื่ออัปโหลดส่วนขยายไปยัง Extensions Hub - ส่งส่วนขยายของคุณเพื่อรับการตรวจทานจากแดชบอร์ดผู้เผยแพร่
ข้อมูลมากกว่านี้
เรียนรู้เพิ่มเติมเกี่ยวกับ การลงทะเบียนเป็นผู้จัดพิมพ์ และ การเผยแพร่ส่วนขยาย