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

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

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

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

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

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

ตรวจสอบ Firebase CLI และ firebase-functions เวอร์ชัน

ตรวจสอบว่าคุณใช้ CLI เวอร์ชัน 12.00 และ firebase-functions เวอร์ชัน 4.3.0 ขึ้นไปFirebase เวอร์ชันใหม่กว่าจะรองรับทั้งรุ่นที่ 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 ชอบการนำเข้าแบบโมดูลาร์ ให้อัปเดตคำจำกัดความของทริกเกอร์เพื่อแสดงการนำเข้าที่เปลี่ยนแปลงจากขั้นตอนก่อนหน้า

อาร์กิวเมนต์ที่ส่งไปยังฟังก์ชันเรียกกลับสำหรับทริกเกอร์บางรายการมีการเปลี่ยนแปลง ในตัวอย่างนี้ โปรดสังเกตว่าอาร์กิวเมนต์ไปยังฟังก์ชันเรียกกลับ 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) => {
  /* ... */
});

ลดความพยายามในการเขียนใหม่ด้วยการแยกโครงสร้าง JavaScript

หากฟังก์ชันของคุณมีเนื้อหาที่ซับซ้อนซึ่งอาศัยบริบทของรุ่นที่ 1 หรือพารามิเตอร์เฉพาะของผู้ให้บริการ (เช่น message หรือ snapshot) เป็นอย่างมาก คุณสามารถใช้ฟังก์ชันช่วยเหลือความเข้ากันได้ของรุ่นที่ 1 ที่สร้างขึ้นใน SDK รุ่นที่ 2

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

ข้อมูลอ้างอิงการแมปผู้ให้บริการ

ผู้ให้บริการ อาร์กิวเมนต์รุ่นที่ 1 การแยกโครงสร้างเหตุการณ์ที่แก้ไขแล้วของรุ่นที่ 2
Pub/Sub (message, context) ({ message, context }) => { ... }
Cloud Firestore (snapshot, context) ({ snapshot, context }) => { ... }
Cloud Storage (object, context) ({ object, context }) => { ... }
Realtime Database (snapshot, context) ({ snapshot, context }) => { ... }
Remote Config (version, context) ({ version, context }) => { ... }
Cloud Scheduler (context) ({ context }) => { ... }
คิวงาน (data, context) ({ data, context }) => { ... }

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

export const myPubSubV1 = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  const data = message.json;
  const eventId = context.eventId;
  // ... rest of the logic
});

ทางเลือกใหม่ (รุ่นที่ 2 พร้อมการแยกโครงสร้าง):

import { onMessagePublished } from "firebase-functions/v2/pubsub";

export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
  // No need to change the function body!
  const data = message.json;      // Uses v1 Message wrapper
  const eventId = context.eventId; // Uses v1 EventContext map
  // ... rest of the logic
});

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

ฟังก์ชันรุ่นที่ 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

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

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

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

    ใช้คำสั่ง 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. อัปเดตโค้ดฟังก์ชันเพื่อผูกข้อมูลลับ

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

    ก่อน

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

กลยุทธ์การย้ายข้อมูลจะขึ้นอยู่กับประเภททริกเกอร์ที่ฟังก์ชันใช้

ย้ายข้อมูลทริกเกอร์ที่เรียกใช้ได้, คิวงาน และ HTTP

ทริกเกอร์เหล่านี้เป็นการเรียกใช้โดยตรง เนื่องจากฟังก์ชันรุ่นที่ 2 จะมี ชื่อใหม่ (และ URL ใหม่สำหรับทริกเกอร์ HTTP) คุณจึงย้ายการรับส่งข้อมูลได้โดยการอัปเดต ไคลเอ็นต์

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

ย้ายข้อมูลทริกเกอร์เบื้องหลัง

ทริกเกอร์เบื้องหลัง (เช่น Pub/Sub, Cloud Firestore, และ Cloud Storage ทริกเกอร์) จะตอบสนองต่อเหตุการณ์ในโปรเจ็กต์ คุณต้องเรียกใช้ฟังก์ชันทั้งรุ่นที่ 1 และ รุ่นที่ 2 พร้อมกันชั่วคราวเพื่อไม่ให้พลาดเหตุการณ์ใดๆ ระหว่างการเปลี่ยนผ่าน

ในช่วงเปลี่ยนผ่าน ฟังก์ชันทั้ง 2 จะทริกเกอร์ในเหตุการณ์เดียวกัน ซึ่งหมายความว่าตรรกะทางธุรกิจจะทำงาน 2 ครั้งต่อเหตุการณ์ ตรวจสอบว่าฟังก์ชัน เป็น Idempotent ก่อนดำเนินการต่อ

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

    import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing 1st gen function ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("V1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 passthrough function ---
export const myPubSubV2 = onMessagePublished("my-topic", async ({ message, context }) => {
  console.log("v2 handler triggering V1 for event:", context.eventId);
  // Call the v1 function's handler
  await myPubSub.run(message, context);
});

  2. วิ่ง firebase deploy ตอนนี้ฟังก์ชันทั้ง 2 ทำงานอยู่และรับฟังเหตุการณ์เดียวกัน

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

  4. เมื่อมั่นใจว่าฟังก์ชันทำงานอย่างถูกต้องแล้ว ให้ย้ายตรรกะทางธุรกิจจริงจากฟังก์ชันรุ่นที่ 1 ไปยังเนื้อหาของฟังก์ชันรุ่นที่ 2 หากคุณใช้วิธีการส่งผ่าน ให้นำการเรียกใช้ myPubSub.run() ออก

    import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing v1 function (to be removed next) ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("v1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 function with full logic ---
export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
  console.log("v2 handler running for event:", context.eventId);
  // ... existing v1 function logic WAS MOVED HERE ...
});

    ทำให้การเปลี่ยนแปลงนี้ใช้งานได้

  5. นำคำจำกัดความของฟังก์ชันรุ่นที่ 1 ออกจากโค้ดแล้วทำให้ใช้งานได้อีกครั้ง CLI จะ แจ้งให้คุณลบฟังก์ชันรุ่นที่ 1 ออกจาก Google Cloud