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 người dùng cài đặt tiện ích của bạn 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 để thực hiện việc này:

• Sự kiện Eventarc: để cung cấp cho người dùng một cách thức 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 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ý sau của riêng mình.

• Đường liên kết đồng bộ: để cung cấp cho người dùng cách thêm logic chặn vào tiện ích, bạn có thể thêm các đường liên kết đồ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 các điểm này, bạn chạy một hàm nhà cung cấp người dùng và chỉ tiếp tục sau khi hàm này hoàn tất. Các tác vụ xử lý trước thường thuộc danh mục này.

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

Sự kiện Eventarc

Cách phát hành sự kiện từ một tiện ích:

1. Khai báo các loại sự kiện mà bạn sẽ phát hành 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 thành từ một số trường được phân tách bằng dấu chấm. Bạn bắt buộc 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à mô tả cho từng loại sự kiện mà bạn phát hành.

   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 để đăng ký khi cài đặt tiện ích.

2. Trong các hàm tiện ích, hãy nhập API Eventarc từ Admin SDK và khởi chạy một kênh sự kiện bằng chế độ cài đặt 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 để phát hành 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 phát hành. Khi bạn khởi chạy một kênh bằng giá trị này, SDK Quản trị 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 Sự kiện trên đám mây. SDK quản trị 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 rõ ràng biến này.

   Nếu bạn không bật sự kiện trong quá trình cài đặt, các biến này sẽ không được xác định. Bạn có thể sử dụng thông tin này để chỉ khởi chạy 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. Xuất bản sự kiện cho kênh tại các điểm trong tiện ích mà bạn muốn 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 phát hành 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 sử dụng
   • Điểm trong logic của tiện ích mà tiện ích đó chạy
   • Dữ liệu đầu ra mà hàm này bao gồm
   • Đ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 vòng lặp vô hạn.

Khi bạn phát hành 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ý 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();
    });

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 Đổi kích thước hình ảnh chính thức cung cấp một trình nối không đồng bộ bằng cách phát hành lên Eventarc sau khi đổi kích thước hình ảnh.

Phần phụ trợ đồng bộ

Khi bạn muốn cung cấp cho người dùng một trình bổ trợ 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 trình bổ trợ đồng bộ.

Một trình bổ trợ đồng bộ gọi Hàm trên đám mây có thể gọi qua 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 dẫn đến lỗi trong hàm mở rộng.

Để hiển thị một trình bổ trợ đồ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 trên đá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 điểm trong tiện ích mà bạn muốn hiển thị trình bổ trợ, hãy gọi hàm bằng URL của trình bổ trợ đó. 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 trình bổ trợ mà bạn cung cấp trong tệp PREINSTALL hoặc POSTINSTALL.

   Đối với mỗi trình bổ trợ, hãy ghi lại những thông tin sau:

   • Mục đích sử dụng
   • Đ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 tuỳ 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 Algolia cung cấp một trình nố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.