Cài đặt một tiện ích Firebase

Bạn có thể cài đặt (và quản lý) bất kỳ tiện ích Firebase chính thức nào bằng cách sử dụng bảng điều khiển Firebase, CLI Firebase (giao diện dòng lệnh) hoặc bằng cách sử dụng một SDK được tạo tự động.

Hãy nhớ xem xét sự khác biệt về các thao tác được hỗ trợ cho từng phương thức cài đặt.


Cài đặt bằng SDK được tạo tự động là một lựa chọn mới để cài đặt và quản lý các tiện ích. Với lựa chọn này, bạn sử dụng CLI để tự động tạo một Node SDK cho một phiên bản tiện ích cụ thể. Bạn có thể nhập phiên bản này dưới dạng một phần phụ thuộc thông thường trong Cloud Functions JavaScript hoặc TypeScript.

SDK được tạo tự động này chứa:

  • Một giao diện đại diện cho các tham số của tiện ích và khai báo kiểu cho hầu hết các kiểu tham số không nguyên thuỷ.
  • Một hàm khởi tạo khởi chạy một phiên bản của tiện ích
  • Một lớp tiện ích chứa các điều kiện kích hoạt Eventarc cho tất cả các sự kiện do tiện ích phát ra.

Sau khi bạn tạo một SDK tiện ích, mọi cấu hình của tiện ích sẽ diễn ra trong mã.

Việc sử dụng lựa chọn cài đặt này có thể giúp đơn giản hoá đáng kể việc quản lý nhiều phiên bản tiện ích, đặc biệt là trong các dự án có chứa các hàm Cloud được xác định bên ngoài tiện ích.


Để cài đặt hoặc quản lý các tiện ích, bạn phải được chỉ định một trong các vai trò sau: Chủ sở hữu hoặc Người chỉnh sửa hoặc Quản trị viên Firebase.

Để cài đặt một tiện ích, dự án của bạn phải sử dụng gói Blaze (trả tiền theo mức dùng). Mặc dù không mất phí khi cài đặt tiện ích, nhưng bạn có thể bị tính phí khi sử dụng các dịch vụ của Firebase hoặc Cloud, chẳng hạn như Cloud Secret Manager, nếu mức sử dụng của bạn vượt quá bậc miễn phí của các dịch vụ này.

Trước khi bắt đầu

  1. Nếu bạn chưa thực hiện, hãy thêm Firebase vào dự án của bạn.

  2. Nếu bạn chưa nâng cấp, hãy nâng cấp dự án của bạn lên gói Blaze (trả tiền theo mức dùng).

  3. Cài đặt hoặc cập nhật lên phiên bản mới nhất của CLI Firebase.

  4. Ghi lại mã dự án Firebase hoặc bí danh dự án mà bạn đã định cấu hình trước đó.

    • Mã dự án – Chạy firebase projects:list ở bất cứ đâu trên máy tính.
    • Bí danh dự án – Chạy firebase use từ thư mục ứng dụng cục bộ.

Bước 1: Xem thông tin chi tiết về một tiện ích

Bước này không bắt buộc nhưng bạn nên thực hiện.

Trước khi cài đặt một Firebase Extension, bạn nên xem thông tin chi tiết về tiện ích, bao gồm:

  • Cách hoạt động của tiện ích, mọi việc cần làm trước khi cài đặt và thông tin chi tiết về tiện ích
  • Thông tin nhận dạng chung và nội dung mô tả
  • Liệu các tác vụ của tiện ích có yêu cầu tài khoản thanh toán hay không
  • Các dịch vụ (API) của Google và vai trò truy cập cần thiết cho hoạt động
  • Tài nguyên được tạo cho tiện ích (chẳng hạn như các hàm)
  • Nội dung mô tả về các thông số do người dùng định cấu hình

