อัปเกรดฟังก์ชัน 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 เป็นโมดูลย่อย และเราขอแนะนำให้นำเข้าเฉพาะ ที่คุณต้องการ

ก่อน: รุ่นที่ 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 รองรับการนำเข้าแบบโมดูล ดังนั้นโปรดอัปเดตคำจำกัดความของทริกเกอร์เป็น จะแสดงการนำเข้าที่เปลี่ยนแปลงจากขั้นตอนก่อนหน้า

อาร์กิวเมนต์ที่ส่งผ่านไปยัง Callback สำหรับทริกเกอร์บางรายการมีการเปลี่ยนแปลง ด้วยวิธีนี้ ตัวอย่างเช่น โปรดทราบว่าอาร์กิวเมนต์ของ Callback 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 จะบล็อกการทำให้ใช้งานได้ เว้นแต่ว่าพารามิเตอร์ทั้งหมดจะมีค่าที่ถูกต้อง ซึ่งทำให้ฟังก์ชันไม่ได้ทำให้ใช้งานได้โดยที่ขาดการกำหนดค่า

ย้ายข้อมูลไปยังแพ็กเกจย่อย params

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

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

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

exports.date = functions.https.onRequest((req, res) => {
  const date = new Date();
  const formattedDate =
date.toLocaleDateString(functions.config().dateformat);

  // ...
});

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

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

const dateFormat = defineString("DATE_FORMAT");

exports.date = onRequest((req, res) => {
  const date = new Date();
  const formattedDate = date.toLocaleDateString(dateFormat.value());

  // ...
});

ตั้งค่าพารามิเตอร์

ครั้งแรกที่คุณทำให้ใช้งานได้ ระบบจะแจ้ง Firebase CLI สำหรับค่าทั้งหมดของ และบันทึกค่าในไฟล์ dotenv หากต้องการส่งออก ค่า Functions.config ให้เรียกใช้ firebase functions:config:export

เพื่อความปลอดภัยยิ่งขึ้น คุณสามารถระบุประเภทพารามิเตอร์และกฎการตรวจสอบได้ด้วย

กรณีพิเศษ: คีย์ API

โมดูล params จะผสานรวมกับ Cloud Secret Manager ซึ่งทำให้ การควบคุมการเข้าถึงค่าที่มีความละเอียดอ่อน เช่น คีย์ API แบบละเอียด โปรดดู พารามิเตอร์ลับ เพื่อดูข้อมูลเพิ่มเติม

ก่อน: รุ่นที่ 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());
    // ...
  }
);

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

การกำหนดค่าตัวเลือกรันไทม์ มีการเปลี่ยนแปลงระหว่างรุ่นที่ 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) => {
  /* ... */
});

ใช้การเกิดขึ้นพร้อมกัน

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

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.

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

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