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

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

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

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

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

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

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

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

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

npm install -g firebase-tools

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

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

เมื่อเริ่มต้นใช้งาน SDK ของ Firebase สำหรับ 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 มีตัวเลือกต่อไปนี้สำหรับการรองรับภาษา

   • JavaScript
   • Python
   • TypeScript ดูข้อมูลเพิ่มเติมได้ที่เขียนฟังก์ชันด้วย TypeScript

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

6. CLI จะให้ตัวเลือกในการติดตั้งทรัพยากร Dependency ด้วย npm คุณสามารถปฏิเสธได้อย่างปลอดภัยหากต้องการจัดการทรัพยากร Dependency ด้วยวิธีอื่น แต่หากปฏิเสธ คุณจะต้องเรียกใช้ 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 ของ Node เพิ่มบรรทัดต่อไปนี้ลงในไฟล์ 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 { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

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

CLI ของ Firebase จะติดตั้ง Firebase และ SDK ของ Firebase สำหรับโมดูล Node ของ 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 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

ฟังก์ชัน 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 ของ Emulator Suite UI โดยค่าเริ่มต้นจะเป็น localhost:4000 แต่อาจโฮสต์ในพอร์ตอื่นในเครื่องของคุณ ป้อน URL นั้นในเบราว์เซอร์เพื่อเปิด Emulator Suite 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 คุณสามารถเปลี่ยนข้อความ "uppercaseme" เป็นข้อความที่กำหนดเองได้ (ไม่บังคับ)

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

5. ดูผลลัพธ์ของฟังก์ชันใน Emulator Suite UI ดังนี้

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

ทำให้ฟังก์ชันใช้งานได้ในสภาพแวดล้อมฮาร์ดแวร์และซอฟต์แวร์

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

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

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

    firebase deploy --only functions
    

   หลังจากเรียกใช้คำสั่งนี้แล้ว CLI ของ Firebase จะแสดงผล 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 หากต้องการลบฟังก์ชันในการพัฒนาหรือเวอร์ชันที่ใช้งานจริง ให้ใช้ 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 { 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 = 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 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 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 คุณยังสามารถทำสิ่งต่อไปนี้ได้ด้วย

• อ่านข้อมูลเกี่ยวกับกรณีการใช้งานสำหรับ Cloud Functions
• ลองใช้ Codelab ของ Cloud Functions
• ตรวจสอบและเรียกใช้ตัวอย่างโค้ดใน GitHub