Cách xem thông tin chi tiết của một tiện ích:

  1. Đảm bảo rằng bạn đã thiết lập môi trường và chọn một tiện ích.

  2. Chạy lệnh extension-info ở bất kỳ vị trí nào trên máy tính:

    firebase ext:info publisher-id/extension-id

    Bạn phải cung cấp đối số publisher-id và extension-id và có thể tìm thấy các đối số này trên trang chi tiết trước khi cài đặt của tiện ích.

Bước 2: Cài đặt một tiện ích

Trước khi cài đặt, hãy xem xét các thông số kỹ thuật cơ bản của tiện ích (chẳng hạn như API đã bật, tài nguyên đã tạo, quyền truy cập đã cấp, v.v.) và các yêu cầu về việc thanh toán của tiện ích.

Trước khi tiếp tục, hãy đảm bảo rằng bạn đã thiết lập môi trường và chọn một tiện ích.

Khởi động Cloud Functions cho Firebase

Nếu bạn đang bắt đầu một dự án mới hoặc nếu dự án của bạn chưa sử dụng Cloud Functions cho Firebase, hãy chạy init functions:

cd your-project
firebase init functions

Chọn TypeScript hoặc JavaScript làm ngôn ngữ hàm.

Nếu dự án của bạn đã khởi chạy Cloud Functions, hãy đảm bảo bạn đang dùng phiên bản 5.1.0 trở lên của gói firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

Nếu sử dụng ESLint, bạn cũng có thể muốn loại trừ các SDK đã tạo khỏi cấu hình (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Tạo một SDK tiện ích

Từ thư mục Firebase cục bộ, hãy chạy lệnh ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

Ví dụ: để cài đặt phiên bản 0.1.34 của tiện ích firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

Bạn phải có publisher-id và extension-id và có thể tìm thấy các thuộc tính này trên trang chi tiết trước khi cài đặt của tiện ích trên extensions.dev. Phần @version là không bắt buộc; nếu bạn bỏ qua phần này, công cụ sẽ cài đặt phiên bản mới nhất.

Bạn có thể chỉ định 2 lựa chọn:

  • --force: Thực hiện tất cả các thao tác sau mà không cần xác nhận thêm:

    • Tự động tạo SDK ngay cả khi đã có một SDK được tạo cho cùng một tiện ích và phiên bản.
    • Cài đặt gói SDK được tạo tự động trong dự án Cloud Functions Node.

  • --codebase: Tên của cơ sở mã để thêm SDK vào. Nếu bạn không chỉ định, lệnh này sẽ thêm SDK vào cơ sở mã mặc định, functions.

Lệnh này sẽ tạo một gói Node chứa SDK được tự động tạo cho tiện ích và thêm gói đó vào một trong các cơ sở mã Cloud Functions của dự án. Trong cơ sở mã mặc định (functions), SDK được lưu vào vị trí sau: 

functions/generated/extensions/publisher-id/extension-id/version

Sau khi tạo SDK, lệnh này sẽ hỏi xem bạn có muốn cài đặt SDK vào dự án Node Cloud Functions của mình hay không. Trả lời Có cho câu hỏi này.

Định cấu hình các thực thể tiện ích

Để định cấu hình tiện ích, hãy nhập SDK và đối với mỗi phiên bản tiện ích mà bạn muốn cài đặt, hãy gọi hàm khởi tạo, truyền vào đó một mã nhận dạng phiên bản duy nhất của dự án và các tham số cấu hình mà tiện ích yêu cầu.

  1. Trong nguồn Cloud Functions, hãy nhập hàm khởi tạo bằng câu lệnh do lệnh ext:sdk:install in.

    TypeScript

    Ví dụ: nếu bạn tạo một SDK cho tiện ích firestore-send-email, thì câu lệnh import sẽ có dạng như sau:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Nếu tiện ích yêu cầu bất kỳ giá trị bí mật nào, chẳng hạn như mật khẩu, bạn cũng cần hàm defineSecret trong Cloud Functions SDK:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Ví dụ: nếu bạn tạo một SDK cho tiện ích firestore-send-email, thì câu lệnh require sẽ có dạng như sau:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Nếu tiện ích yêu cầu bất kỳ giá trị bí mật nào, chẳng hạn như mật khẩu, bạn cũng cần hàm defineSecret trong Cloud Functions SDK:

    const { defineSecret } = require('firebase-functions/params');

  2. Đối với mỗi phiên bản mà bạn muốn định cấu hình, hãy gọi hàm khởi tạo và xuất kết quả.

    Đặt cho mỗi phiên bản một mã nhận dạng riêng biệt, chỉ chứa chữ cái viết thường, số và dấu gạch ngang.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Xin lưu ý rằng bạn phải chỉ định các giá trị bí mật bằng hàm defineSecret.

  3. Sau đó, để triển khai các tiện ích mà bạn đã định cấu hình, hãy chạy: 

    firebase deploy --only functions --project=projectId-or-alias

    Tất cả các lựa chọn triển khai Cloud Functions thông thường đều được áp dụng. Ví dụ: để triển khai một phiên bản tiện ích duy nhất từ một cơ sở mã cụ thể: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Bước 3: Hoàn tất quá trình thiết lập sau khi cài đặt

Một số tiện ích có các bước bắt buộc hoặc không bắt buộc mà bạn cần hoàn tất trước khi sử dụng. Bạn có thể xem các hướng dẫn này trên trang thông tin chi tiết sau khi cài đặt của tiện ích trong trang tổng quan Extensions của bảng điều khiển Firebase (đường liên kết cụ thể đến trang tổng quan sẽ xuất hiện trong thiết bị đầu cuối sau khi cài đặt).

Bạn cũng có thể tìm thấy các hướng dẫn này trong tệp POSTINSTALL.md có trong thư mục nguồn của tiện ích.

Tạo tài nguyên Firebase

Nếu bạn định cấu hình tiện ích để sử dụng các tài nguyên Firebase (Cloud Firestoretập hợp, Realtime Databaseđường dẫn, Cloud Storagethùng) chưa tồn tại, hãy tạo các tài nguyên đó trước khi sử dụng tiện ích.

Tạo trình xử lý sự kiện Eventarc

Một số tiện ích xuất bản lên Eventarc khi các sự kiện quan trọng xảy ra trong quá trình thực thi. Nếu một tiện ích xuất bản các sự kiện, bạn có thể viết các hàm phản ứng với những sự kiện này bằng logic tuỳ chỉnh của riêng mình. Ví dụ: điều này có thể hữu ích khi bạn muốn thông báo cho người dùng khi các tác vụ chạy trong thời gian dài hoàn tất hoặc khi bạn muốn xử lý hậu kỳ đầu ra của một hàm tiện ích.

Nếu muốn xác định trình xử lý cho bất kỳ sự kiện nào do tiện ích phát ra, bạn có thể thực hiện bằng cách sử dụng các phương thức kích hoạt của từng thực thể:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Bạn phải xuất trình xử lý sự kiện cùng với phiên bản tiện ích.

Sau khi xác định một trình xử lý sự kiện và sau mỗi lần bạn thay đổi một trình xử lý, hãy triển khai lại cả tiện ích và trình xử lý.

Cài đặt nhiều phiên bản tiện ích

Bạn có thể cài đặt cùng một tiện ích nhiều lần trong cùng một dự án. Mỗi phiên bản đã cài đặt có thể có cấu hình tuỳ chỉnh riêng và tài nguyên tiện ích riêng. Bạn xác định và tham chiếu đến từng phiên bản đã cài đặt bằng mã nhận dạng phiên bản (mã này là duy nhất trong dự án của bạn).

Gọi hàm khởi tạo của SDK được tạo tự động một lần cho mỗi phiên bản mà bạn muốn cài đặt và định cấu hình.

Các bước tiếp theo