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 Chức năng đám mây, hãy thử thực hiện hướng dẫn này, bắt đầu với các tác vụ thiết lập bắt buộc 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 tin nhắn" hiển thị một URL chấp nhận giá trị văn bản và ghi nó vào Cloud Firestore.
  • Chức năng "tạo chữ hoa" kích hoạt ghi trên Cloud Firestore và chuyển văn bản thành chữ hoa.

Chúng tôi đã chọn Cloud Firestore và các hàm JavaScript được kích hoạt HTTP 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ộ mô phỏng 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ơ 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ư Trình kích hoạt cấu hình từ xa, TestLab và Analytics đều có thể được kiểm tra 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, kiểm tra 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 tới Xem lại mã mẫu hoàn chỉnh .

Tạo dự án Firebase

  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 dự á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 để có đượ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 tài khoản Google Analytics hiện có hoặc tạo 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 , 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 về 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ôi trường Node.js để viết các hàm và bạn sẽ cần Firebase CLI để triển khai các hàm vào thời gian chạy Chức năng đá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

Điều 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 của npm . Để cập nhật lên phiên bản mới nhất của firebase-tools , 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 tạo SDK Firebase cho Chức năng đám mây, bạn tạo một dự án trống chứa các 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 hàm. 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ề các quy tắc và tệp chỉ mục của Firestore. Nếu bạn chưa sử dụng Cloud Firestore trong dự án này, bạn cũng cần chọn chế độ và vị trí bắt đầu cho Firestore như được mô tả trong Bắt đầu với Cloud Firestore .
  4. Chạy firebase init functions . CLI sẽ 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 việc triển khai của bạn mở rộng, bạn có thể muốn sắp xếp các hàm 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ần phụ thuộc với npm. Bạn có thể từ chối nếu muốn quản lý các phần 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 tạo ứ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 quản trị 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 phiên bản ứng dụng admin để 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 quản trị viên , như dành cho FCM, Xác thực và Cơ sở dữ liệu thời gian thực Firebase, nó đều cung cấp một cách mạnh mẽ để 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 tạo 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 hàm 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à điểm cuối HTTP. Bất kỳ yêu cầu nào tớ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 có tính đồ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 nhanh nhất có thể 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 đến đ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 trùng 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ì, hàm 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 .

Mô phỏng việc thực hiện các chức năng của bạn

Bộ mô phỏng cục bộ Firebase cho phép bạn xây dựng và thử nghiệm các ứng dụng trên máy cục bộ của mình thay vì triển khai vào dự án Firebase. Việc thử nghiệm cục bộ trong quá trình phát triển được đặc biệt khuyến khích, một phần vì nó làm giảm rủi ro từ các 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 trình firebase emulators:start và kiểm tra đầu ra để tìm URL của giao diện người dùng Bộ mô phỏng. 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. Nó sẽ trông giống như: 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 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 Giao diện người dùng Bộ mô phỏng:

    1. Trong tab Nhật ký , bạn sẽ thấy nhật ký mới cho biết 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 tài liệu chứa tin nhắn gốc cũng như phiên bản viết hoa của tin nhắn (nếu ban đầu nó là "chữ hoa", bạn sẽ thấy "Chữ hoa").

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

Sau khi các hàm của bạn hoạt động như mong muốn trong trình mô phỏng, 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 lên 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 định giá Blaze . Xem giá của Chức năng đám mây .

Để hoàn thành phần hướng dẫn, hãy triển khai các hàm 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 mọi điểm cuối của hàm HTTP. 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 hàm 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ố hàm HTTP sản xuất sẽ chỉ định một vị trí để giảm thiểu độ trễ mạng.

    Nếu bạn gặp phải các lỗi truy cập 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 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 chuỗi văn bản được lưu trữ. Sự kiện ghi này kích hoạt makeUppercase() , viế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 bảng điều khiển Google Cloud . Nếu bạn cần xóa các chức năng đang trong quá trình phát triển hoặc sản xuất, hãy sử dụng Firebase CLI.

Trong quá trình 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 chia tỷ lệ để 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ố đến đ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ý các chức năng cho Cloud Functions cũng như cách xử lý tất cả các loại sự kiện được Cloud Functions hỗ trợ.

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