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

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

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

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

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

เหตุการณ์ 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: ตัวระบุแหล่งที่มาของ Cloud Event Admin SDK จะส่งค่านี้ในฟิลด์ source ของเหตุการณ์ที่เผยแพร่โดยอัตโนมัติ โดยปกติแล้วคุณไม่จำเป็นต้องใช้ตัวแปรนี้อย่างชัดเจน

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

   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();
    });

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

ตัวอย่าง

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

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

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

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

วิธีแสดงฮุกแบบซิงโครนัส

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. ในจุดของส่วนขยายที่ต้องการแสดงฮุก ให้เรียกใช้ฟังก์ชันโดยใช้ 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. จัดทำเอกสารฮุกที่พร้อมใช้งานในไฟล์ PREINSTALL หรือ POSTINSTALL

   สำหรับฮุกแต่ละฮุก ให้จัดทำเอกสารเกี่ยวกับข้อมูลต่อไปนี้

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

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

ตัวอย่าง

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