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


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

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

เราเลือกใช้ฟังก์ชัน JavaScript ที่ทริกเกอร์โดย Cloud Firestore และ 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 ต่อไปนี้ Firebase A/B Testing Cloud Messaging Crashlytics In-App Messaging และ Remote Config (รวมถึงการปรับเปลี่ยนในแบบของคุณ)

    เลือกบัญชี Google Analytics ที่มีอยู่ หรือสร้างบัญชีใหม่ หากสร้างบัญชีใหม่ ให้เลือกAnalyticsสถานที่ตั้งการรายงาน จากนั้นยอมรับการตั้งค่าการแชร์ข้อมูลและGoogle Analyticsข้อกำหนดสำหรับ โปรเจ็กต์

  5. คลิกสร้างโปรเจ็กต์ (หรือเพิ่ม Firebase หากคุณเพิ่ม Firebase ไปยังโปรเจ็กต์ Google Cloud ที่มีอยู่)

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

ตั้งค่า Node.js และ Firebase CLI

คุณจะต้องมีสภาพแวดล้อม Node.js เพื่อเขียนฟังก์ชัน และจะต้องมี Firebase CLI เพื่อทำให้ฟังก์ชันใช้งานได้ในรันไทม์ Cloud Functions ขอแนะนําให้ใช้ Node Version Manager ในการติดตั้ง 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 มีตัวเลือกการรองรับภาษาต่อไปนี้

    เลือก 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 มีการรองรับทุกที่ เช่น FCM, Authentication และ Firebase Realtime Database ซึ่งเป็นวิธีที่มีประสิทธิภาพในการผสานรวม Firebase โดยใช้ Cloud Functions

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

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

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