Bắt đầu: viết, kiểm thử và triển khai các hàm đầu tiên


Để bắt đầu sử dụng Cloud Functions, hãy thử làm theo hướng dẫn này. Hướng dẫn này bắt đầu bằng các nhiệm vụ thiết lập bắt buộc và thực hiện việc tạo, kiểm thử và triển khai hai hàm có liên quan:

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

Dưới đây là mã mẫu đầy đủ chứa các hàm:

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

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

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

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

  const uppercase = original.toUpperCase();

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

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Giới thiệu về hướng dẫn này

Chúng tôi đã chọn Cloud Firestore và các hàm được kích hoạt bằng HTTP cho mẫu này một phần vì các trình kích hoạt ở chế độ nền này có thể được kiểm thử kỹ lưỡng thông qua Firebase Local Emulator Suite. Bộ công cụ này cũng hỗ trợ các trình kích hoạt có thể gọi Realtime Database, Cloud Storage, PubSub, Auth và HTTP. Bạn có thể kiểm thử tương tác các loại trình kích hoạt trong nền khác như Remote Config và trình kích hoạt TestLab bằ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 để tạo, kiểm thử và triển khai mẫu.

Tạo dự án Firebase

  1. Trong bảng điều khiển Firebase, hãy 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 đó trong trình đơn thả xuống.

    • Để tạo dự án mới, hãy nhập tên dự án mong muốn. Bạn cũng có thể tuỳ ý chỉnh sửa mã dự án xuất hiện bên dưới tên dự án.

  2. Nếu bạn thấy thông báo nhắc, hãy xem xét và chấp nhận các điều khoản của Firebase.

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

  4. (Không bắt buộc) Thiết lập Google Analytics cho dự án của 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, sau đó chấp nhận chế độ 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 sẽ tự động phân bổ tài nguyên cho dự án Firebase của bạn. Khi quá trình này hoàn tất, bạn sẽ được chuyển đến trang tổng quan về dự án Firebase trong bảng điều khiển Firebase.

Thiết lập môi trường và Giao diện dòng lệnh (CLI) của Firebase

Node.js

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

Sau khi bạn đã cài đặt Node.js và npm, hãy cài đặt CLI Firebase thông qua phương thức ưu tiên của bạn. Để cài đặt CLI thông 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 này 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 cùng một lệnh.

Python

Bạn sẽ cần một môi trường Python để viết hàm và bạn sẽ cần CLI Firebase để triển khai các hàm cho môi trường thời gian chạy Cloud Functions. Bạn nên sử dụng venv để tách biệt các phần phụ thuộc. Các phiên bản Python 3.10 và 3.11 được hỗ trợ.

Sau khi cài đặt Python, hãy cài đặt CLI Firebase thông qua phương thức bạn muốn.

Khởi chạy dự án

Khi khởi chạy SDK Firebase cho Cloud Functions, bạn sẽ 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. Nếu đang sử dụng Node.js, bạn có thể chọn TypeScript hoặc JavaScript để soạn các hàm. Đối với mục đích của hướng dẫn này, bạn cũng cần khởi chạy Cloud Firestore.

Cách khởi chạy dự án:

  1. Chạy firebase login để đăng nhập qua trình duyệt và xác thực CLI Firebase.
  2. Chuyển đến thư mục dự án Firebase.
  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ế độ khởi động và vị trí cho Firestore như mô tả trong phần Bắt đầu sử dụng Cloud Firestore.
  4. Chạy firebase init functions. CLI sẽ nhắc bạn chọn cơ sở mã hiện có hoặc khởi chạy và đặt tên cho một cơ sở mã mới. Khi mới bắt đầu, bạn chỉ cần một cơ sở mã duy nhất ở vị trí mặc định; sau này, khi việc triển khai 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 các tuỳ chọn hỗ trợ ngôn ngữ sau:

    • JavaScript
    • TypeScript
    • Python

    Đối với hướng dẫn này, hãy chọn JavaScript hoặc Python. Để viết bằng TypeScript, hãy xem phần Viết hàm bằng TypeScript.

  6. CLI cho phép bạn cài đặt các phần phụ thuộc. Bạn có thể an toàn khi từ chối nếu muốn quản lý các phần phụ thuộc theo cách khác.

Sau khi các lệnh này hoàn tất, cấu trúc dự án của bạn sẽ có dạng như sau:

Node.js

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

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

Python

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

Nhập các mô-đun bắt buộc và khởi chạy ứng dụng

Sau khi hoàn tất 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ư 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 Cloud Functions và SDK dành cho quản trị viên. Thêm các dòng như sau vào tệp nguồn:

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

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

initializeApp();
index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Các dòng này tải các mô-đun bắt buộc và khởi chạy một thực thể ứng dụng admin để có thể thực hiện các thay đổi Cloud Firestore. Bất cứ khi nào có hỗ trợ SDK dành cho quản trị viên (như đối với FCM, Authentication và Firebase Realtime Database), SDK này sẽ cung cấp một cách hiệu quả để tích hợp Firebase bằng Cloud Functions.

Giao diện dòng lệnh (CLI) Firebase tự động cài đặt SDK quản trị của Firebase và SDK Firebase cho các mô-đun Cloud Functions khi bạn khởi chạy dự án. Để biết thêm thông tin về cách thêm thư viện bên thứ ba vào dự án, hãy xem phần Xử lý phần phụ thuộc.

