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 có thể chèn logic tuỳ chỉnh của riêng họ vào quá trình thực thi tiện ích. Có hai cách để hoàn thành việc này:

  • Sự kiện Eventarc: để mang lại 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ể phát hành lên Eventarc. Người dùng có thể triển khai các chức năng của 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 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ộ: để cho phép người dùng thêm logic chặn vào tiện ích, bạn có thể thêm các hook đồng bộ tại các điểm được xác định trước trong thao tác của tiện ích. Tại những thời điểm này, bạn chạy hàm cung cấp cho người dùng và chỉ tiếp tục sau khi hoàn tất. Các nhiệm 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 sự kiện qua một tiện ích:

  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

    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. Các trường mã nhà xuất bản, tên tiện ích và tên sự kiện là bắt buộc. Bạn nên 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 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 những sự kiện cần đăng ký khi họ cài đặt tiện ích.

  2. Trong các hàm tiện ích, hãy nhập Eventarc API từ SDK quản trị 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á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 phát hành sự kiện.
    • EXT_SELECTED_EVENTS: một 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 phát hành. Khi bạn khởi tạo một 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: Giá trị nhận dạng nguồn của Sự kiện trên đám mây. SDK quản trị tự động chuyển giá trị này trong trường source của các sự kiện đã xuất bản. Thường thì bạn không cần sử dụng biến này một cách rõ ràng.

    Nếu các sự kiện không được bật khi cài đặt, thì các biến này sẽ không được xác định. Bạn chỉ có thể sử dụng dữ kiện này để khởi chạy một kênh sự kiện 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. Phát hành sự kiện lên kênh tại các điểm trong tiện ích 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 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à 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 trình xử lý sự kiện của họ mà 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 phát hành 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 đổ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 để biết thêm thông tin.

Ví dụ

Tiện ích Thay đổi kích thước hình ảnh chính thức cung cấp một nội dung hấp dẫn 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 hook 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ộ sẽ gọi một Hàm đám mây có thể gọi HTTPS do người dùng xác định và chờ hoàn tất (có thể có giá trị được trả về) trước khi tiếp tục. Một lỗi trong hàm do người dùng cung cấp sẽ 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 tiện ích 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ị hook, hãy gọi hàm bằng cách sử dụng URL của hàm đó. 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 mọi nội dung hook mà bạn cung cấp trong tệp 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 hàm hook 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.

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 ghi vào Algolia.