ติดตั้งส่วนขยาย Firebase

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

อย่าลืมตรวจสอบความแตกต่างของ การดำเนินการที่รองรับสำหรับวิธีการติดตั้งแต่ละวิธี


การติดตั้งโดยใช้ SDK ที่สร้างขึ้นโดยอัตโนมัติเป็นตัวเลือกใหม่สำหรับการติดตั้งและ การจัดการส่วนขยาย ตัวเลือกนี้ช่วยให้คุณใช้ CLI เพื่อสร้าง Node SDK สำหรับส่วนขยายเวอร์ชันที่เฉพาะเจาะจงโดยอัตโนมัติ ซึ่งคุณสามารถนำเข้าเป็น การอ้างอิงปกติใน Cloud Functions ของ JavaScript หรือ TypeScript ได้

SDK ที่สร้างขึ้นโดยอัตโนมัตินี้มีองค์ประกอบต่อไปนี้

  • อินเทอร์เฟซที่แสดงพารามิเตอร์ของส่วนขยายและการประกาศประเภท สำหรับพารามิเตอร์ประเภทที่ไม่ใช่แบบดั้งเดิมส่วนใหญ่
  • ฟังก์ชันตัวสร้างที่เริ่มต้นอินสแตนซ์ของส่วนขยาย
  • คลาสส่วนขยายที่มีทริกเกอร์ Eventarc สำหรับเหตุการณ์ทั้งหมดที่ส่วนขยายปล่อยออกมา

เมื่อสร้าง SDK ของส่วนขยายแล้ว การกำหนดค่าทั้งหมดของส่วนขยาย จะเกิดขึ้นในโค้ด

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


หากต้องการติดตั้งหรือจัดการส่วนขยาย คุณต้องได้รับมอบหมายบทบาทใดบทบาทหนึ่งต่อไปนี้ เจ้าของหรือผู้แก้ไข หรือ ผู้ดูแลระบบ Firebase

หากต้องการติดตั้งส่วนขยาย โปรเจ็กต์ของคุณต้องใช้แพ็กเกจ Blaze (จ่ายเมื่อใช้) แม้ว่าจะไม่มีค่าใช้จ่ายในการติดตั้งส่วนขยาย แต่ระบบอาจเรียกเก็บเงินสำหรับการใช้บริการ Firebase หรือบริการระบบคลาวด์ เช่น Cloud Secret Manager หากการใช้งานเกินโควต้าของรุ่นฟรีของบริการ

ก่อนเริ่มต้น

  1. เพิ่ม Firebase ลงในโปรเจ็กต์ หากยังไม่ได้เพิ่ม

  2. หากยังไม่ได้ดำเนินการ ให้อัปเกรดโปรเจ็กต์เป็นแพ็กเกจ Blaze (จ่ายตามการใช้งาน)

  3. ติดตั้งหรืออัปเดตเป็น Firebase CLI เวอร์ชันล่าสุด

  4. จดรหัสโปรเจ็กต์ Firebase หรือนามแฝงโปรเจ็กต์ที่กำหนดค่าไว้ก่อนหน้านี้

ขั้นตอนที่ 1: ดูข้อมูลโดยละเอียดเกี่ยวกับส่วนขยาย

ขั้นตอนนี้ไม่บังคับ แต่เราขอแนะนำเป็นอย่างยิ่งให้ดำเนินการ

ก่อนติดตั้ง Firebase Extension เราขอแนะนำให้คุณ ตรวจสอบข้อมูลโดยละเอียดเกี่ยวกับส่วนขยาย ซึ่งรวมถึงข้อมูลต่อไปนี้

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

หากต้องการดูข้อมูลโดยละเอียดของส่วนขยาย ให้ทำดังนี้

  1. ตรวจสอบว่าคุณได้ ตั้งค่า สภาพแวดล้อม และ เลือก ส่วนขยายแล้ว

  2. เรียกใช้คำสั่ง extension-info จากที่ใดก็ได้ในคอมพิวเตอร์

    firebase ext:info publisher-id/extension-id

    ต้องระบุอาร์กิวเมนต์ publisher-id และ extension-id โดยดูได้ในหน้ารายละเอียดการติดตั้งล่วงหน้าของส่วนขยาย

ขั้นตอนที่ 2: ติดตั้งส่วนขยาย

ก่อนการติดตั้ง โปรดอ่านข้อกำหนดพื้นฐานของส่วนขยาย (เช่น API ที่เปิดใช้ ทรัพยากรที่สร้าง สิทธิ์เข้าถึงที่ให้ ฯลฯ) และข้อกำหนดในการเรียกเก็บเงิน

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

เริ่มต้นใช้งาน Cloud Functions for Firebase

หากคุณกำลังเริ่มโปรเจ็กต์ใหม่หรือโปรเจ็กต์ยังไม่ได้ใช้ Cloud Functions for Firebase ให้เรียกใช้คำสั่งต่อไปนี้ init functions

cd your-project
firebase init functions

เลือก TypeScript หรือ JavaScript เป็นภาษาของฟังก์ชัน

หากโปรเจ็กต์ของคุณเริ่มต้นใช้งาน Cloud Functions แล้ว โปรดตรวจสอบว่าคุณใช้แพ็กเกจ firebase-functions เวอร์ชัน 5.1.0 ขึ้นไป

