เริ่มต้นใช้งาน: เขียน ทดสอบ และทำให้ฟังก์ชันแรกใช้งานได้


หากต้องการเริ่มต้นใช้งาน Cloud Functions โปรดลองทำตามบทแนะนำนี้ ซึ่งจะเริ่มจากงานตั้งค่าที่จำเป็นและผ่านการสร้าง ทดสอบ และทำให้ฟังก์ชันที่เกี่ยวข้อง 2 รายการใช้งานได้ ดังนี้

  • ฟังก์ชัน "เพิ่มข้อความ" ที่แสดง URL ที่ยอมรับค่าข้อความและเขียนไปยัง Cloud Firestore
  • ฟังก์ชัน "ทำให้เป็นตัวพิมพ์ใหญ่" ที่ทริกเกอร์ใน Cloud Firestore เขียนและเปลี่ยนข้อความเป็นตัวพิมพ์ใหญ่

เราได้เลือก Cloud Firestore และฟังก์ชัน JavaScript ที่ทริกเกอร์ HTTP สำหรับตัวอย่างนี้ส่วนหนึ่งเนื่องจากทริกเกอร์พื้นหลังเหล่านี้ได้รับการทดสอบอย่างละเอียดผ่านชุดโปรแกรมจำลองภายในของ Firebase ชุดเครื่องมือนี้ยังรองรับทริกเกอร์ Realtime Database, PubSub, การตรวจสอบสิทธิ์ และ HTTP ที่เรียกใช้ได้ด้วย ทริกเกอร์พื้นหลังประเภทอื่นๆ เช่น ทริกเกอร์การกำหนดค่าระยะไกล, TestLab และ Analytics จะทดสอบแบบอินเทอร์แอกทีฟได้ทั้งหมดโดยใช้เครื่องมือที่ไม่ได้อธิบายในหน้านี้

ส่วนต่อไปของบทแนะนำนี้จะอธิบายขั้นตอนที่จำเป็นในการสร้าง ทดสอบ และทำให้ตัวอย่างใช้งานได้ หากต้องการเรียกใช้โค้ดและตรวจสอบโค้ด ให้ข้ามไปที่ ตรวจสอบโค้ดตัวอย่างที่สมบูรณ์

สร้างโปรเจ็กต์ Firebase

  1. ในคอนโซล Firebase ให้คลิกเพิ่มโปรเจ็กต์

    • หากต้องการเพิ่มทรัพยากร Firebase ไปยังโปรเจ็กต์ Google Cloud ที่มีอยู่ ให้ป้อนชื่อโปรเจ็กต์หรือเลือกจากเมนูแบบเลื่อนลง

    • หากต้องการสร้างโปรเจ็กต์ใหม่ ให้ป้อนชื่อโปรเจ็กต์ที่ต้องการ คุณยังแก้ไขรหัสโปรเจ็กต์ที่แสดงใต้ชื่อโปรเจ็กต์ได้อีกด้วย

  2. หากได้รับข้อความแจ้ง ให้ตรวจสอบและยอมรับข้อกำหนดของ Firebase

  3. คลิกดำเนินการต่อ

  4. (ไม่บังคับ) ตั้งค่า Google Analytics สำหรับโปรเจ็กต์ที่จะช่วยให้คุณได้รับประสบการณ์ที่ดีที่สุดเมื่อใช้ผลิตภัณฑ์ Firebase ต่อไปนี้

    เลือกบัญชี Google Analytics ที่มีอยู่หรือสร้างบัญชีใหม่

    หากคุณสร้างบัญชีใหม่ ให้เลือกตำแหน่งการรายงานของ Analytics จากนั้นยอมรับการตั้งค่าการแชร์ข้อมูลและข้อกำหนดของ Google Analytics สำหรับโปรเจ็กต์

  5. คลิกสร้างโปรเจ็กต์ (หรือเพิ่ม Firebase หากใช้โปรเจ็กต์ Google Cloud ที่มีอยู่)

