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


หากต้องการเริ่มต้นใช้งาน 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 ปลอดภัย ให้ปฏิเสธหากคุณต้องการจัดการ ทรัพยากร 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 ข้อความ เพิ่มบรรทัด ดังต่อไปนี้ในไฟล์ 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 คำขอที่ส่งไปยังปลายทาง ผลการค้นหาในรูปแบบ 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} ล้อมรอบ "พารามิเตอร์" ไวลด์การ์ด ที่เปิดเผยข้อมูลที่ตรงกันใน Callback

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

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

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

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

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับฟังก์ชันระบบคลาวด์ โปรดทำดังนี้ ยังสามารถทำสิ่งต่างๆ ดังต่อไปนี้: