Bắt đầu: viết, kiểm tra và triển khai các chức năng đầu tiên của bạn


Để bắt đầu với Cloud Functions, hãy thử làm việc với hướng dẫn này, bắt đầu với các tác vụ thiết lập cần thiết và hoạt động thông qua việc tạo, thử nghiệm và triển khai hai chức năng liên quan:

  • Chức năng "thêm thông báo" hiển thị URL chấp nhận giá trị văn bản và ghi giá trị đó vào Cloud Firestore.
  • Chức năng "viết hoa" kích hoạt ghi trên Cloud Firestore và chuyển đổi văn bản thành chữ hoa.

Chúng tôi đã chọn các chức năng JavaScript kích hoạt HTTP và Cloud Firestore cho mẫu này một phần vì các trình kích hoạt nền này có thể được kiểm tra kỹ lưỡng thông qua Bộ trình giả lập cục bộ Firebase . Bộ công cụ này cũng hỗ trợ các trình kích hoạt có thể gọi được Cơ sở dữ liệu thời gian thực, PubSub, Auth và HTTP. Tất cả các loại trình kích hoạt nền khác như Cấu hình từ xa, TestLab và trình kích hoạt Analytics đều có thể được thử nghiệm một cách tương tác bằng cách sử dụng các bộ công cụ không được mô tả trong trang này.

Các phần sau của hướng dẫn này trình bày chi tiết các bước cần thiết để xây dựng, thử nghiệm và triển khai mẫu. Nếu bạn chỉ muốn chạy mã và kiểm tra mã, hãy chuyển đến Xem lại mã mẫu hoàn chỉnh .

Tạo một dự án căn cứ hỏa lực

  1. Trong bảng điều khiển Firebase , nhấp vào Thêm dự án .

    • Để thêm tài nguyên Firebase vào dự án Google Cloud hiện có , hãy nhập tên dự án hoặc chọn từ menu thả xuống.

    • Để tạo một dự án mới, hãy nhập tên dự án mong muốn. Bạn cũng có thể tùy ý chỉnh sửa ID dự án được hiển thị bên dưới tên dự án.

  2. Nếu được nhắc, hãy xem lại và chấp nhận các điều khoản của Firebase .

  3. Nhấp vào Tiếp tục .

  4. (Tùy chọn) Thiết lập Google Analytics cho dự án của bạn, cho phép bạn có trải nghiệm tối ưu khi sử dụng bất kỳ sản phẩm Firebase nào sau đây:

    Chọn một tài khoản Google Analytics hiện có hoặc để tạo một tài khoản mới.

    Nếu bạn tạo tài khoản mới, hãy chọn vị trí báo cáo Analytics của bạn , sau đó chấp nhận cài đặt chia sẻ dữ liệu và điều khoản Google Analytics cho dự án của bạn.

  5. Nhấp vào Tạo dự án (hoặc Thêm Firebase , nếu bạn đang sử dụng dự án Google Cloud hiện có).

Firebase tự động cung cấp tài nguyên cho dự án Firebase của bạn. Khi quá trình hoàn tất, bạn sẽ được đưa đến trang tổng quan cho dự án Firebase của mình trong bảng điều khiển Firebase.

Thiết lập Node.js và Firebase CLI

Bạn sẽ cần một môi trường Node.js để viết các hàm và bạn sẽ cần CLI Firebase để triển khai các hàm cho thời gian chạy Hàm đám mây. Để cài đặt Node.js và npm , nên sử dụng Trình quản lý phiên bản nút .

Khi bạn đã cài đặt Node.js và npm, hãy cài đặt Firebase CLI thông qua phương pháp ưa thích của bạn. Để cài đặt CLI qua npm, hãy sử dụng:

npm install -g firebase-tools

Thao tác này sẽ cài đặt lệnh firebase có sẵn trên toàn cầu. Nếu lệnh không thành công, bạn có thể cần thay đổi quyền npm . Để cập nhật lên phiên bản firebase-tools mới nhất, hãy chạy lại lệnh tương tự.

Khởi tạo dự án của bạn

Khi bạn khởi chạy SDK Firebase cho Chức năng đám mây, bạn tạo một dự án trống chứa các thành phần phụ thuộc và một số mã mẫu tối thiểu, đồng thời bạn chọn TypeScript hoặc JavaScript để soạn các chức năng. Với mục đích của hướng dẫn này, bạn cũng cần khởi tạo Cloud Firestore.

