Thêm nội dung hấp dẫn người dùng vào một tiện ích

Bạn có thể cho phép những người dùng cài đặt tiện ích của bạn chèn tiện ích của riêng họ logic tuỳ chỉnh vào quá trình thực thi tiện ích. Có 2 cách thực hiện việc 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 sự kiện, bạn có thể xuất bản lên Eventarc. Người dùng có thể triển khai trình xử lý sự kiện các chức năng, chẳng hạn như gửi thông báo sau khi chạy trong thời gian dài công việc hoàn thành hoặc có thể xác định chức năng hậu xử lý của riêng mình.

  • Hook đồng bộ: để cung cấp cho người dùng cách thêm logic chặn vào bạn có thể thêm các hook đồng bộ tại các điểm được xác định trước trong hoạt động của tiện ích. Tại những thời điểm này, bạn chạy hàm người dùng-cung cấp và chỉ tiến hành sau khi hoàn tất. Các công việc trước xử lý thường nằm trong danh mục này.

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

Sự kiện Eventarc

Cách xuất bản sự kiện qua một tiện ích:

  1. Khai báo các loại sự kiện bạn sẽ công bố 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

    Giá trị nhận dạng type được tạo từ một số trường được phân tách bằng dấu chấm. Chiến lược phát hành đĩa đơn Các trường mã nhà xuất bản, tên tiện ích và tên sự kiện đều là là bắt buộc. Bạn nên dùng trường phiên bản. Chọn một tiêu đề độc đáo và mang tính mô tả tên sự kiện cho từng loại sự kiện mà bạn xuất bản.

    Ví dụ: tiện ích 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 đăng ký theo dõi những sự kiện nào khi cài đặt tiện ích đó.

  2. Trong các hàm tiện ích, hãy nhập Eventarc API từ Admin SDK và khởi chạy kênh sự kiện bằng cách sử dụng chế độ cài đặt của người dùng. Các chế độ 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 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 dành cho quản trị viên tự động lọc ra những sự kiện mà người dùng không chọn.
    • EVENTARC_CLOUD_EVENT_SOURCE: Giá trị nhận dạng nguồn của Sự kiện trên đám mây. Chiến lược phát hành đĩa đơn SDK dành cho quản trị viên tự động chuyển giá trị này vào trường source của các sự kiện đã xuất bản. Thường thì bạn không cần phải sử dụng biến.

    Nếu các sự kiện chưa được bật khi cài đặt, các biến này sẽ được chưa xác định. Bạn chỉ có thể sử dụng dữ kiện này để khởi tạo một 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 phần 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 mà bạn xuất bản, trong PREINSTALL hoặc POSTINSTALL .

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

    • Mục đích dự kiến
    • Điểm trong logic của tiện ích mà nó chạy
    • Dữ liệu đầu ra có trong đó
    • Điều kiện để thực thi mã

    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 sự kiện của họ có thể kích hoạt cùng một tiện ích, dẫn đến tình trạng vòng lặp.

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

Ví dụ: ví dụ sau đây xoá hình ảnh gốc sau khi đã đổi kích thước. Xin lưu ý rằng trình xử lý mẫu 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 bài viết Trình kích hoạt sự kiện tuỳ chỉnh để tìm hiểu thêm của bạn.

Ví dụ

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

Hook đồng bộ

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

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

Cách hiển thị một hook đồng bộ:

  1. Thêm một tham số vào tiện ích để cho phép người dùng định cấu hình bằng URL đến hàm đám mây tuỳ 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à bạn muốn hiển thị nội dung hấp dẫn, hãy gọi phương thức bằng cách sử dụng URL của nó. Ví dụ:

    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. Ghi lại mọi nội dung hấp dẫn mà bạn cung cấp trong phần PREINSTALL hoặc POSTINSTALL.

    Đối với mỗi nội dung hấp dẫn, hãy ghi lại nội dung sau:

    • Mục đích dự kiến
    • Điểm trong logic của tiện ích mà nó chạy
    • Đầu vào và đầu ra dự kiến
    • Các điều kiện (hoặc tuỳ chọn) để thực thi quy tắc

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

Ví dụ

Tiện ích Tìm kiếm của Algolia 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 viết thư cho Algolia.