อัปเกรดฟังก์ชัน Node.js รุ่นที่ 1 เป็นรุ่นที่ 2

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

ตัวอย่างในหน้านี้ถือว่าคุณใช้ JavaScript กับโมดูล CommonJS (require การนำเข้าสไตล์) แต่หลักการเดียวกันนี้ใช้ได้กับ JavaScript ที่มี ESM (import … from การนำเข้าสไตล์) และ TypeScript

กระบวนการย้ายข้อมูล

ฟังก์ชันรุ่นที่ 1 และรุ่นที่ 2 สามารถอยู่ร่วมกันในไฟล์เดียวกันได้ ซึ่งจะช่วยให้คุณย้ายข้อมูลทีละส่วนได้อย่างง่ายดายเมื่อพร้อม เราขอแนะนำให้ ย้ายข้อมูลฟังก์ชันทีละรายการ ทำการทดสอบและยืนยันก่อน ดำเนินการต่อ

ยืนยัน Firebase CLI และเวอร์ชัน firebase-function

ตรวจสอบว่าคุณใช้ Firebase CLI เวอร์ชัน 12.00 เป็นอย่างน้อย และ firebase-functions เวอร์ชัน 4.3.0 ส่วนเวอร์ชันใหม่กว่าจะรองรับทั้งรุ่นที่ 2 และรุ่นที่ 1

อัปเดตการนำเข้า

ฟังก์ชันรุ่นที่ 2 จะนำเข้าจากแพ็กเกจย่อย v2 ใน SDK firebase-functions เส้นทางการนำเข้าที่แตกต่างกันนี้คือทั้งหมดที่ Firebase CLI ต้องการเพื่อพิจารณาว่าจะ ติดตั้งใช้งานโค้ดฟังก์ชันเป็นฟังก์ชันรุ่นที่ 1 หรือรุ่นที่ 2

v2 Subpackage เป็นแบบแยกส่วน และเราขอแนะนำให้นำเข้าเฉพาะโมดูลที่ต้องการ เท่านั้น

ก่อน: รุ่นที่ 1

const functions = require("firebase-functions/v1");

หลัง: รุ่นที่ 2

// explicitly import each trigger
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

อัปเดตคำจำกัดความของทริกเกอร์

เนื่องจาก SDK รุ่นที่ 2 จะเน้นการนำเข้าแบบแยกส่วน ให้อัปเดตคำจำกัดความของทริกเกอร์เพื่อ แสดงการนำเข้าที่เปลี่ยนแปลงจากขั้นตอนก่อนหน้า

อาร์กิวเมนต์ที่ส่งไปยังการเรียกกลับสำหรับทริกเกอร์บางรายการมีการเปลี่ยนแปลง ใน ตัวอย่างนี้ โปรดสังเกตว่าอาร์กิวเมนต์ของแฮนเดิล onDocumentCreated ได้รับการ รวมเป็นออบเจ็กต์ event เดียว นอกจากนี้ ทริกเกอร์บางรายการยังมี ฟีเจอร์การกำหนดค่าใหม่ที่สะดวก เช่น ตัวเลือก cors ของonRequestทริกเกอร์

ก่อน: รุ่นที่ 1

const functions = require("firebase-functions/v1");

exports.date = functions.https.onRequest((req, res) => {
  // ...
});

exports.uppercase = functions.firestore
  .document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

หลัง: รุ่นที่ 2

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

ใช้การกำหนดค่าแบบพารามิเตอร์

ฟังก์ชันรุ่นที่ 2 จะเลิกการรองรับ functions.config เพื่อให้มีอินเทอร์เฟซที่ปลอดภัยยิ่งขึ้นสำหรับการกำหนดพารามิเตอร์การกำหนดค่าแบบประกาศภายในโค้ดเบส โมดูล params ใหม่จะบล็อกการติดตั้งใช้งาน CLI เว้นแต่พารามิเตอร์ทั้งหมด จะมีค่าที่ถูกต้อง เพื่อให้มั่นใจว่าจะไม่มีการติดตั้งใช้งานฟังก์ชันที่มีการกำหนดค่า ที่ขาดหายไป

