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


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

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

เราได้เลือกฟังก์ชัน JavaScript Cloud Firestore และฟังก์ชัน JavaScript ที่ทริกเกอร์ HTTP สำหรับการดำเนินการนี้ ตัวอย่างบางส่วนเนื่องจากทริกเกอร์พื้นหลังเหล่านี้สามารถทดสอบได้อย่างละเอียด ผ่าน Firebase Local Emulator Suite ชุดเครื่องมือนี้ ยังรองรับ Realtime Database ด้วย ทริกเกอร์ PubSub, การตรวจสอบสิทธิ์ และ 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.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 ปลอดภัย ให้ปฏิเสธหากคุณต้องการจัดการ ทรัพยากร 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();

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

CLI ของ Firebase โดยอัตโนมัติ ติดตั้ง 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.` });
});

ฟังก์ชัน 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 จะทำงานแบบไม่พร้อมกัน ฟังก์ชัน 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 คุณควรเห็นเอกสารที่มีเอกสารต้นฉบับ รวมทั้งข้อความในเวอร์ชันตัวพิมพ์ใหญ่ (หากเป็น แต่เดิมคุณจะเห็น "ตัวพิมพ์ใหญ่" คุณจะเห็น "ตัวพิมพ์ใหญ่")

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

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

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

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

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