Để khởi tạo dự án của bạn:

  1. Chạy firebase login để đăng nhập qua trình duyệt và xác thực Firebase CLI.
  2. Chuyển đến thư mục dự án Firebase của bạn.
  3. Chạy firebase init firestore . Đối với hướng dẫn này, bạn có thể chấp nhận các giá trị mặc định khi được nhắc về quy tắc Firestore và tệp chỉ mục. Nếu chưa sử dụng Cloud Firestore trong dự án này, bạn cũng cần chọn chế độ bắt đầu và vị trí cho Firestore như được mô tả trong Bắt đầu với Cloud Firestore .
  4. Chạy firebase init functions . CLI nhắc bạn chọn một cơ sở mã hiện có hoặc khởi tạo và đặt tên cho một cơ sở mã mới. Khi bạn mới bắt đầu, một cơ sở mã duy nhất ở vị trí mặc định là đủ; sau này, khi triển khai của bạn mở rộng, bạn có thể muốn tổ chức các chức năng trong cơ sở mã .

  5. CLI cung cấp cho bạn hai tùy chọn để hỗ trợ ngôn ngữ:

    Đối với hướng dẫn này, hãy chọn JavaScript .

  6. CLI cung cấp cho bạn tùy chọn cài đặt các phụ thuộc với npm. Bạn có thể từ chối nếu muốn quản lý các phụ thuộc theo cách khác, tuy nhiên nếu từ chối, bạn sẽ cần chạy npm install trước khi mô phỏng hoặc triển khai các chức năng của mình.

Sau khi các lệnh này hoàn tất thành công, cấu trúc dự án của bạn trông như thế này:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

Tệp package.json được tạo trong quá trình khởi tạo chứa một khóa quan trọng: "engines": {"node": "16"} . Điều này chỉ định phiên bản Node.js của bạn để viết và triển khai các chức năng. Bạn có thể chọn các phiên bản được hỗ trợ khác .

Nhập các mô-đun cần thiết và khởi chạy ứng dụng

Sau khi hoàn thành các tác vụ thiết lập, bạn có thể mở thư mục nguồn và bắt đầu thêm mã như được mô tả trong các phần sau. Đối với mẫu này, dự án của bạn phải nhập các mô-đun SDK dành cho quản trị viên và Chức năng đám mây bằng cách sử dụng các câu lệnh require Node. Thêm các dòng như sau vào tệp index.js của bạn:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Các dòng này tải các mô-đun firebase-functions và firebase-admin , đồng thời khởi tạo một phiên bản ứng dụng admin mà từ đó có thể thực hiện các thay đổi trên Cloud Firestore. Bất cứ nơi nào có hỗ trợ SDK dành cho quản trị viên , như đối với Cơ sở dữ liệu thời gian thực FCM, Xác thực và Firebase, nó cung cấp một cách hiệu quả để tích hợp Firebase bằng Chức năng đám mây.

Firebase CLI tự động cài đặt các mô-đun Firebase và SDK Firebase cho Nút chức năng đám mây khi bạn khởi chạy dự án của mình. Để thêm thư viện của bên thứ 3 vào dự án của bạn, bạn có thể sửa đổi package.json và chạy npm install . Để biết thêm thông tin, hãy xem Xử lý phụ thuộc .

Thêm chức năng addMessage()

Đối với hàm addMessage() , hãy thêm những dòng này vào index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

Hàm addMessage() là một điểm cuối HTTP. Bất kỳ yêu cầu nào đối với điểm cuối đều dẫn đến các đối tượng Yêu cầu và Phản hồi kiểu ExpressJS được chuyển đến lệnh gọi lại onRequest() .

Các hàm HTTP là đồng bộ (tương tự như các hàm có thể gọi ), vì vậy bạn nên gửi phản hồi càng nhanh càng tốt và trì hoãn công việc bằng Cloud Firestore. Hàm HTTP addMessage() chuyển một giá trị văn bản tới điểm cuối HTTP và chèn nó vào cơ sở dữ liệu theo đường dẫn /messages/:documentId/original .

Thêm hàm makeUppercase()

Đối với hàm makeUppercase() , hãy thêm những dòng này vào index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Hàm makeUppercase() thực thi khi Cloud Firestore được ghi vào. Hàm ref.set xác định tài liệu để nghe. Vì lý do hiệu suất, bạn nên càng cụ thể càng tốt.

Dấu ngoặc nhọn—ví dụ: {documentId} —các "tham số" bao quanh, các ký tự đại diện hiển thị dữ liệu khớp của chúng trong lệnh gọi lại.

Cloud Firestore kích hoạt lệnh gọi lại onCreate() bất cứ khi nào có tin nhắn mới được thêm vào.

Các chức năng hướng sự kiện như sự kiện Cloud Firestore không đồng bộ. Hàm gọi lại sẽ trả về null , Object hoặc Promise . Nếu bạn không trả lại bất cứ thứ gì, chức năng sẽ hết thời gian, báo hiệu lỗi và được thử lại. Xem Đồng bộ hóa, Không đồng bộ và Lời hứa .

Thi đua thực hiện các chức năng của bạn

Bộ giả lập cục bộ Firebase cho phép bạn tạo và thử nghiệm ứng dụng trên máy cục bộ của mình thay vì triển khai cho dự án Firebase. Thử nghiệm cục bộ trong quá trình phát triển được khuyến nghị mạnh mẽ, một phần vì nó làm giảm rủi ro do lỗi mã hóa có khả năng phát sinh chi phí trong môi trường sản xuất (ví dụ: vòng lặp vô hạn).

