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


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

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

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

  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();
index.js

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

Firebase CLI จะติดตั้ง Firebase และ Firebase SDK สำหรับโมดูลโหนด Cloud Functions โดยอัตโนมัติเมื่อคุณเริ่มต้นโครงการ หากต้องการเพิ่มไลบรารีของบุคคลที่สามในโครงการของคุณ คุณสามารถแก้ไข 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.` });
});
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} ล้อมรอบ "พารามิเตอร์" สัญลักษณ์แทนที่แสดงข้อมูลที่ตรงกันในการเรียกกลับ

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

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

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

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

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

  2. ใช้เอาต์พุต URL addMessage() โดย CLI เพิ่มพารามิเตอร์ข้อความค้นหา และเปิดในเบราว์เซอร์:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo

    ฟังก์ชันดำเนินการและเปลี่ยนเส้นทางเบราว์เซอร์ไปยังคอนโซล Firebase ที่ตำแหน่งฐานข้อมูลที่เก็บสตริงข้อความ เหตุการณ์การเขียนนี้ทริกเกอร์ makeUppercase() ซึ่งเขียนสตริงตัวพิมพ์ใหญ่

หลังจากปรับใช้และเรียกใช้ฟังก์ชันแล้ว คุณสามารถดูบันทึกใน Google Cloud Console หากต้องการ ลบฟังก์ชัน ในการพัฒนาหรือใช้งานจริง ให้ใช้ 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 คุณสามารถดำเนินการดังต่อไปนี้: