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

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

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


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

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 ครั้งสําหรับอินสแตนซ์แต่ละรายการที่ต้องการติดตั้งและกำหนดค่า

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