Để mô phỏng các chức năng của bạn:

  1. Chạy firebase emulators:start và kiểm tra đầu ra cho URL của giao diện người dùng Emulator Suite. Nó mặc định là localhost:4000 , nhưng có thể được lưu trữ trên một cổng khác trên máy của bạn. Nhập URL đó vào trình duyệt của bạn để mở giao diện người dùng Emulator Suite.

  2. Kiểm tra đầu ra của firebase emulators:start để biết URL của hàm HTTP addMessage() . Nó sẽ trông giống như http://localhost:5001/MY_PROJECT/us-central1/addMessage , ngoại trừ:

    1. MY_PROJECT sẽ được thay thế bằng ID dự án của bạn.
    2. Cổng có thể khác trên máy cục bộ của bạn.

  3. Thêm chuỗi truy vấn ?text=uppercaseme vào cuối URL của hàm. Cái này sẽ giống như sau: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Theo tùy chọn, bạn có thể thay đổi thông báo "chữ hoa" thành thông báo tùy chỉnh.

  4. Tạo một tin nhắn mới bằng cách mở URL trong tab mới trong trình duyệt của bạn.

  5. Xem tác dụng của các chức năng trong Emulator Suite UI:

    1. Trong tab Nhật ký , bạn sẽ thấy các nhật ký mới cho biết rằng các hàm addMessage() và makeUppercase() đã chạy:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Trong tab Firestore , bạn sẽ thấy một tài liệu chứa thư gốc cũng như phiên bản viết hoa của thư (nếu ban đầu là "chữ hoa", bạn sẽ thấy "UPPERCASEME").

Triển khai các chức năng cho môi trường sản xuất

Sau khi các chức năng của bạn hoạt động như mong muốn trong trình giả lập, bạn có thể tiến hành triển khai, thử nghiệm và chạy chúng trong môi trường sản xuất. Hãy nhớ rằng để triển khai vào môi trường thời gian chạy Node.js 14 được đề xuất, dự án của bạn phải nằm trong gói giá Blaze . Xem giá Chức năng đám mây .

Để hoàn thành hướng dẫn, hãy triển khai các chức năng của bạn rồi thực thi addMessage() để kích hoạt makeUppercase() .

  1. Chạy lệnh này để triển khai các chức năng của bạn:

     firebase deploy --only functions

    Sau khi bạn chạy lệnh này, Firebase CLI sẽ xuất URL cho bất kỳ điểm cuối chức năng HTTP nào. Trong thiết bị đầu cuối của bạn, bạn sẽ thấy một dòng như sau:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage

    URL chứa ID dự án của bạn cũng như vùng dành cho chức năng HTTP. Mặc dù bây giờ bạn không cần phải lo lắng về điều đó, nhưng một số chức năng HTTP sản xuất nên chỉ định một vị trí để giảm thiểu độ trễ của mạng.

    Nếu bạn gặp lỗi truy cập, chẳng hạn như "Không thể cấp quyền truy cập vào dự án", hãy thử kiểm tra bí danh dự án của bạn.

  2. Sử dụng đầu ra URL addMessage() của CLI, thêm một tham số truy vấn văn bản và mở nó trong trình duyệt:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo

    Hàm thực thi và chuyển hướng trình duyệt đến bảng điều khiển Firebase tại vị trí cơ sở dữ liệu nơi lưu trữ chuỗi văn bản. Sự kiện ghi này kích hoạt makeUppercase() , viết một phiên bản chữ hoa của chuỗi.

Sau khi triển khai và thực thi các chức năng, bạn có thể xem nhật ký trong Google Cloud Console . Nếu bạn cần xóa các chức năng trong quá trình phát triển hoặc sản xuất, hãy sử dụng Firebase CLI.

Trong sản xuất, bạn có thể muốn tối ưu hóa hiệu suất chức năng và kiểm soát chi phí bằng cách đặt số lượng phiên bản tối thiểu và tối đa để chạy. Xem Kiểm soát hành vi mở rộng quy mô để biết thêm thông tin về các tùy chọn thời gian chạy này.

Xem lại mã mẫu hoàn chỉnh

Đây là functions/index.js đã hoàn thành chứa các hàm addMessage() và makeUppercase() . Các hàm này cho phép bạn chuyển tham số tới điểm cuối HTTP ghi giá trị vào Cloud Firestore, sau đó chuyển đổi giá trị đó bằng cách viết hoa tất cả các ký tự trong chuỗi.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Bước tiếp theo

Trong tài liệu này, bạn có thể tìm hiểu thêm về cách quản lý chức năng cho Chức năng đám mây cũng như cách xử lý tất cả các loại sự kiện được Chức năng đám mây hỗ trợ.

Để tìm hiểu thêm về Chức năng đám mây, bạn cũng có thể làm như sau: