ย้ายข้อมูล Firebase Extensions ไปยังชุดฟังก์ชัน

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

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

ตลอดทั้งคู่มือนี้ ส่วนขยาย Stream Cloud Firestore to BigQuery (firestore-bigquery-export) จะใช้เป็นตัวอย่างที่แสดงคำสั่งและเอาต์พุตจากคำสั่งสำหรับแต่ละขั้นตอนของการย้ายข้อมูล

กำหนดเส้นทางการย้ายข้อมูล

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

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

  • เรียกใช้ firebase ext:list ภายในโปรเจ็กต์ Firebase ในเทอร์มินัลเพื่อแสดงว่าส่วนขยายที่ติดตั้งไว้รายการใดมีรายการทดแทนอย่างเป็นทางการ

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: 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.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

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

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

เลือกเส้นทางการย้ายข้อมูล ย้ายข้อมูลไปยังชุดฟังก์ชันใน npm ย้ายข้อมูลไปยังชุดฟังก์ชันที่สร้างขึ้นเอง

ย้ายข้อมูลไปยังชุดฟังก์ชันใน npm

ตรวจสอบข้อจำกัดที่ทราบเกี่ยวกับการย้ายข้อมูล

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

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

ก่อนเริ่มต้น

คุณต้องตั้งค่า Firebase CLI และเริ่มต้นโปรเจ็กต์ Firebase เมื่อใช้ CLI ให้ตรวจสอบว่าคุณใช้ firebase-tools เวอร์ชัน >= 15.32.0 ซึ่งมีคำสั่งการย้ายข้อมูลและชุดฟังก์ชันใหม่

สิทธิ์และบทบาทในบัญชีที่จำเป็น

บัญชีที่คุณใช้ตรวจสอบสิทธิ์กับ Firebase และ Google Cloud ต้องมีบทบาทต่อไปนี้ ทั้งนี้ขึ้นอยู่กับสิ่งที่ต้องสร้างและกำหนดค่าโดย Firebase CLI ในระหว่างการย้ายข้อมูล

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (หากคุณต้องทำ setIamPermissions สำหรับปลายทางสาธารณะ)
  • roles/secretmanager.admin (หากใช้ข้อมูลลับ)
  • roles/serviceusage.serviceUsageAdmin (หากต้องการเปิดใช้ API ใหม่)

เราขอแนะนำให้ใช้บัญชีที่ติดตั้งส่วนขยายและติดตั้งใช้งานฟังก์ชันไว้ก่อนหน้านี้ เนื่องจากสิทธิ์เหล่านี้ส่วนใหญ่จะได้รับอนุญาตแล้ว หากบัญชีที่ย้ายข้อมูลต้องการบทบาทเพิ่มเติม ให้ทำตามวิธีการของ Google Cloud IAM เพื่อเพิ่มบทบาท

เลือกเวิร์กโฟลว์ CLI

หากต้องการย้ายข้อมูลจากอินสแตนซ์ส่วนขยายไปยังชุดฟังก์ชันที่พร้อมใช้งานใน npm ให้เลือกตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้

  • (แนะนำ) ย้ายข้อมูลโดยใช้คำสั่ง CLI ext:migrate คำสั่งนี้จะทำให้ชุดฟังก์ชันที่ใช้แทนที่ใช้งานได้ก่อนที่จะถอนการติดตั้งส่วนขยายที่ถูกแทนที่
  • ย้ายข้อมูลโดยใช้คำสั่ง CLI ของชุดฟังก์ชัน คุณสามารถใช้คำสั่งแยกต่างหากเพื่ออัปเดตส่วนขยาย ติดตั้งชุดฟังก์ชัน กำหนดค่าชุดฟังก์ชันเหมือนส่วนขยาย ติดตั้งใช้งานชุดฟังก์ชัน และถอนการติดตั้งส่วนขยาย ซึ่งช่วยให้จัดเรียงคำสั่งใหม่หรือทำงานเพิ่มเติมระหว่างขั้นตอนต่างๆ ได้อย่างยืดหยุ่นมากขึ้น

ย้ายข้อมูลโดยใช้ ext:migrate

เริ่มการย้ายข้อมูลโดยเรียกใช้คำสั่งต่อไปนี้ 1 ครั้งต่ออินสแตนซ์ส่วนขยาย

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

คำสั่งนี้จะแนะนำขั้นตอนต่อไปนี้

  1. การเลือกส่วนขยายที่จะย้ายข้อมูลซึ่งมีชุดฟังก์ชันอย่างเป็นทางการที่ใช้แทนได้
  2. เลือกอินสแตนซ์ที่เฉพาะเจาะจงของส่วนขยายนั้น
  3. อัปเดตส่วนขยายเป็นเวอร์ชันล่าสุดหากจำเป็น
  4. การติดตั้งชุดฟังก์ชัน การกำหนดค่าอินสแตนซ์ให้เหมือนกับการกำหนดค่าอินสแตนซ์ส่วนขยาย
  5. กำลังติดตั้งใช้งานชุดฟังก์ชัน
  6. ตรวจสอบว่าติดตั้งใช้งานชุดฟังก์ชันสำเร็จแล้ว และฮุกวงจรทั้งหมด (หากมี) ทำงานแล้ว
  7. กำลังถอนการติดตั้งอินสแตนซ์ส่วนขยาย

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

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

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

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

ยืนยันการติดตั้งใช้งานชุดฟังก์ชัน

หากต้องการยืนยันว่า firebase deploy ของชุดไม่มีข้อผิดพลาด ให้ตรวจสอบบันทึกการติดตั้งใช้งานเพื่อดูว่ามีการทริกเกอร์ Lifecycle Hook หรือไม่ ส่วนขยายยอดนิยม เช่น สตรีม Cloud Firestore ไปยัง BigQuery จะใช้ฮุกวงจร ตัวอย่างต่อไปนี้แสดงลักษณะของ Lifecycle Hook เมื่อทริกเกอร์

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/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

ข้อความในบันทึกเหล่านี้จะยืนยันสิ่งต่อไปนี้

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

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

firebase functions:lifecycle:run <hook-name> <codebase>

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

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

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

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

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

ตัวอย่างการทำงาน: สตรีม Cloud Firestore ไปยัง BigQuery

เมื่อใช้ส่วนขยาย Stream Cloud Firestore to BigQuery การเขียนลงในทั้งตารางบันทึกการเปลี่ยนแปลงดิบ (*_raw_changelog) และตารางมุมมองล่าสุด (*_raw_latest) จะกรองข้อมูลที่ซ้ำกันออกหากมีการส่งเหตุการณ์เดียวกันไปยังชุดและส่วนขยาย ดังนั้นคุณจึงไม่สามารถใช้การมีอยู่ของแถวหรือแถวที่ซ้ำกันใน BigQuery เพื่อตรวจสอบว่าชุดเครื่องมือทำงานอยู่หรือไม่

คุณสามารถดูบันทึกฟังก์ชันได้ไม่นานหลังจากเขียนลงในคอลเล็กชัน Firestore โดยใช้ firebase functions:logs และมองหารายการบันทึกที่ระบุว่าประมวลผลการเขียนสำเร็จ สำหรับชุดอุปกรณ์นี้ที่มีรหัสอินสแตนซ์เริ่มต้นเป็น firestore-bigquery-export จะมีลักษณะดังนี้

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

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

firebase functions:log --only <function name>

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

firebase functions:list | grep kit-<kit instance id>

สำหรับตัวอย่างนี้

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

ตรวจสอบ README ของชุดฟังก์ชัน

ชุดอุปกรณ์บางชุดอาจต้องมีการดำเนินการเพิ่มเติม นอกเหนือจากที่ชุดฟังก์ชันจัดการโดยอัตโนมัติ อ่านREADMEสำหรับชุดอุปกรณ์ที่คุณกำลังติดตั้งและทำตามวิธีการเพิ่มเติม

ย้ายข้อมูลโดยใช้ CLI ของชุดฟังก์ชัน

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

1. อัปเกรดอินสแตนซ์ส่วนขยายเป็นเวอร์ชันล่าสุด

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

ใช้ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้เพื่ออัปเดตส่วนขยาย โดยขึ้นอยู่กับตำแหน่งที่ติดตั้งส่วนขยาย

  • จากคอนโซล Firebase
  • จาก Firebase CLI โดยใช้คำสั่งต่อไปนี้
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

หากข้ามขั้นตอนนี้ CLI จะแจ้งให้คุณอัปเกรดเมื่อส่งออกการกำหนดค่าหากส่วนขยายไม่ได้ใช้เวอร์ชันล่าสุด

2. ตรวจสอบและติดตั้งอินสแตนซ์ชุดฟังก์ชันทดแทน

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

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

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

เมื่อติดตั้งชุดแล้ว ระบบจะสร้างไดเรกทอรีใหม่ภายในโปรเจ็กต์ Firebase โดยมีตำแหน่ง เช่น function-kits/<kit-name>/source ซึ่งมีแพ็กเกจ npm พร้อมชุดที่แทนที่ส่วนขยายและไฟล์ index.ts พื้นฐานที่ส่งออกฟังก์ชันเหล่านั้นเพื่อให้ Firebase นำไปใช้และตั้งค่าการกำหนดค่าที่กำหนดเอง

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

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

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

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. กำหนดค่าอินสแตนซ์ชุดฟังก์ชันให้เหมือนกับส่วนขยาย

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

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

เมื่อสิ้นสุดขั้นตอนนี้ ข้อมูลการกำหนดค่าสำหรับอินสแตนซ์นี้จะจัดเก็บไว้ในไฟล์ .env เฉพาะโปรเจ็กต์ในไดเรกทอรีการกำหนดค่าอินสแตนซ์ เช่น function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. ติดตั้งใช้งานและยืนยันการเปลี่ยนชุดอุปกรณ์

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

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

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

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!

