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

คุณสามารถให้สิทธิ์แก่ผู้ใช้ที่ติดตั้งส่วนขยายของคุณในการแทรกตรรกะที่กำหนดเองลงในการดำเนินการส่วนขยายของคุณได้ ซึ่งทำได้ 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 แบบซิงโครนัส

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

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

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

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

   - 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