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

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

Hãy nhớ xem xét sự khác biệt trong 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 tuỳ chọn này, bạn sử dụng CLI để tự động tạo SDK Node cho một phiên bản tiện ích cụ thể. Bạn có thể nhập SDK này dưới dạng phần phụ thuộc thông thường trong Hàm trên đám mây 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 loại cho hầu hết các loại tham số không phải nguyên gốc.
  • Hàm khởi tạo khởi chạy một thực thể của tiện ích
  • Một lớp tiện ích chứa các trình kích hoạt Eventarc cho tất cả sự kiện do tiện ích phát ra.

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

Việc sử dụng tuỳ chọn cài đặt này có thể đơ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 chứa các hàm trên đám mây được xác định bên ngoài tiện ích.


Để cài đặt hoặc quản lý 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 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í để cài đặt tiện ích, nhưng bạn có thể phải trả phí khi sử dụng các dịch vụ Firebase hoặc dịch vụ trên đám mây như Trình quản lý bí mật trên đám mây nếu mức sử dụng của bạn vượt quá cấp miễn phí của các dịch vụ này.

Trước khi bắt đầu

  1. Thêm Firebase vào dự án nếu bạn chưa thực hiện.

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

  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 đã định cấu hình trước đó.

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 Firebase Extension, bạn nên xem lại thông tin chi tiết về tiện ích này, bao gồm:

  • Cách hoạt động của tiện ích, mọi tác vụ trước khi cài đặt và thông tin chi tiết về tiện ích
  • Thông tin nhận dạng và nội dung mô tả chung
  • 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ụ của Google (API) và vai trò truy cập cần thiết để hoạt động
  • Tài nguyên được tạo cho tiện ích (chẳng hạn như hàm)
  • Nội dung mô tả về các tham số mà người dùng có thể định cấu hình

Cách xem thông tin chi tiết về 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ỳ đâu trên máy tính:

    firebase ext:info publisher-id/extension-id

    Bạn bắt buộc phải sử dụng đối số publisher-id và extension-id. Bạn có thể tìm thấy các đối số này trên trang chi tiết về việc cài đặt trước của tiện ích.

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

Trước khi cài đặt, hãy xem lại các thông số kỹ thuật cơ bản của tiện ích (chẳng hạn như các API được bật, tài nguyên được tạo, quyền truy cập được cấp, v.v.) và các yêu cầu về 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 chạy 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 Hàm trên đám mây 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 sử 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 nên loại trừ các SDK đã tạo khỏi cấu hình (.eslintrc.js):

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

Tạo 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 bắt buộc phải có publisher-id và extension-id. Bạn có thể tìm thấy các phần này trên trang chi tiết cài đặt trước 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 hai tuỳ chọn:

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

    • Tự động tạo SDK ngay cả khi đã tạo SDK 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 Nút của Hàm trên đám mây.

  • --codebase: Tên của cơ sở mã để thêm SDK. Nếu 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 tạo một gói Node chứa một SDK được tạo tự động cho tiện ích và thêm gói đó vào một trong các cơ sở mã của dự án về Hàm trên đám mây. 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 sẽ hỏi xem bạn có muốn cài đặt SDK vào dự án Nút của Hàm trên đám mây hay không. Trả lời Có cho lời nhắc này.

Định cấu hình 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 thực thể 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ã nhận dạng thực thể 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 ra.

    TypeScriptJavaScript

    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 như mật khẩu, bạn cũng cần có hàm defineSecret từ SDK Cloud Functions:

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

    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 như mật khẩu, bạn cũng cần có hàm defineSecret từ SDK Cloud Functions:

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

  2. Đối với mỗi thực thể 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ả.

    Gán cho mỗi thực thể một mã nhận dạng duy nhất, chỉ chứa chữ cái thường, số và dấu gạch nối.

    TypeScriptJavaScript
    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",
});

    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 cách sử dụng hàm defineSecret.

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

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

    Tất cả các tuỳ chọn triển khai Hàm trên đám mây thông thường đều được áp dụng. Ví dụ: để triển khai một thực thể 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 việc 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 phải hoàn tất trước khi sử dụng. Bạn có thể tìm thấy các hướng dẫn này trong trang chi tiết sau khi cài đặt tiện ích trên 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 (bộ sưu tập Cloud Firestore, đường dẫn Realtime Database, bộ chứa Cloud Storage) 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 phát hành 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 phát hành sự kiện, bạn có thể viết các hàm phản ứng với các sự kiện này bằng logic tuỳ chỉnh của riêng mình. Điều này có thể hữu ích, chẳng hạn như để 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 để xử lý hậu kỳ đầu ra của một hàm mở rộng.

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 việc này bằng cách sử dụng các phương thức kích hoạt của từng thực thể:

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

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

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 thực thể tiện ích.

Sau khi xác định trình xử lý sự kiện và sau mỗi lần bạn thực hiện thay đổi đối vớ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 thực thể đã 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 thực thể đã cài đặt bằng cách sử dụng mã nhận dạng thực thể riêng biệt trong dự án.

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

Các bước tiếp theo