Thêm hàm "thêm thông báo"

Đối với hàm "add message" (thêm thông báo), hãy thêm các dòng sau vào tệp nguồn:

Node.js

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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

Python

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

Hàm "add message" (thêm tin nhắn) là một điểm cuối HTTP. Mọi yêu cầu đến điểm cuối đều dẫn đến việc các đối tượng yêu cầu và phản hồi được chuyển đến trình xử lý yêu cầu cho nền tảng của bạn (onRequest() hoặc on_request).

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 nhanh nhất có thể và trì hoãn công việc bằng Cloud Firestore. Hàm HTTP "thêm thông báo" truyền một giá trị văn bản đến điểm cuối HTTP và chèn giá trị đó vào cơ sở dữ liệu theo đường dẫn /messages/:documentId/original.

Thêm hàm "make uppercase"

Đối với hàm "viết hoa", hãy thêm các dòng sau vào tệp nguồn:

Node.js

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

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

  const uppercase = original.toUpperCase();

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

Python

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Hàm "đặt chữ hoa" sẽ thực thi khi Cloud Firestore được ghi vào, xác định tài liệu cần theo dõi. Vì lý do hiệu suất, bạn nên mô tả càng cụ thể càng tốt.

Dấu ngoặc nhọn (ví dụ: {documentId}) bao quanh "tham số", ký tự đại diện hiển thị dữ liệu trùng khớp trong lệnh gọi lại. Cloud Firestore kích hoạt lệnh gọi lại bất cứ khi nào có tin nhắn mới được thêm.

Trong Node.js, các hàm dựa trên sự kiện, chẳng hạn như các sự kiện Cloud Firestore, không đồng bộ. Hàm gọi lại phải trả về null, Đối tượng hoặc Lời hứa. Nếu bạn không trả về giá trị nào, hàm sẽ hết thời gian chờ, báo hiệu lỗi và thử lại. Xem phần Đồng bộ, không đồng bộ và Lời hứa.

Mô phỏng quá trình thực thi các hàm

Firebase Local Emulator Suite cho phép bạn tạo và kiểm thử ứng dụng trên máy cục bộ thay vì triển khai cho một dự án Firebase. Bạn nên kiểm thử cục bộ trong quá trình phát triển, một phần vì tính năng này giúp giảm rủi ro từ các lỗi lập trình có thể phát sinh chi phí trong môi trường sản xuất (ví dụ: một vòng lặp vô hạn).

Cách mô phỏng các hàm của bạn:

  1. Chạy firebase emulators:start và kiểm tra kết quả cho URL của Emulator Suite UI. Cổng 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 để mở Emulator Suite UI.

  2. Kiểm tra kết quả của lệnh firebase emulators:start để biết URL của hàm HTTP. Phương thức này sẽ có dạng tương tự như http://localhost:5001/MY_PROJECT/us-central1/addMessage, ngoại trừ:

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

  3. Thêm chuỗi truy vấn ?text=uppercaseme vào cuối URL của hàm. Mã này sẽ có dạng như sau: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Bạn có thể thay đổi thông báo "uppercaseme" thành thông báo tuỳ chỉnh (không bắt buộc).

  4. Tạo thư mới bằng cách mở URL trong một thẻ mới trong trình duyệt.

  5. Xem hiệu ứng của các hàm trong Emulator Suite UI:

    1. Trong thẻ Nhật ký, bạn sẽ thấy các nhật ký mới cho biết rằng hàm HTTP của bạn đã chạy thành công:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

Triển khai hàm vào môi trường sản xuất

Sau khi các hàm hoạt động như mong muốn trong trình mô phỏng, bạn có thể tiếp tục triển khai, kiểm thử và chạy các hàm đó trong môi trường sản xuất. Xin lưu ý rằng để triển khai trong phiên bản chính thức, dự án của bạn phải có Gói giá linh hoạt. Xem giá của Cloud Functions.

Để hoàn tất hướng dẫn, hãy triển khai các hàm rồi thực thi các hàm đó.

  1. Chạy lệnh sau để triển khai các hàm:

     firebase deploy --only functions

    Sau khi bạn chạy lệnh này, CLI Firebase sẽ xuất ra URL cho mọi điểm cuối của hàm HTTP. Trong dòng lệnh, bạn sẽ thấy một dòng như sau:

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

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

    Nếu bạn gặp lỗi truy cập như "Không thể uỷ quyền truy cập vào dự án", hãy thử kiểm tra tên đại diện của dự án.

  2. Sử dụng URL do CLI xuất ra, thêm một tham số truy vấn văn bản rồi mở tham số đó trong trình duyệt:

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

    Hàm này 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 lưu trữ chuỗi văn bản. Sự kiện ghi này kích hoạt hàm "make uppercase" (đổi chữ hoa) để ghi phiên bản chữ hoa của chuỗi.

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

Trong môi trường sản xuất, bạn nên tối ưu hoá hiệu suất của hàm và kiểm soát chi phí bằng cách đặt số lượng thực thể tối thiểu và tối đa để chạy. Hãy xem phần Kiểm soát hành vi điều chỉnh theo tỷ lệ để biết thêm thông tin về các tuỳ chọn thời gian chạy này.

Các 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 hàm cho Cloud Functions cũng như cách xử lý tất cả các loại sự kiện mà Cloud Functions hỗ trợ.

Để tìm hiểu thêm về Cloud Functions, bạn cũng có thể làm như sau: