在擴充功能中新增使用者掛鉤

您可以讓安裝擴充功能的使用者， 自訂邏輯有兩種方法 完成這項動作：

  • Eventarc 事件：為使用者提供非同步回應 事件即可發布至 Eventarc使用者可以部署事件處理常式 舉例來說，這類函式會在長時間執行後傳送通知 也能定義自己的後續處理函式

  • 同步掛鉤：讓使用者能在您的 擴充功能，您可以在 擴充功能的作業。這時，您要執行 User-provider 函式 並等到作業完成後再繼續預先處理工作往往涉及到 這個類別

擴充功能可以同時使用任一方法，或同時使用兩者。

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 ID 是由數個以點分隔的欄位所組成。 發布商 ID、擴充功能名稱和事件名稱欄位 這通常代表交易 不會十分要求關聯語意建議使用版本欄位。選擇不重複的描述性字詞 所發布每種事件類型的事件名稱。

    例如 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. 在擴充功能函式中，從 Admin SDK 匯入 Eventarc API ，然後使用使用者的安裝設定將事件管道初始化。 您可以透過下列環境變數公開這些設定：

    • EVENTARC_CHANNEL：Eventarc 管道的完整名稱 也就是使用者選擇發布事件的時間
    • EXT_SELECTED_EVENTS：使用者的事件類型清單 (以半形逗號分隔) 最終決定發布使用這個值初始化管道時， Admin SDK 會自動篩除使用者未選取的事件。
    • EVENTARC_CLOUD_EVENT_SOURCE：Cloud 事件來源 ID。 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.appspot.com")
          .file(event.subject)
          .delete();
    });

詳情請參閱「自訂事件觸發條件」一文 可能不準確或不適當

範例

官方的 Resize Images 擴充功能 發布至 Eventarc，即可提供非同步掛鉤 調整圖片大小

同步掛鉤

您想為使用者提供必須成功完成的掛鉤 如要運作其中一個擴充功能函式，請使用同步掛鉤。

同步掛鉤呼叫使用者定義的 HTTPS 可呼叫雲端 函式，並等待完成 (可能 )，然後再繼續。使用者提供的函式發生錯誤 會導致擴充功能函式發生錯誤。

如要公開同步掛鉤：

  1. 在擴充功能中加入參數，讓使用者設定 自訂 Cloud 函式的網址。例如：

    - 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. 在擴充功能中要顯示掛鉤的位置，呼叫 函式。例如：

    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 搜尋擴充功能 提供同步掛鉤，以呼叫使用者提供的轉換函式 有尚未寫完的消息