หากต้องการยืนยันว่า firebase deploy ของชุดไม่มีข้อผิดพลาด ให้ตรวจสอบบันทึกการติดตั้งใช้งานเพื่อดูว่ามีการทริกเกอร์ Lifecycle Hook หรือไม่ ส่วนขยายยอดนิยม เช่น สตรีม Cloud Firestore ไปยัง BigQuery จะใช้ฮุกวงจร ตัวอย่างต่อไปนี้แสดงลักษณะของ Lifecycle Hook เมื่อทริกเกอร์

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/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

ข้อความในบันทึกเหล่านี้จะยืนยันสิ่งต่อไปนี้

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

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

firebase functions:lifecycle:run <hook-name> <codebase>

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

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

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

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

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

ตัวอย่างการทำงาน: สตรีม Cloud Firestore ไปยัง BigQuery

เมื่อใช้ส่วนขยาย Stream Cloud Firestore to BigQuery การเขียนลงในทั้งตารางบันทึกการเปลี่ยนแปลงดิบ (*_raw_changelog) และตารางมุมมองล่าสุด (*_raw_latest) จะกรองข้อมูลที่ซ้ำกันออกหากมีการส่งเหตุการณ์เดียวกันไปยังชุดและส่วนขยาย ดังนั้นคุณจึงไม่สามารถใช้การมีอยู่ของแถวหรือแถวที่ซ้ำกันใน BigQuery เพื่อตรวจสอบว่าชุดเครื่องมือทำงานอยู่หรือไม่

คุณสามารถดูบันทึกฟังก์ชันได้ไม่นานหลังจากเขียนลงในคอลเล็กชัน Firestore โดยใช้ firebase functions:logs และมองหารายการบันทึกที่ระบุว่าประมวลผลการเขียนสำเร็จ สำหรับชุดอุปกรณ์นี้ที่มีรหัสอินสแตนซ์เริ่มต้นเป็น firestore-bigquery-export จะมีลักษณะดังนี้

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

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

firebase functions:log --only <function name>

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

firebase functions:list | grep kit-<kit instance id>

สำหรับตัวอย่างนี้

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

5. ถอนการติดตั้งส่วนขยาย

เมื่อยืนยันชุดฟังก์ชันที่ติดตั้งใช้งานแล้ว คุณสามารถถอนการติดตั้งส่วนขยายเพื่อไม่ให้เกิดการทำงานซ้ำซ้อนทั้งในชุดและในส่วนขยาย คุณสามารถถอนการติดตั้งส่วนขยายทั้งหมดจาก CLI ของ Firebase ได้ไม่ว่าจะติดตั้งด้วยวิธีใดก็ตาม หากคุณส่งแฟล็ก --immediate ดังนี้

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

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

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

เอาต์พุต:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

การย้ายข้อมูลขั้นสูง

คุณสามารถมีส่วนขยายในโปรเจ็กต์ Firebase หลายโปรเจ็กต์ที่ต้องการจัดการด้วยฐานของโค้ดเดียว ตัวอย่างเช่น หากคุณติดตั้งใช้งานโครงสร้างพื้นฐานเดียวกันในสภาพแวดล้อม testing และสภาพแวดล้อม production ซึ่งแต่ละสภาพแวดล้อมมีอินสแตนซ์ documents Cloud Firestore ที่คุณส่งออกไปยัง BigQuery คุณอาจติดตั้งส่วนขยาย firestore-bigquery-export ไว้ 2 อินสแตนซ์ ดังนี้

  • export-documents-testing
  • export-documents-production

หากคุณย้ายข้อมูลอินสแตนซ์ส่วนขยาย 2 รายการนี้ไปยังอินสแตนซ์ชุดฟังก์ชัน 2 รายการในฐานของโค้ดเดียวเมื่อทำงานกับ Firebase CLI และทำให้ใช้งานได้โดยใช้ firebase deploy --project testing และ firebase deploy --project production การทำให้ใช้งานได้แต่ละครั้งจะสร้างอินสแตนซ์ 2 รายการทั้งในสภาพแวดล้อม testing และ production

แต่ให้แทนที่อินสแตนซ์ส่วนขยาย 2 รายการด้วยอินสแตนซ์ชุดฟังก์ชัน 1 รายการของ firestore-bigquery-export ที่ติดตั้งใช้งานในหลายโปรเจ็กต์ โดยแต่ละโปรเจ็กต์มีการกำหนดค่าของตัวเอง ไดเรกทอรีการกำหนดค่าสำหรับอินสแตนซ์ควรมีลักษณะดังนี้

  • config-export-documents/
    • .env.testing
    • .env.production

การติดตั้งใช้งานแต่ละครั้งใน testing และ production จะสร้างอินสแตนซ์ของชุดอุปกรณ์ 1 รายการพร้อมการกำหนดค่าที่เกี่ยวข้อง คำสั่ง CLI ที่มีอยู่จะสร้างการตั้งค่านี้ตราบใดที่คุณส่งแฟล็ก --project ในการเรียกใช้ ext:migrate หรือ functions:kits:install แต่ละครั้ง

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

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

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