เพิ่มฮุกผู้ใช้ลงในส่วนขยาย

คุณสามารถให้สิทธิ์แก่ผู้ใช้ที่ติดตั้งส่วนขยายของคุณในการแทรกตรรกะที่กำหนดเองลงในการดำเนินการส่วนขยายของคุณได้ ซึ่งทำได้ 2 วิธีดังนี้

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

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

ส่วนขยายจะใช้วิธีใดวิธีหนึ่งหรือทั้ง 2 วิธีก็ได้

เหตุการณ์ Eventarc

วิธีเผยแพร่กิจกรรมจากส่วนขยาย

  1. ประกาศประเภทเหตุการณ์ที่คุณจะเผยแพร่ในไฟล์ extension.yaml ดังนี้

    events:
  - type: publisher-id.extension-name.version.event-name
    description: event-description
  - type: publisher-id.extension-name.version.another-event-name
    description: another-event-description

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

    เช่น ส่วนขยาย storage-resize-images ประกาศประเภทเหตุการณ์เดียว

    events:
  - type: firebase.extensions.storage-resize-images.v1.complete
    description: |
      Occurs when image resizing completes. The event will contain further
      details about specific formats and sizes.

    ผู้ใช้จะเลือกกิจกรรมที่ต้องการติดตามได้เมื่อ ติดตั้งส่วนขยาย

  2. ในฟังก์ชันส่วนขยาย ให้นำเข้า Eventarc API จาก Admin SDK และเริ่มต้นช่องเหตุการณ์โดยใช้การตั้งค่าการติดตั้งของผู้ใช้ การตั้งค่าเหล่านี้จะแสดงโดยใช้ตัวแปรสภาพแวดล้อมต่อไปนี้

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

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

    import * as admin from "firebase-admin";
import {getEventarc} from 'firebase-admin/eventarc';

admin.initializeApp();

// 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,
  });

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

    // If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel && eventChannel.publish({
    type: 'firebase.extensions.storage-resize-images.v1.complete',
    subject: filename,  // the name of the original file
    data: {
      // ...
    }
});

  4. บันทึกเหตุการณ์ที่คุณเผยแพร่ในไฟล์ PREINSTALL หรือ POSTINSTALL

    สำหรับแต่ละเหตุการณ์ ให้บันทึกข้อมูลต่อไปนี้

    • วัตถุประสงค์ที่ตั้งใจไว้
    • จุดในตรรกะของส่วนขยายที่ทำงาน
    • ข้อมูลเอาต์พุตที่รวมอยู่
    • เงื่อนไขในการดำเนินการ

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

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

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

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

ดูข้อมูลเพิ่มเติมได้ที่ทริกเกอร์เหตุการณ์ที่กําหนดเอง

ตัวอย่าง

ส่วนขยายปรับขนาดรูปภาพอย่างเป็นทางการ มี Hook แบบไม่พร้อมกันโดยการเผยแพร่ไปยัง Eventarc หลังจากปรับขนาดรูปภาพ

ฮุกแบบซิงโครนัส

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

Hook แบบซิงโครนัสจะเรียกใช้ HTTPS Callable Cloud Function ที่ผู้ใช้กำหนด และรอให้เสร็จสมบูรณ์ (อาจมีค่าที่ส่งคืน) ก่อนที่จะดำเนินการต่อ ข้อผิดพลาดในฟังก์ชันที่ผู้ใช้ระบุ ส่งผลให้เกิดข้อผิดพลาดในฟังก์ชันส่วนขยาย

วิธีเปิดเผย Hook แบบซิงโครนัส

  1. เพิ่มพารามิเตอร์ลงในส่วนขยายเพื่อให้ผู้ใช้กำหนดค่าส่วนขยายด้วย URL ไปยัง Cloud Function ที่กำหนดเองได้ เช่น

    - param: PREPROCESSING_FUNCTION
  label: Pre-processing function URL
  description: >
    An HTTPS callable function that will be called to transform the input data
    before it is processed by this function.
  type: string
  example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
  required: false

  2. ในจุดที่ต้องการแสดง Hook ในส่วนขยาย ให้เรียกฟังก์ชันโดยใช้ URL เช่น

    const functions = require('firebase-functions/v1');
const fetch = require('node-fetch');

const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;

exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
    .onWrite((change, context) => {
      // PREPROCESSING_FUNCTION hook begins here.
      // If a preprocessing function is defined, call it before continuing.
      if (preprocessFunctionURL) {
        try {
          await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
        } catch (e) {
          // Preprocessing failure causes the function to fail.
          functions.logger.error("Preprocessor error:", e);
          return;
        }
      }
      // End of PREPROCESSING_FUNCTION hook.

      // Main function logic follows.
      // ...
    });

  3. บันทึก Hook ที่คุณทำให้พร้อมใช้งานในไฟล์ PREINSTALL หรือ POSTINSTALL

    สำหรับแต่ละฮุก ให้บันทึกข้อมูลต่อไปนี้

    • วัตถุประสงค์ที่ตั้งใจไว้
    • จุดในตรรกะของส่วนขยายที่ทำงาน
    • อินพุตและเอาต์พุตที่คาดไว้
    • เงื่อนไข (หรือตัวเลือก) ในการดำเนินการ

    นอกจากนี้ ให้เตือนผู้ใช้ไม่ให้ดำเนินการใดๆ ในฟังก์ชัน Hook ที่อาจทริกเกอร์ส่วนขยายเดียวกัน ซึ่งจะส่งผลให้เกิดลูป ไม่สิ้นสุด

ตัวอย่าง

ส่วนขยาย Algolia Search มี Hook แบบซิงโครนัสสำหรับเรียกใช้ฟังก์ชันการแปลงที่ผู้ใช้ระบุ ก่อนที่จะเขียนไปยัง Algolia