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


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

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

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

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

npm install -g firebase-tools

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

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

เมื่อเริ่มต้นใช้งาน Firebase SDK สําหรับ Cloud Functions จะเป็นการสร้างขึ้นโปรเจ็กต์ว่างที่มีไลบรารีที่ใช้ร่วมกันและโค้ดตัวอย่างขั้นต่ำบางส่วน และคุณเลือก 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 โดยใช้คำสั่ง Node 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 เป็นวิธีที่มีประสิทธิภาพในการผสานรวม Firebase โดยใช้ Cloud Functions ในทุกที่ที่รองรับ เช่นเดียวกับที่รองรับใน FCM, Authentication และ Firebase Realtime Database

Firebase CLI จะติดตั้ง Firebase และ Firebase SDK สําหรับโมดูล 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 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 ที่ส่งไปยังการเรียกกลับ onRequest()

ฟังก์ชัน HTTP เป็นการทำงานแบบซิงค์ (คล้ายกับฟังก์ชันที่เรียกใช้ได้) คุณจึงควรส่งการตอบกลับโดยเร็วที่สุดและเลื่อนการทำงานโดยใช้ Cloud Firestore ฟังก์ชัน addMessage() HTTP จะส่งค่าข้อความไปยังปลายทาง 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} จะล้อมรอบ "พารามิเตอร์" ซึ่งเป็นไวลด์การ์ดที่แสดงข้อมูลที่ตรงกันในคอลแบ็ก

Cloud Firestore จะทริกเกอร์การเรียกกลับ onCreate() ทุกครั้งที่มีการเพิ่มข้อความใหม่

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

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

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

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

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

  2. ใช้เอาต์พุต addMessage() URL ที่ 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 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 คุณยังทําสิ่งต่อไปนี้ได้ด้วย