ก่อน: รุ่นที่ 1

const functions = require("firebase-functions/v1");

exports.getQuote = functions.https.onRequest(async (req, res) => {
  const quote = await fetchMotivationalQuote(functions.config().apiKey);
  // ...
});

หลัง: รุ่นที่ 2

const {onRequest} = require("firebase-functions/v2/https");
const {defineSecret} = require("firebase-functions/params");

// Define the secret parameter
const apiKey = defineSecret("API_KEY");

exports.getQuote = onRequest(
  // make the secret available to this function
  { secrets: [apiKey] },
  async (req, res) => {
    // retrieve the value of the secret
    const quote = await fetchMotivationalQuote(apiKey.value());
    // ...
  }
);

หากมีการกำหนดค่าสภาพแวดล้อมที่มีอยู่ด้วย functions.config ให้ย้ายข้อมูล การกำหนดค่านี้เป็นส่วนหนึ่งของการอัปเกรดเป็นรุ่นที่ 2

functions.config API เลิกใช้งานแล้วและจะหยุดให้บริการในเดือนมีนาคม 2027 หลังจากวันที่ดังกล่าว การติดตั้งใช้งานที่มี functions.config จะล้มเหลว

หากต้องการป้องกันไม่ให้การติดตั้งใช้งานล้มเหลว ให้ย้ายข้อมูลการกำหนดค่าไปยัง Cloud Secret Manager โดยใช้ Firebase CLI เราขอแนะนำอย่างยิ่งให้ใช้วิธีนี้เนื่องจากเป็นวิธีที่มีประสิทธิภาพและปลอดภัยที่สุดในการย้ายข้อมูลการกำหนดค่า

1. ส่งออกการกำหนดค่าด้วย FirebaseCLI

   ใช้คำสั่ง config export เพื่อส่งออกการกำหนดค่าสภาพแวดล้อมที่มีอยู่ไปยังข้อมูลลับใหม่ใน Cloud Secret Manager

   $ firebase functions:config:export
   i  This command retrieves your Runtime Config values (accessed via functions.config())
      and exports them as a Secret Manager secret.
   
   i  Fetching your existing functions.config() from your project...  ✔
      Fetched your existing functions.config().
   
   i  Configuration to be exported:
   ⚠  This may contain sensitive data. Do not share this output.
   
   {
      ...
   }
   
   ✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG
   
   ✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```
   

2. อัปเดตโค้ดฟังก์ชันเพื่อเชื่อมโยงข้อมูลลับ

   หากต้องการใช้การกำหนดค่าที่จัดเก็บไว้ใน Secret ใหม่ใน Cloud Secret Manager ให้ใช้ defineJsonSecret API ในแหล่งที่มาของฟังก์ชัน นอกจากนี้ โปรดตรวจสอบว่าได้ เชื่อมโยงข้อมูลลับกับฟังก์ชันทั้งหมดที่ต้องการข้อมูลลับ

   ก่อน

   const functions = require("firebase-functions/v1");
   
   exports.myFunction = functions.https.onRequest((req, res) => {
     const apiKey = functions.config().someapi.key;
     // ...
   });
   

   หลัง

   const { onRequest } = require("firebase-functions/v2/https");
   const { defineJsonSecret } = require("firebase-functions/params");
   
   const config = defineJsonSecret("RUNTIME_CONFIG");
   
   exports.myFunction = onRequest(
     // Bind secret to your function
     { secrets: [config] },
     (req, res) => {
       // Access secret values via .value()
       const apiKey = config.value().someapi.key;
       // ...
   });
   

3. ทำให้ฟังก์ชันใช้งานได้

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

   firebase deploy --only functions:<your-function-name>
   

ตั้งค่าตัวเลือกของรันไทม์

การกำหนดค่าตัวเลือกขณะรันไทม์ มีการเปลี่ยนแปลงระหว่างรุ่นที่ 1 กับรุ่นที่ 2 นอกจากนี้ รุ่นที่ 2 ยังเพิ่มความสามารถใหม่ในการ ตั้งค่าตัวเลือกสำหรับฟังก์ชันทั้งหมด

ก่อน: รุ่นที่ 1

const functions = require("firebase-functions/v1");

exports.date = functions
  .runWith({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  })
  // locate function closest to users
  .region("asia-northeast1")
  .https.onRequest((req, res) => {
    // ...
  });

exports.uppercase = functions
  // locate function closest to users and database
  .region("asia-northeast1")
  .firestore.document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

หลัง: รุ่นที่ 2

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions/v2");

// locate all functions closest to users
setGlobalOptions({ region: "asia-northeast1" });

exports.date = onRequest({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  }, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

อัปเดตบัญชีบริการเริ่มต้น (ไม่บังคับ)

แม้ว่าฟังก์ชันรุ่นที่ 1 จะใช้บัญชีบริการเริ่มต้นของ Google App Engine เพื่อ ให้สิทธิ์เข้าถึง Firebase API แต่ฟังก์ชันรุ่นที่ 2 จะใช้บัญชีบริการเริ่มต้นของ Compute Engine ความแตกต่างนี้อาจทำให้เกิดปัญหาเกี่ยวกับสิทธิ์สำหรับ ฟังก์ชันที่ย้ายข้อมูลไปยังรุ่นที่ 2 ในกรณีที่คุณให้สิทธิ์พิเศษ แก่บัญชีบริการรุ่นที่ 1 หากไม่ได้เปลี่ยนสิทธิ์ของบัญชีบริการ ให้ข้ามขั้นตอนนี้

วิธีแก้ปัญหาที่แนะนำคือการกำหนดบัญชีบริการเริ่มต้นของ App Engine รุ่นที่ 1 ที่มีอยู่ให้กับฟังก์ชันที่คุณต้องการย้ายข้อมูลไปยังรุ่นที่ 2 อย่างชัดเจน โดยแทนที่ค่าเริ่มต้นของรุ่นที่ 2 คุณทำได้โดยตรวจสอบว่าฟังก์ชันที่ย้ายข้อมูลแต่ละรายการ กำหนดค่าที่ถูกต้องสำหรับ serviceAccountEmail ดังนี้

const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions");

// Use the App Engine default service account for all functions
setGlobalOptions({serviceAccountEmail: '<my-project-number>@<wbr>appspot.gserviceaccount.com'});

// Now I use the App Engine default service account.
exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

// I do too!
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  // ...
});

หรือคุณอาจแก้ไขรายละเอียดบัญชีบริการให้ตรงกับสิทธิ์ที่จำเป็นทั้งหมดในทั้งบัญชีบริการเริ่มต้นของ App Engine (สำหรับรุ่นที่ 1) และบัญชีบริการเริ่มต้นของ Compute Engine (สำหรับรุ่นที่ 2)

ใช้การทำงานพร้อมกัน

ข้อได้เปรียบที่สำคัญของฟังก์ชันรุ่นที่ 2 คือความสามารถของอินสแตนซ์ฟังก์ชันเดียว ในการจัดการคำขอมากกว่า 1 รายการพร้อมกัน ซึ่งจะช่วยลดจำนวน Cold Start ที่ผู้ใช้ปลายทางพบได้อย่างมาก โดยค่าเริ่มต้น ระบบจะตั้งค่าการทำงานพร้อมกันไว้ที่ 80 แต่คุณสามารถตั้งค่าใดก็ได้ตั้งแต่ 1 ถึง 1,000

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // set concurrency value
    concurrency: 500
  },
  (req, res) => {
    // ...
});

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

ตรวจสอบการใช้ตัวแปรส่วนกลาง

ฟังก์ชันรุ่นที่ 1 ที่เขียนโดยไม่ได้คำนึงถึงการทำงานพร้อมกันอาจใช้ตัวแปรส่วนกลาง ซึ่งตั้งค่าและอ่านในแต่ละคำขอ เมื่อเปิดใช้การทำงานพร้อมกันและอินสแตนซ์เดียวเริ่มจัดการคำขอหลายรายการพร้อมกัน อาจทำให้เกิดข้อบกพร่องในฟังก์ชันเนื่องจากคำขอที่ทำงานพร้อมกันจะเริ่มตั้งค่าและอ่านตัวแปรส่วนกลางพร้อมกัน

ขณะอัปเกรด คุณสามารถตั้งค่า CPU ของฟังก์ชันเป็น gcf_gen1 และตั้งค่า concurrency เป็น 1 เพื่อคืนค่าลักษณะการทำงานของรุ่นที่ 1 ได้โดยทำดังนี้

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // TEMPORARY FIX: remove concurrency
    cpu: "gcf_gen1",
    concurrency: 1
  },
  (req, res) => {
    // ...
});

อย่างไรก็ตาม เราไม่แนะนำให้ใช้วิธีนี้เป็นการแก้ไขระยะยาว เนื่องจากจะทำให้เสียข้อได้เปรียบด้านประสิทธิภาพของฟังก์ชันรุ่นที่ 2 แต่ให้ตรวจสอบการใช้ตัวแปรส่วนกลางในฟังก์ชัน และนำการตั้งค่าชั่วคราวเหล่านี้ออกเมื่อพร้อม

ย้ายการรับส่งข้อมูลไปยังฟังก์ชันรุ่นที่ 2 ใหม่

เช่นเดียวกับเมื่อเปลี่ยนภูมิภาคหรือประเภททริกเกอร์ของฟังก์ชัน คุณจะต้องตั้งชื่อใหม่ให้กับฟังก์ชันรุ่นที่ 2 และค่อยๆ ย้ายการเข้าชมไปยังฟังก์ชันดังกล่าว

คุณไม่สามารถอัปเกรดฟังก์ชันจากรุ่นที่ 1 เป็นรุ่นที่ 2 โดยใช้ชื่อเดียวกัน และเรียกใช้ firebase deploy ได้ การดำเนินการดังกล่าวจะทำให้เกิดข้อผิดพลาดต่อไปนี้

Upgrading from GCFv1 to GCFv2 is not yet supported. Please delete your old function or wait for this feature to be ready.

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

1. เปลี่ยนชื่อฟังก์ชันในโค้ดฟังก์ชัน เช่น เปลี่ยนชื่อ resizeImage เป็น resizeImageSecondGen
2. ติดตั้งใช้งานฟังก์ชันเพื่อให้ทั้งฟังก์ชันรุ่นที่ 1 เดิมและฟังก์ชันรุ่นที่ 2 ทำงาน
   1. ในกรณีของทริกเกอร์ที่เรียกใช้ได้, Task Queue และ HTTP ให้เริ่มชี้ไคลเอ็นต์ทั้งหมดไปยังฟังก์ชันรุ่นที่ 2 โดยการอัปเดตโค้ดไคลเอ็นต์ด้วยชื่อหรือ URL ของฟังก์ชันรุ่นที่ 2
   2. เมื่อใช้ทริกเกอร์ในเบื้องหลัง ฟังก์ชันทั้งรุ่นที่ 1 และรุ่นที่ 2 จะตอบสนองต่อทุกเหตุการณ์ทันทีเมื่อมีการติดตั้งใช้งาน
3. เมื่อย้ายข้อมูลการรับส่งทั้งหมดออกแล้ว ให้ลบฟังก์ชันรุ่นที่ 1 โดยใช้คำสั่ง firebase functions:delete ของ Firebase CLI
   1. เปลี่ยนชื่อฟังก์ชันรุ่นที่ 2 ให้ตรงกับชื่อฟังก์ชันรุ่นที่ 1 (ไม่บังคับ)