Thêm móc người dùng vào tiện ích mở rộng

Bạn có thể cung cấp cho người dùng cài đặt tiện ích mở rộng của bạn khả năng chèn logic tùy chỉnh của riêng họ vào quá trình thực thi tiện ích mở rộng của bạn. Có hai cách để thực hiện điều này:

  • Sự kiện Eventarc : để cung cấp cho người dùng cách phản ứng không đồng bộ với các sự kiện, bạn có thể xuất bản lên Eventarc. Người dùng có thể triển khai các chức năng xử lý sự kiện, chẳng hạn như gửi thông báo sau khi hoàn thành các tác vụ dài hạn hoặc họ có thể xác định các chức năng xử lý hậu kỳ của riêng mình.

  • Móc đồng bộ : để cung cấp cho người dùng cách thêm logic chặn vào tiện ích mở rộng của bạn, bạn có thể thêm móc đồng bộ tại các điểm được xác định trước trong hoạt động của tiện ích mở rộng. Tại những thời điểm này, bạn chạy chức năng nhà cung cấp người dùng và chỉ tiếp tục sau khi hoàn thành. Các tác vụ tiền xử lý thường thuộc loại này.

Tiện ích mở rộng có thể sử dụng một hoặc cả hai phương pháp.

Sự kiện sự kiện

Để xuất bản các sự kiện từ tiện ích mở rộng:

  1. Khai báo các loại sự kiện bạn sẽ xuất bản trong tệp 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

    Mã định danh type được tạo thành từ một số trường được phân cách bằng dấu chấm. Các trường ID nhà xuất bản , tên tiện ích mở rộng và tên sự kiện là bắt buộc. Trường phiên bản được khuyến nghị. Chọn tên sự kiện duy nhất và mang tính mô tả cho từng loại sự kiện bạn xuất bản.

    Ví dụ: tiện ích mở rộng storage-resize-images khai báo một loại sự kiện duy nhất:

    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.

    Người dùng sẽ có thể chọn sự kiện nào để đăng ký khi họ cài đặt tiện ích mở rộng.

  2. Trong các hàm mở rộng của bạn, hãy nhập API Eventarc từ SDK quản trị và khởi tạo kênh sự kiện bằng cài đặt cài đặt của người dùng. Các cài đặt này được hiển thị bằng cách sử dụng các biến môi trường sau:

    • EVENTARC_CHANNEL : tên đủ điều kiện của kênh Eventarc mà người dùng đã chọn để xuất bản sự kiện.
    • EXT_SELECTED_EVENTS : danh sách các loại sự kiện được phân tách bằng dấu phẩy mà người dùng đã chọn xuất bản. Khi bạn khởi tạo kênh có giá trị này, SDK quản trị sẽ tự động lọc ra các sự kiện mà người dùng không chọn.
    • EVENTARC_CLOUD_EVENT_SOURCE : mã định danh nguồn Sự kiện đám mây. SDK quản trị tự động chuyển giá trị này vào trường source của sự kiện đã xuất bản. Bạn thường không cần phải sử dụng biến này một cách rõ ràng.

    Nếu sự kiện không được bật khi cài đặt, các biến này sẽ không được xác định. Bạn chỉ có thể sử dụng thực tế này để khởi tạo kênh sự kiện khi sự kiện được bật:

    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. Xuất bản sự kiện lên kênh tại các điểm trong tiện ích mở rộng mà bạn muốn hiển thị cho người dùng. Ví dụ:

    // 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. Ghi lại các sự kiện bạn xuất bản ở dạng tệp PREINSTALL hoặc POSTINSTALL.

    Đối với mỗi sự kiện, hãy ghi lại những nội dung sau:

    • Mục đích dự định của nó
    • Điểm trong logic của tiện ích mở rộng của bạn mà nó chạy
    • Dữ liệu đầu ra nó bao gồm
    • Điều kiện thực hiện

    Ngoài ra, hãy cảnh báo người dùng không thực hiện bất kỳ hành động nào trong trình xử lý sự kiện có thể kích hoạt cùng một tiện ích mở rộng, dẫn đến vòng lặp vô hạn.

Khi bạn xuất bản sự kiện từ tiện ích mở rộng, người dùng có thể triển khai trình xử lý sự kiện để phản hồi bằng logic tùy chỉnh.

Ví dụ: ví dụ sau sẽ xóa hình ảnh gốc sau khi nó được thay đổi kích thước. Lưu ý rằng trình xử lý ví dụ này sử dụng thuộc tính subject của sự kiện, trong trường hợp này là tên tệp gốc của hình ảnh.

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

Xem Trình kích hoạt sự kiện tùy chỉnh để biết thêm thông tin.

Ví dụ

Tiện ích mở rộng Thay đổi kích thước hình ảnh chính thức cung cấp một hook không đồng bộ bằng cách xuất bản lên Eventarc sau khi thay đổi kích thước hình ảnh.

Móc đồng bộ

Khi bạn muốn cung cấp cho người dùng một hook phải hoàn thành thành công để một trong các chức năng mở rộng của bạn hoạt động, hãy sử dụng hook đồng bộ .

Một hook đồng bộ gọi Hàm đám mây có thể gọi HTTPS do người dùng xác định và chờ hoàn thành (có thể có giá trị được trả về) trước khi tiếp tục. Lỗi trong hàm do người dùng cung cấp sẽ dẫn đến lỗi trong hàm mở rộng.

Để hiển thị một hook đồng bộ:

  1. Thêm tham số vào tiện ích mở rộng của bạn để cho phép người dùng định cấu hình tiện ích mở rộng bằng URL tới Chức năng đám mây tùy chỉnh của họ. Ví dụ:

    - 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. Tại thời điểm trong tiện ích mở rộng nơi bạn muốn hiển thị hook, hãy gọi hàm bằng URL của nó. Ví dụ:

    const functions = require('firebase-functions');
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. Ghi lại bất kỳ hook nào bạn cung cấp trong tệp PREINSTALL hoặc POSTINSTALL.

    Đối với mỗi hook, hãy ghi lại những thông tin sau:

    • Mục đích dự định của nó
    • Điểm trong logic của tiện ích mở rộng của bạn mà nó chạy
    • Đầu vào và đầu ra dự kiến
    • Các điều kiện (hoặc tùy chọn) để thực hiện nó

    Ngoài ra, hãy cảnh báo người dùng không thực hiện bất kỳ hành động nào trong hàm hook vì có thể kích hoạt cùng một tiện ích mở rộng, dẫn đến vòng lặp vô hạn.

Ví dụ

Tiện ích mở rộng Algolia Search cung cấp một hook đồng bộ để gọi hàm biến đổi do người dùng cung cấp trước khi ghi vào Algolia.