แนวทางปฏิบัติแนะนำหลังการย้ายข้อมูล

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

การใช้ชุดฟังก์ชันจากแพ็กเกจ npm โดยไม่ต้องย้ายข้อมูล

หากคุณไม่ได้ย้ายข้อมูลจากส่วนขยาย การใช้ชุดฟังก์ชันจะประกอบด้วย 2 ส่วนดังนี้

การติดตั้งชุดอุปกรณ์

คุณติดตั้งชุดฟังก์ชันได้โดยใช้คำสั่ง CLI ต่อไปนี้

firebase functions:kits:install --package <npm-package-name>

ตัวอย่างที่อธิบายอย่างละเอียด

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i  function-kits/firestore-bigquery-export/source/package.json is unchanged
i  function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i  function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i  functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i  functions: Building TypeScript source...
✔  Wrote configuration info to firebase.json

i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1

✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project

✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing

# Omitting many more parameters for brevity

✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

i  functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i  functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠  functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.

การเปลี่ยนตัวเลือกส่วนกลางเริ่มต้น

หากต้องการกำหนดค่าตัวเลือกส่วนกลางสำหรับอินสแตนซ์ชุด ให้แก้ไขไฟล์ index.ts ที่อยู่ใน function-kits/<your-kit-id>/source/src/index.ts

หากต้องการให้แชร์ค่าเริ่มต้นในทุกอินสแตนซ์ของชุด ให้ตั้งค่าโดยตรงใน index.ts หรือสร้างพารามิเตอร์ที่ตั้งค่าต่ออินสแตนซ์ โดยทำตามตัวอย่างและวิธีการที่ระบุไว้ใน index.ts

กำลังติดตั้งใช้งานชุดอุปกรณ์

หากต้องการติดตั้งใช้งานชุดฟังก์ชัน ให้เรียกใช้คำสั่งต่อไปนี้

firebase deploy --only functions:<kit-instance-id>

ตัวอย่างที่อธิบายอย่างละเอียด

firebase deploy --only functions:firestore-bigquery-export --project my-project

เอาต์พุต:

=== Deploying to 'my-project'...

i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.

✔  Deploy complete!

การติดตั้งและทำให้ชุดอุปกรณ์ใช้งานได้จะดำเนินการต่อไปนี้

  • สร้าง function-kits/firestore-bigquery-export/source ซึ่งมีแหล่งที่มาของชุดอุปกรณ์ รวมถึงไฟล์ index.ts พื้นฐานที่นำเข้าและส่งออกแพ็กเกจชุดอุปกรณ์ขณะตั้งค่าพารามิเตอร์ที่ให้คุณเลือกตำแหน่งที่แตกต่างกันสำหรับชุดอุปกรณ์แต่ละอินสแตนซ์
  • สร้าง function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> และป้อนข้อมูลการกำหนดค่าที่ป้อนสำหรับฟังก์ชัน หากการอัปเดตในอนาคตมีการเพิ่มพารามิเตอร์ใหม่ ระบบจะแจ้งให้คุณทราบในการติดตั้งใช้งานครั้งถัดไป
  • สร้างทรัพยากร Google Cloud ที่จำเป็นเพื่อเรียกใช้ชุดนี้ ซึ่งรวมถึงบัญชีบริการที่มีบทบาท IAM, ฟังก์ชัน, ทริกเกอร์ Eventarc และคิวงาน Cloud Tasks ที่เฉพาะเจาะจง

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

การถอนการติดตั้งชุดอุปกรณ์

หากต้องการนำชุดอุปกรณ์และอินสแตนซ์ทั้งหมดออก ให้เรียกใช้คำสั่งต่อไปนี้

firebase functions:kits:uninstall --kit <kit-id>

การดำเนินการนี้จะลบอินสแตนซ์ทั้งหมดและการกำหนดค่าของอินสแตนซ์เหล่านั้น รวมถึงนำแหล่งที่มาของชุดอุปกรณ์ออกจากดิสก์

หากต้องการนำชุดอุปกรณ์ออกเพียงชุดเดียว ให้เรียกใช้คำสั่งต่อไปนี้

firebase functions:kits:uninstall --instance <kit-instance-id>

หากคุณมีชุดอุปกรณ์เพียงชุดเดียว การดำเนินการนี้จะถอนการติดตั้งทั้งชุด

การอัปเดตการกำหนดค่าชุดอุปกรณ์

ในระหว่างการติดตั้งหรือการติดตั้งใช้งานครั้งแรก ระบบจะแจ้งให้คุณกำหนดค่าพารามิเตอร์ทั้งหมดสำหรับชุดอุปกรณ์ (เว้นแต่คุณจะย้ายข้อมูลการกำหนดค่าจากส่วนขยาย) พารามิเตอร์เหล่านี้จะจัดเก็บไว้ในไฟล์ .env ในไดเรกทอรีการกำหนดค่าอินสแตนซ์ของชุดเครื่องมือ ตัวอย่างเช่น หากคุณมีอินสแตนซ์ชุดเครื่องมือชื่อ firestore-bigquery-export ในโปรเจ็กต์ my-project ไฟล์ .env จะอยู่ที่ function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project

ซึ่งจะมีลักษณะดังนี้

DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1

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

เช่น หากคุณลบบรรทัด COLLECTION_PATH=posts และทำให้ใช้งานได้ ระบบจะแจ้งให้คุณป้อนข้อมูลดังกล่าวในระหว่างการทำให้ใช้งานได้ ดังนี้

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:

Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)

การบำรุงรักษาและการอัปเกรดชุดฟังก์ชัน