Firebase จะจัดสรรทรัพยากรสำหรับโปรเจ็กต์ Firebase โดยอัตโนมัติ เมื่อขั้นตอนเสร็จสมบูรณ์ ระบบจะนำคุณไปที่หน้าภาพรวมของโปรเจ็กต์ Firebase ในคอนโซล Firebase

ตั้งค่า Node.js และ Firebase CLI

คุณจะต้องมีสภาพแวดล้อม Node.js เพื่อเขียนฟังก์ชัน และจะต้องใช้ Firebase CLI เพื่อทำให้ฟังก์ชันใช้งานได้ในรันไทม์ Cloud Functions สำหรับการติดตั้ง Node.js และ npm ขอแนะนำให้ใช้เครื่องมือจัดการเวอร์ชันโหนด

เมื่อติดตั้ง Node.js และ npm แล้ว ให้ติดตั้ง Firebase CLI ผ่านวิธีการที่ต้องการ หากต้องการติดตั้ง CLI ผ่าน npm ให้ใช้:

npm install -g firebase-tools

การดำเนินการนี้จะติดตั้งคำสั่ง Firebase ที่ใช้ได้ทั่วโลก หากคำสั่งไม่สำเร็จ คุณอาจต้องเปลี่ยนสิทธิ์ npm หากต้องการอัปเดต firebase-tools เป็นเวอร์ชันล่าสุด ให้เรียกใช้คำสั่งเดิมอีกครั้ง

เริ่มต้นโปรเจ็กต์

เมื่อเริ่ม Firebase SDK สำหรับ Cloud Functions คุณจะสร้างโปรเจ็กต์ว่างที่มีทรัพยากร Dependency และโค้ดตัวอย่างขั้นต่ำบางส่วน รวมถึงเลือก TypeScript หรือ JavaScript สำหรับการเขียนฟังก์ชัน เพื่อให้เป็นไปตามวัตถุประสงค์ของบทแนะนำนี้ คุณจะต้องเริ่มต้น Cloud Firestore ด้วย

วิธีเริ่มต้นโปรเจ็กต์

  1. เรียกใช้ firebase login เพื่อเข้าสู่ระบบผ่านเบราว์เซอร์และตรวจสอบสิทธิ์ Firebase CLI
  2. ไปที่ไดเรกทอรีโปรเจ็กต์ Firebase
  3. เรียกใช้ firebase init firestore สำหรับบทแนะนำนี้ คุณอาจยอมรับค่าเริ่มต้นเมื่อมีข้อความแจ้งเกี่ยวกับกฎ Firestore และไฟล์ดัชนี หากยังไม่เคยใช้ Cloud Firestore ในโปรเจ็กต์นี้ คุณจะต้องเลือกโหมดและตำแหน่งเริ่มต้นสำหรับ Firestore ตามที่อธิบายไว้ในเริ่มต้นใช้งาน Cloud Firestore
  4. เรียกใช้ firebase init functions โดย CLI จะแจ้งให้คุณเลือกโค้ดเบสที่มีอยู่ หรือเริ่มต้นและตั้งชื่อโค้ดใหม่ เมื่อคุณเพิ่งเริ่มต้น โค้ดเบสเดียวในตำแหน่งเริ่มต้นก็เพียงพอแล้ว หลังจากนั้นเมื่อการใช้งานจะขยายออก คุณอาจต้องจัดระเบียบฟังก์ชันในโค้ดเบส

  5. CLI มี 2 ตัวเลือกสำหรับการรองรับภาษา ดังนี้

    เลือก JavaScript สำหรับบทแนะนำนี้

  6. CLI จะมีตัวเลือกให้คุณติดตั้งทรัพยากร Dependency ด้วย npm แต่คุณสามารถปฏิเสธได้หากต้องการจัดการการอ้างอิงด้วยวิธีอื่น แต่หากต้องการปฏิเสธ คุณจะต้องเรียกใช้ npm install ก่อนที่จะจำลองหรือทำให้ฟังก์ชันใช้งานได้

