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

หลังจากย้ายข้อมูลจาก 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.ajp-testing
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 เมื่อเวลาผ่านไปเพื่อแก้ไขข้อบกพร่อง เพิ่มฟีเจอร์ อัปเดตการอ้างอิง หรือแก้ไขช่องโหว่ด้านความปลอดภัย เราขอแนะนำให้คุณติดตามการอัปเดตเหล่านี้และติดตั้งการอัปเดต โดยเฉพาะการอัปเดตที่ จัดการกับช่องโหว่ด้านความปลอดภัย

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

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

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

npm outdated

หากคุณใช้เครื่องมือเพื่อระบุการขึ้นต่อกันที่ต้องอัปเดตอยู่แล้ว เช่น 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. ดูรายการรหัสอินสแตนซ์ของส่วนขยาย

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

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

    ตัวอย่างการคำนวณ

    firebase ext:list --project my-project

    » firebaselocal ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in ajp-testing:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ 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 โดยตรง แต่คุณไม่จำเป็นต้องใช้ไฟล์ดังกล่าวในแต่ละวันหากยังไม่ได้ย้ายข้อมูลไปยังชุดฟังก์ชัน คุณสามารถย้ายข้อมูลจากโปรเจ็กต์ไปยัง ที่เก็บข้อมูลอื่นๆ ที่เหมาะสมจนกว่าจะจำเป็นต้องใช้ในอนาคต หรือ เลือกที่จะลบข้อมูลได้