เริ่มต้น: เขียน ทดสอบ และปรับใช้ฟังก์ชันแรกของคุณ


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

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

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

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

npm install -g firebase-tools

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

เริ่มต้นโครงการของคุณ

เมื่อคุณเริ่มต้น Firebase SDK สำหรับฟังก์ชันระบบคลาวด์ คุณจะสร้างโปรเจ็กต์ว่างที่มีการขึ้นต่อกันและโค้ดตัวอย่างขั้นต่ำบางส่วน และคุณเลือก 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 แจ้งให้คุณเลือกฐานรหัสที่มีอยู่หรือเริ่มต้นและตั้งชื่อฐานใหม่ เมื่อคุณเพิ่งเริ่มต้น codebase เดียวในตำแหน่งเริ่มต้นก็เพียงพอแล้ว ในภายหลัง เมื่อการใช้งานของคุณขยายตัว คุณอาจต้องการ จัดระเบียบฟังก์ชันใน codebases
  5. CLI มีตัวเลือกสองทางสำหรับการรองรับภาษา:

    สำหรับบทช่วยสอนนี้ ให้เลือก JavaScript

  6. CLI ให้ตัวเลือกแก่คุณในการติดตั้งการขึ้นต่อกันด้วย 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();

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

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

เพิ่มฟังก์ชัน 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.` });
});

ฟังก์ชัน 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 });
  });

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

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

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

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

จำลองการทำงานของฟังก์ชันของคุณ

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 หรือคุณสามารถเปลี่ยนข้อความ "ตัวพิมพ์ใหญ่" เป็นข้อความที่กำหนดเองได้

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

  5. ดูผลกระทบของฟังก์ชันใน Emulator Suite UI:

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

ปรับใช้ฟังก์ชันกับสภาพแวดล้อมการผลิต

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

หากต้องการเสร็จสิ้นบทช่วยสอน ให้ปรับใช้ฟังก์ชันของคุณ จากนั้นดำเนินการ 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 });
  });

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

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

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