หลังจากคำสั่งเหล่านี้เสร็จสมบูรณ์แล้ว โครงสร้างโปรเจ็กต์จะมีลักษณะดังนี้

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

ไฟล์ package.json ที่สร้างขึ้นระหว่างการเริ่มต้นมีคีย์สำคัญคือ "engines": {"node": "16"} โหมดนี้จะระบุเวอร์ชัน Node.js ของคุณสำหรับการเขียนและการทำให้ฟังก์ชันใช้งานได้ คุณเลือกเวอร์ชันอื่นๆ ที่รองรับได้

นำเข้าโมดูลที่จำเป็นและเริ่มต้นแอป

หลังจากทำงานตั้งค่าเสร็จแล้ว คุณสามารถเปิดไดเรกทอรีต้นทางและเริ่มเพิ่มโค้ดได้ตามที่อธิบายไว้ในส่วนต่อไปนี้ สำหรับตัวอย่างนี้ โปรเจ็กต์ของคุณต้องนำเข้าโมดูล Cloud Functions และ Admin SDK โดยใช้คำสั่ง require ของโหนด เพิ่มบรรทัดต่อไปนี้ลงในไฟล์ index.js

// 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

บรรทัดเหล่านี้จะโหลดโมดูล firebase-functions และ firebase-admin และเริ่มต้นอินสแตนซ์ของแอป admin ที่จะทำการเปลี่ยนแปลง Cloud Firestore ได้ เมื่อใดก็ตามที่การรองรับ Admin SDK พร้อมให้บริการ เช่นเดียวกับ FCM, การตรวจสอบสิทธิ์ และฐานข้อมูลเรียลไทม์ของ Firebase ฟีเจอร์ดังกล่าวจะมอบวิธีที่มีประสิทธิภาพในการผสานรวม Firebase โดยใช้ฟังก์ชันระบบคลาวด์

Firebase CLI จะติดตั้ง Firebase และ Firebase SDK สำหรับโมดูลโหนด Cloud Functions โดยอัตโนมัติเมื่อคุณเริ่มต้นโปรเจ็กต์ หากต้องการเพิ่มไลบรารีของบุคคลที่สามลงในโปรเจ็กต์ คุณจะแก้ไข package.json และเรียกใช้ npm install ได้ ดูข้อมูลเพิ่มเติมได้ที่ทรัพยากร Dependency ของแฮนเดิล

เพิ่มฟังก์ชัน addMessage()

สำหรับฟังก์ชัน addMessage() ให้เพิ่มบรรทัดต่อไปนี้ใน 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

ฟังก์ชัน addMessage() เป็นปลายทาง HTTP คำขอที่ส่งไปยังปลายทางจะส่งผลให้เกิดออบเจ็กต์ Request และ Response ในรูปแบบ ExpressJS ที่ส่งไปยัง Callback ของ onRequest()

ฟังก์ชัน HTTP ทำงานพร้อมกัน (คล้ายกับฟังก์ชันที่เรียกได้) คุณจึงควรส่งการตอบกลับโดยเร็วที่สุดและเลื่อนเวลาการทำงานโดยใช้ Cloud Firestore ฟังก์ชัน HTTP addMessage() จะส่งค่าข้อความไปยังปลายทาง HTTP และแทรกลงในฐานข้อมูลภายใต้เส้นทาง /messages/:documentId/original

เพิ่มฟังก์ชัน makeUppercase()

สำหรับฟังก์ชัน makeUppercase() ให้เพิ่มบรรทัดต่อไปนี้ใน 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

ฟังก์ชัน makeUppercase() จะทำงานเมื่อมีการเขียน Cloud Firestore ฟังก์ชัน ref.set จะกำหนดเอกสารที่จะฟัง ในเรื่องประสิทธิภาพ คุณควรให้ข้อมูลที่เจาะจงที่สุด

วงเล็บปีกกา เช่น {documentId} ล้อมรอบ "พารามิเตอร์" ซึ่งเป็นไวลด์การ์ดที่แสดงข้อมูลที่ตรงกันใน Callback

Cloud Firestore ทริกเกอร์ Callback onCreate() เมื่อใดก็ตามที่มีการเพิ่มข้อความใหม่

ฟังก์ชันที่ขับเคลื่อนด้วยเหตุการณ์ เช่น เหตุการณ์ Cloud Firestore จะเป็นแบบไม่พร้อมกัน ฟังก์ชัน Callback ควรแสดงผล null, ออบเจ็กต์ หรือ Promise หากไม่แสดงผลใดๆ ฟังก์ชันจะหมดเวลาซึ่งเป็นการส่งสัญญาณข้อผิดพลาด แล้วลองอีกครั้ง โปรดดูการซิงค์ ไม่พร้อมกัน และสัญญา

จำลองการดำเนินการของฟังก์ชัน

Firebase Local Emulator Suite ช่วยให้คุณสร้างและทดสอบแอปในเครื่องของคุณเองได้ แทนที่จะนำไปทำให้ใช้งานได้ในโปรเจ็กต์ Firebase เราขอแนะนำเป็นอย่างยิ่งให้ใช้การทดสอบในเครื่องระหว่างการพัฒนา ซึ่งส่วนหนึ่งเป็นเพราะลดความเสี่ยงจากข้อผิดพลาดในการเขียนโค้ดซึ่งอาจก่อให้เกิดค่าใช้จ่ายในสภาพแวดล้อมการใช้งานจริง (เช่น การวนซ้ำอย่างไม่สิ้นสุด)

วิธีจำลองฟังก์ชัน

  1. เรียกใช้ firebase emulators:start และตรวจสอบเอาต์พุตสำหรับ URL ของ UI ของชุดโปรแกรมจำลอง โดยมีค่าเริ่มต้นเป็น localhost:4000 แต่อาจโฮสต์ในพอร์ตอื่นในเครื่องของคุณ โดยป้อน URL ดังกล่าวในเบราว์เซอร์เพื่อเปิด UI ของชุดโปรแกรมจำลอง

  2. ตรวจสอบเอาต์พุตของคำสั่ง firebase emulators:start สำหรับ URL ของฟังก์ชัน HTTP addMessage() โดยจะมีลักษณะคล้ายกับ http://localhost:5001/MY_PROJECT/us-central1/addMessage ยกเว้นเฉพาะ

    1. ระบบจะใช้รหัสโปรเจ็กต์แทน MY_PROJECT
    2. พอร์ตอาจแตกต่างกันในเครื่องของคุณ

  3. เพิ่มสตริงการค้นหา ?text=uppercaseme ต่อท้าย URL ของฟังก์ชัน ซึ่งควรมีลักษณะดังนี้ http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme หรือจะเปลี่ยนข้อความ "ตัวพิมพ์ใหญ่" ให้เป็นข้อความที่กำหนดเองก็ได้

  4. สร้างข้อความใหม่โดยเปิด URL ในแท็บใหม่ในเบราว์เซอร์

  5. วิธีดูผลของฟังก์ชันใน UI ชุดโปรแกรมจำลอง

    1. ในแท็บบันทึก คุณควรเห็นบันทึกใหม่ที่ระบุว่าฟังก์ชัน addMessage() และ makeUppercase() ทำงาน:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. ในแท็บ Firestore คุณควรเห็นเอกสารที่มีข้อความต้นฉบับและข้อความตัวพิมพ์ใหญ่ (หากตอนแรกเป็น "ตัวพิมพ์ใหญ่" คุณจะเห็น "ตัวพิมพ์ใหญ่")

ทำให้ฟังก์ชันใช้งานได้ในสภาพแวดล้อมที่ใช้งานจริง