cd your-project/functions
npm upgrade --save firebase-functions

หากใช้ ESLint คุณอาจต้องยกเว้น SDK ที่สร้างขึ้นจากการกำหนดค่า (.eslintrc.js) ด้วย

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

สร้าง SDK ของส่วนขยาย

เรียกใช้ext:sdk:installจากไดเรกทอรี Firebase ในเครื่อง

firebase ext:sdk:install publisher-id/extension-id@version

เช่น หากต้องการติดตั้งส่วนขยาย firestore-send-email เวอร์ชัน 0.1.34 ให้ทำดังนี้

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id และ extension-id เป็นข้อมูลที่จำเป็นและดูได้ในหน้ารายละเอียดก่อนการติดตั้งของส่วนขยายใน extensions.dev ส่วน @version เป็นข้อมูลที่ไม่บังคับ หากคุณละเว้นส่วนนี้ เครื่องมือจะติดตั้งเวอร์ชันล่าสุด

คุณระบุตัวเลือกได้ 2 รายการ ดังนี้

  • --force: ดำเนินการต่อไปนี้ทั้งหมดโดยไม่ต้องมีการยืนยันเพิ่มเติม

    • สร้าง SDK โดยอัตโนมัติแม้ว่าจะมีการสร้าง SDK สำหรับส่วนขยายและเวอร์ชันเดียวกันแล้วก็ตาม
    • ติดตั้งแพ็กเกจ SDK ที่สร้างขึ้นโดยอัตโนมัติในโปรเจ็กต์ Node ของ Cloud Functions

  • --codebase: ชื่อของโค้ดเบสที่จะเพิ่ม SDK หากไม่ได้ระบุ คำสั่งจะเพิ่ม SDK ลงในโค้ดเบสเริ่มต้น functions

คำสั่งนี้จะสร้างแพ็กเกจ Node ที่มี SDK ซึ่งสร้างขึ้นโดยอัตโนมัติสำหรับส่วนขยาย และเพิ่มลงในฐานของโค้ด Cloud Functions ของโปรเจ็กต์ ในโค้ดเบสเริ่มต้น (functions) ระบบจะบันทึก SDK ไว้ที่ตำแหน่งต่อไปนี้ 

functions/generated/extensions/publisher-id/extension-id/version

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

กำหนดค่าอินสแตนซ์ส่วนขยาย

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

  1. ในแหล่งที่มาของ Cloud Functions ให้นำเข้าตัวสร้างโดยใช้คำสั่ง ที่พิมพ์โดยคำสั่ง ext:sdk:install

    TypeScript

    ตัวอย่างเช่น หากคุณสร้าง SDK สำหรับส่วนขยาย firestore-send-email ข้อความ import จะมีลักษณะดังนี้

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    หากส่วนขยายต้องใช้ค่าลับ เช่น รหัสผ่าน คุณจะต้องใช้ฟังก์ชัน defineSecret จาก Cloud Functions SDK ด้วย

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    ตัวอย่างเช่น หากคุณสร้าง SDK สำหรับส่วนขยาย firestore-send-email ข้อความ require จะมีลักษณะดังนี้ 

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    หากส่วนขยายต้องใช้ค่าลับ เช่น รหัสผ่าน คุณจะต้องใช้ฟังก์ชัน defineSecret จาก Cloud Functions SDK ด้วย

    const { defineSecret } = require('firebase-functions/params');

  2. สำหรับแต่ละอินสแตนซ์ที่คุณต้องการกำหนดค่า ให้เรียกใช้ฟังก์ชันตัวสร้างและ ส่งออกผลลัพธ์

    กำหนดรหัสที่ไม่ซ้ำกันให้กับแต่ละอินสแตนซ์ โดยมีเฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข และขีดกลาง

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    โปรดทราบว่าต้องระบุค่าลับโดยใช้ฟังก์ชัน defineSecret

  3. จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อทำให้ส่วนขยายที่คุณกำหนดค่าใช้งานได้ 

    firebase deploy --only functions --project=projectId-or-alias

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

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

ขั้นตอนที่ 3: ตั้งค่าหลังการติดตั้งให้เสร็จสมบูรณ์

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

คุณยังดูวิธีการเหล่านี้ได้ในPOSTINSTALL.mdไฟล์ที่รวมอยู่ใน ไดเรกทอรีแหล่งที่มาของส่วนขยาย

สร้างทรัพยากร Firebase

หากคุณกำหนดค่าส่วนขยายให้ใช้ทรัพยากร Firebase (Cloud Firestore คอลเล็กชัน Realtime Database เส้นทาง Cloud Storage บัคเก็ต) ที่ยังไม่มีอยู่ ให้สร้างทรัพยากรเหล่านั้นก่อนใช้ส่วนขยาย

สร้างตัวแฮนเดิลเหตุการณ์ Eventarc

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

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

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

คุณต้องส่งออกตัวแฮนเดิลเหตุการณ์พร้อมกับอินสแตนซ์ส่วนขยาย

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

ติดตั้งอินสแตนซ์ส่วนขยายหลายรายการ

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

เรียกใช้ฟังก์ชันตัวสร้างของ SDK ที่สร้างขึ้นโดยอัตโนมัติ 1 ครั้งสำหรับทุกอินสแตนซ์ที่คุณต้องการติดตั้งและกำหนดค่า

ขั้นตอนถัดไป