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

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

  • Các lệnh gọi đồng bộ: để cho phép người dùng thêm logic chặn vào tiện ích của bạn, bạn có thể thêm các lệnh gọi đồ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 điểm này, bạn chạy một hàm do người dùng cung cấp và chỉ tiếp tục sau khi hàm này hoàn tất. Các tác vụ tiền xử lý thường thuộc 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 các sự kiện từ một tiện ích:

  1. Khai báo các loại sự kiện mà 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

    Giá trị nhận dạng type bao gồm một số trường được phân tách bằng dấu chấm. Bạn phải điền các trường mã nhận dạng nhà xuất bản, tên tiện ích và tên sự kiện. Bạn nên sử dụng trường phiên bản. Chọn một tên sự kiện duy nhất và mang tính mô tả cho mỗi 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 có thể chọn sự kiện mà họ muốn đăng ký 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 một kênh sự kiện bằ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á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 phân tách bằng dấu phẩy gồm các loại sự kiện mà người dùng chọn xuất bản. Khi bạn khởi tạo một kênh bằng giá trị này, Admin SDK sẽ 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 Cloud Event. Admin SDK sẽ tự động truyền giá trị này trong trường source của các sự kiện đã xuất bản. Thông thường, bạn không cần 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, thì các biến này sẽ không xác định. Bạn có thể dùng dữ liệu này để khởi chạy một kênh sự kiện chỉ khi các 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 các sự kiện cho kênh tại những điểm trong tiện ích mà bạn muốn cho người dùng thấy. 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 tệp 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à tiện ích chạy
    • Dữ liệu đầu ra mà báo cáo này bao gồm
    • Các điều kiện để thực thi

    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, dẫn đến một vòng lặp vô hạn.

Khi bạn xuất bản các 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 sẽ xoá hình ảnh gốc sau khi hình ảnh đó được đổi kích thước. Xin 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.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

Hãy xem bài viết Trình kích hoạt sự kiện tuỳ chỉnh để biết thêm thông tin.

Ví dụ

Tiện ích Resize Images (Đổi kích thước hình ảnh) chính thức cung cấp một lệnh gọi 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.

Các hook đồng bộ

Khi bạn muốn cung cấp cho người dùng một lệnh gọi phải hoàn tất thành công để một trong các hàm tiện ích của bạn hoạt động, hãy sử dụng lệnh gọi đồng bộ.

Một lệnh gọi hook đồng bộ sẽ gọi Cloud Function có thể gọi HTTPS do người dùng xác định và chờ hoàn tất (có thể có giá trị 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.

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 tiện ích bằng URL đến Cloud Functions 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 điểm trong tiện ích mà bạn muốn hiển thị lệnh gọi, hãy gọi hàm bằng URL của hàm đó. 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 hook mà bạn cung cấp trong tệp PREINSTALL hoặc POSTINSTALL.

    Đối với mỗi lệnh gọi, 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à tiện ích chạy
    • Đầu vào và đầu ra dự kiến
    • Các điều kiện (hoặc lựa chọn) để thực thi

    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 hàm hook có thể kích hoạt cùng một tiện ích, dẫn đến vòng lặp vô hạn.

Ví dụ

Tiện ích Tìm kiếm của Algolia cung cấp một lệnh gọi đồng bộ để gọi hàm biến đổi do người dùng cung cấp trước khi ghi vào Algolia.