เมื่อฟังก์ชันต่างๆ ทำงานได้ตามที่ต้องการในโปรแกรมจำลองแล้ว คุณสามารถทำให้ใช้งานได้ ทดสอบ และเรียกใช้ฟังก์ชันเหล่านั้นในสภาพแวดล้อมการใช้งานจริง โปรดทราบว่าหากต้องการทำให้ใช้งานได้กับสภาพแวดล้อมรันไทม์ Node.js 14 ที่แนะนำ โปรเจ็กต์ต้องอยู่ในแพ็กเกจราคา Blaze ดูราคาของ Cloud Functions

หากต้องการจบบทแนะนำ ให้ทำให้ฟังก์ชันใช้งานได้ จากนั้นเรียกใช้ addMessage() เพื่อทริกเกอร์ makeUppercase()

  1. เรียกใช้คำสั่งนี้เพื่อทำให้ฟังก์ชันใช้งานได้:

     firebase deploy --only functions

    หลังจากเรียกใช้คำสั่งนี้ Firebase CLI จะแสดง URL สำหรับปลายทางของฟังก์ชัน HTTP ที่เทอร์มินัล คุณควรเห็นบรรทัดต่อไปนี้

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

    URL จะมีรหัสโปรเจ็กต์และภูมิภาคสำหรับฟังก์ชัน HTTP แม้คุณจะไม่ต้องกังวลในตอนนี้ แต่ฟังก์ชัน HTTP เวอร์ชันที่ใช้งานจริงบางรายการควรระบุตำแหน่งเพื่อลดเวลาในการตอบสนองของเครือข่าย

    หากคุณพบข้อผิดพลาดในการเข้าถึง เช่น "ให้สิทธิ์เข้าถึงโปรเจ็กต์ไม่ได้" โปรดลองตรวจสอบชื่อแทนโปรเจ็กต์

  2. ใช้เอาต์พุตของ URL addMessage() โดย CLI ให้เพิ่มพารามิเตอร์การค้นหาข้อความ แล้วเปิดในเบราว์เซอร์

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

    ฟังก์ชันนี้จะดำเนินการและเปลี่ยนเส้นทางเบราว์เซอร์ไปยังคอนโซล Firebase ที่ตำแหน่งฐานข้อมูลที่เก็บสตริงข้อความไว้ เหตุการณ์การเขียนนี้จะทริกเกอร์ makeUppercase() ซึ่งจะเขียนสตริงเวอร์ชันตัวพิมพ์ใหญ่

หลังจากทำให้ฟังก์ชันใช้งานได้และดำเนินการแล้ว คุณจะดูบันทึกได้ใน Google Cloud Console หากต้องการลบฟังก์ชันในการพัฒนาหรือเวอร์ชันที่ใช้งานจริง ให้ใช้ Firebase CLI

ในการใช้งานจริง คุณอาจต้องการเพิ่มประสิทธิภาพการทำงานของฟังก์ชันและควบคุมต้นทุนโดยการกำหนดจำนวนอินสแตนซ์ขั้นต่ำและสูงสุดที่จะเรียกใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกรันไทม์เหล่านี้ได้ที่ควบคุมพฤติกรรมการปรับขนาด

ตรวจสอบโค้ดตัวอย่างที่สมบูรณ์

นี่คือ functions/index.js ที่สมบูรณ์ซึ่งมีฟังก์ชัน addMessage() และ makeUppercase() ฟังก์ชันเหล่านี้ช่วยให้คุณส่งพารามิเตอร์ไปยังปลายทาง HTTP ที่เขียนค่าไปยัง Cloud Firestore จากนั้นเปลี่ยนรูปแบบพารามิเตอร์ดังกล่าวโดยการใช้อักขระทับอักขระทั้งหมดในสตริง

// 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

ขั้นตอนถัดไป

ในเอกสารประกอบนี้ คุณจะได้เรียนรู้เพิ่มเติมเกี่ยวกับวิธีจัดการฟังก์ชันสำหรับ Cloud Functions รวมถึงวิธีจัดการประเภทเหตุการณ์ทั้งหมดที่ Cloud Functions รองรับ

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับ Cloud Functions คุณสามารถทำสิ่งต่อไปนี้ได้