ผู้เผยแพร่อาจอัปเดตแพ็กเกจ npm เป็นระยะๆ เพื่อแก้ไขข้อบกพร่อง เพิ่มฟีเจอร์ อัปเดตทรัพยากร Dependency หรือแก้ไขช่องโหว่ด้านความปลอดภัย เราขอแนะนำให้คุณติดตามการอัปเดตรุ่นเหล่านี้และติดตั้งการอัปเดต โดยเฉพาะการอัปเดตที่จัดการกับช่องโหว่ด้านความปลอดภัยที่อาจเกิดขึ้น

คำสั่ง functions:kits:install จะสร้างฐานของโค้ดที่ติดตั้งชุดเครื่องมือเป็นแพ็กเกจ npm และส่งออกฟังก์ชันทั้งหมดสำหรับชุดเครื่องมือแต่ละอินสแตนซ์ หากต้องการอัปเกรดชุด ให้เปลี่ยนเวอร์ชันแพ็กเกจ แล้วติดตั้งใช้งานแต่ละอินสแตนซ์ของชุดอีกครั้งเพื่อใช้การเปลี่ยนแปลง

การตรวจสอบว่าชุดอุปกรณ์มีการอัปเดตหรือไม่

ไปที่ไดเรกทอรี source ของชุดอุปกรณ์ที่ function-kits/<your-kit-id>/source จากไดเรกทอรี source นี้ ให้เรียกใช้คำสั่งต่อไปนี้เพื่อรับรายงานเกี่ยวกับแพ็กเกจ npm ที่ล้าสมัยทั้งหมด รวมถึงชุดฟังก์ชันและ SDK Cloud Functions

npm outdated

หากคุณใช้เครื่องมือเพื่อระบุทรัพยากร Dependency ที่ต้องอัปเดตอยู่แล้ว เช่น Dependabot สำหรับ GitHub เราขอแนะนำให้ผสานรวมไดเรกทอรีชุดเครื่องมือเข้ากับเวิร์กโฟลว์ดังกล่าว

การอัปเดตชุดอุปกรณ์

หากต้องการอัปเดตชุดเครื่องมือและทรัพยากร Dependency เป็นเวอร์ชันล่าสุดที่ไม่ส่งผลกับส่วนอื่นในระบบ (ไม่รวมการอัปเดตเวอร์ชันหลักที่อาจมีการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ) ให้เรียกใช้คำสั่งต่อไปนี้

npm update --save

หากต้องการอัปเดตเฉพาะแพ็กเกจชุดฟังก์ชันและไม่อัปเดตแพ็กเกจอื่นๆ ให้ส่งชื่อแพ็กเกจไปยัง npm update ดังนี้

npm update <package-name> --save

หากต้องการอัปเกรดแพ็กเกจเป็นเวอร์ชันหลักล่าสุด (ซึ่งอาจทำให้เกิดการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ) ให้เรียกใช้คำสั่งต่อไปนี้

npm update --save <npm-package-name>@latest

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

กำลังติดตั้งใช้งานอินสแตนซ์ที่อัปเดต

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

firebase deploy --only functions

การยกเลิกการย้ายข้อมูล

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

หลังจากติดตั้งใช้งานส่วนขยายแล้ว ให้ถอนการติดตั้งอินสแตนซ์ชุด (ซึ่งจะถอนการติดตั้งทั้งชุดหากเป็นอินสแตนซ์สุดท้ายที่เหลืออยู่) โดยทำดังนี้

firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>

การบันทึกการกำหนดค่าส่วนขยายสำหรับการย้ายข้อมูลในอนาคต

หลังจากวันที่ 31 มีนาคม 2027 คุณจะไม่สามารถดึงข้อมูลการกำหนดค่าส่วนขยายที่มีอยู่ได้ หากคุณไม่สามารถย้ายข้อมูลก่อนวันที่ 31 มีนาคม 2027 เราขอแนะนำอย่างยิ่งให้บันทึกส่วนขยายไว้เผื่อว่าคุณตัดสินใจย้ายข้อมูลหลังจากวันที่ดังกล่าว

  1. ดูรายการรหัสอินสแตนซ์ของส่วนขยายโดยทำดังนี้

    คุณใช้คำสั่ง CLI ext:list เพื่อดูรายการอินสแตนซ์ส่วนขยายทั้งหมดในโปรเจ็กต์ Firebase ได้ โดยทำดังนี้

    firebase ext:list --project <project-id>

    ตัวอย่างที่อธิบายอย่างละเอียด

    firebase ext:list --project my-project

    » firebase ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3   │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export      │ ACTIVE │ 0.3.2   │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

    คำสั่ง ext:list ยังมีรูปแบบเอาต์พุต JSON ด้วย และหากคุณติดตั้งยูทิลิตี jq ไว้ คุณสามารถใช้ยูทิลิตีนี้เพื่อรับรายการรหัสอินสแตนซ์ทั้งหมดสำหรับโปรเจ็กต์ได้

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    ตัวอย่างที่อธิบายอย่างละเอียด

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    เอาต์พุต:

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. ส่งออกการกำหนดค่าสำหรับแต่ละอินสแตนซ์โดยทำดังนี้

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

    firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>

    ตัวอย่างที่อธิบายอย่างละเอียด

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    เอาต์พุต:

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  functions: Saving exported extensions config as a Function Kits .env file
i  functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control.
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing

    ในดิสก์ คุณจะเห็นการส่งออกอินสแตนซ์ของส่วนขยายนี้ในตำแหน่ง เช่น <instance-id>/.env.<project-id> ในตัวอย่างนี้คือ firestore-bigquery-export/.env.my-project

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

  3. ย้ายไฟล์ .env ที่ส่งออกไปยังตำแหน่งที่ดีกว่า โดยทำดังนี้

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