นำเข้าและส่งออกข้อมูล

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

หน้านี้อธิบายวิธีส่งออกและนำเข้าเอกสาร Cloud Firestore โดยใช้บริการส่งออกและนำเข้าที่มีการจัดการและ Cloud Storage บริการส่งออกและนำเข้าที่มีการจัดการของ Cloud Firestore พร้อมใช้งานผ่านเครื่องมือบรรทัดคำสั่ง gcloud และ Cloud Firestore API (REST, RPC)

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

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

1. เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Google Cloud เฉพาะโปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงินเท่านั้นที่จะใช้ฟังก์ชันการส่งออกและนำเข้าได้
2. สร้างบักเก็ต Cloud Storage สำหรับโปรเจ็กต์ในตำแหน่งที่อยู่ใกล้กับตำแหน่งฐานข้อมูล Cloud Firestore คุณไม่สามารถใช้บักเก็ต Requester Pays หรือบักเก็ต Rapid สำหรับการดำเนินการส่งออกและนำเข้าได้

3. ตรวจสอบว่าบัญชีของคุณมีสิทธิ์ที่จำเป็นสำหรับ Cloud Firestore และ Cloud Storage หากคุณเป็นเจ้าของโปรเจ็กต์ บัญชีของคุณจะมีสิทธิ์ที่จำเป็น หรือบทบาทต่อไปนี้จะให้สิทธิ์ที่จำเป็นสำหรับการดำเนินการส่งออกและนำเข้า รวมถึงการเข้าถึง Cloud Storage

   • บทบาท Cloud Firestore: Owner, Cloud Datastore Owner หรือ Cloud Datastore Import Export Admin

   • บทบาท Cloud Storage: Owner หรือ Storage Admin

สิทธิ์ของ Service Agent

การดำเนินการส่งออกและนำเข้าใช้ Agent บริการ Cloud Firestore เพื่อให้สิทธิ์การดำเนินการ Cloud Storage ตัวแทนบริการ Cloud Firestore ใช้รูปแบบการตั้งชื่อต่อไปนี้

ตัวแทนบริการ Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Service Agent ได้ที่หัวข้อ Service Agent

ตัวแทนบริการ Cloud Firestore ต้องมีสิทธิ์เข้าถึงบักเก็ต Cloud Storage ที่ใช้ในการดำเนินการส่งออกหรือนำเข้า หากบักเก็ต Cloud Storage อยู่ในโปรเจ็กต์เดียวกับฐานข้อมูล Cloud Firestore ตัวแทนบริการ Cloud Firestore จะเข้าถึงบักเก็ตได้โดยค่าเริ่มต้น

หากบักเก็ต Cloud Storage อยู่ในโปรเจ็กต์อื่น คุณ ต้องให้สิทธิ์เข้าถึงบักเก็ต Cloud Storage แก่ตัวแทนบริการ Cloud Firestore

มอบหมายบทบาทให้กับตัวแทนบริการ

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

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

แทนที่ PROJECT_NUMBER ด้วยหมายเลขโปรเจ็กต์ ซึ่งใช้เพื่อตั้งชื่อตัวแทนบริการ Cloud Firestore หากต้องการดูชื่อ Service Agent โปรดดูหัวข้อดูชื่อ Service Agent

หรือจะมอบหมายบทบาทนี้โดยใช้คอนโซล Google Cloud ก็ได้

ดูชื่อตัวแทนบริการ

คุณดูบัญชีที่การดำเนินการนำเข้าและส่งออกใช้เพื่อให้สิทธิ์คำขอได้จากหน้านำเข้า/ส่งออกในคอนโซล Google Cloud นอกจากนี้ คุณยังดูได้ว่าฐานข้อมูลใช้ Agent บริการ Cloud Firestore หรือบัญชีบริการ App Engine เดิม

1. ดูบัญชีการให้สิทธิ์ข้างป้ายกำกับงานนำเข้า/ส่งออกที่เรียกใช้ในชื่อ

Service Agent ต้องมีบทบาท Storage Admin สำหรับบักเก็ต Cloud Storage ที่จะใช้สำหรับการดำเนินการส่งออกหรือนำเข้า

ตั้งค่า gcloud สำหรับโปรเจ็กต์

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

• เข้าถึง gcloud จากคอนโซล Google Cloud โดยใช้ Cloud Shell

  เริ่ม Cloud Shell

  ตรวจสอบว่าได้กำหนดค่า gcloud สำหรับโปรเจ็กต์ที่ถูกต้องแล้ว โดยทำดังนี้

  gcloud config set project [PROJECT_ID]
  

• ติดตั้งและเริ่มต้นใช้งาน Google Cloud SDK

นำเข้าข้อมูล

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

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

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

• หากเอกสารในฐานข้อมูลไม่ได้รับผลกระทบจากการนำเข้า เอกสารนั้นจะยังคงอยู่ในฐานข้อมูลหลังจากการนำเข้า

• ชื่อไฟล์ .overall_export_metadata ต้องตรงกับชื่อของโฟลเดอร์หลัก ดังนี้

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  หากคุณย้ายหรือคัดลอกไฟล์เอาต์พุตของการส่งออก ให้คงชื่อไฟล์ PARENT_FOLDER_NAME และ .overall_export_metadata ไว้เหมือนเดิม

• การนำเข้าฐานข้อมูล Cloud Firestore จากการส่งออกที่มีคอลเล็กชันย่อยไม่สำเร็จเนื่องจาก Cloud Firestore ไม่รองรับคอลเล็กชันย่อย

• การนําเข้าไปยังฐานข้อมูล Firestore Standard Edition จากการส่งออกที่มีประเภท BSON จะไม่สําเร็จ เนื่องจาก Firestore Standard Edition ไม่รองรับประเภท BSON

• การนำเข้าไปยังฐานข้อมูล Cloud Firestore ไม่สามารถนำเข้าข้อมูลจากเนมสเปซที่ไม่ใช่ค่าเริ่มต้น (Datastore API)

  การนำเข้าฐานข้อมูล Cloud Firestore จากไฟล์ข้อมูลที่มีเนมสเปซที่ไม่ใช่ค่าเริ่มต้นจะได้รับอนุญาตก็ต่อเมื่อการดำเนินการส่งออกมีตัวกรอง --namespace-ids ที่มีเนมสเปซเริ่มต้น ระบบจะนำเข้าเฉพาะข้อมูลจากเนมสเปซเริ่มต้นเท่านั้น

นำเข้าเอกสารทั้งหมดจากการส่งออก

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

นำเข้าคอลเล็กชันที่เฉพาะเจาะจง

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
  --database=[DATABASE]

นําเข้าจากการส่งออกที่มีข้อมูล PITR

ใช้ขั้นตอนเดียวกับในหัวข้อนำเข้าเอกสารทั้งหมดหรือนำเข้าคอลเล็กชันที่เฉพาะเจาะจงเพื่อนำเข้าข้อมูล PITR หากมีเอกสารอยู่ในฐานข้อมูลอยู่แล้ว ระบบจะเขียนทับเอกสารนั้น

ส่งออกข้อมูล

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

ส่งออกเอกสารทั้งหมด

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

ส่งออกคอลเล็กชันที่เฉพาะเจาะจง

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

ส่งออกจากประทับเวลา PITR

คุณสามารถส่งออกฐานข้อมูลไปยัง Cloud Storage จากข้อมูล PITR ได้ คุณสามารถส่งออกข้อมูล PITR ที่มีการประทับเวลาเป็นนาทีเต็มภายใน 7 วันที่ผ่านมา แต่ต้องไม่ก่อนวันที่ earliestVersionTime หากไม่มีข้อมูลอยู่ในการประทับเวลาที่ระบุอีกต่อไป การดำเนินการส่งออกจะล้มเหลว

การดำเนินการส่งออก PITR รองรับตัวกรองทั้งหมด รวมถึงการส่งออกเอกสารทั้งหมดและการส่งออกคอลเล็กชันที่เฉพาะเจาะจง

โปรดทราบประเด็นต่อไปนี้ก่อนส่งออกข้อมูล PITR

• ระบุการประทับเวลาในรูปแบบ RFC 3339 เช่น 2020-09-01T23:59:30.234233Z
• ตรวจสอบว่าการประทับเวลาที่คุณระบุเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมา แต่ไม่เกิน earliestVersionTime หากไม่มีข้อมูลอยู่ในการประทับเวลาที่ระบุ ระบบจะสร้างข้อผิดพลาดขึ้น
• ระบบจะไม่เรียกเก็บเงินสำหรับการส่งออก PITR ที่ไม่สำเร็จ

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

จัดการการดำเนินการส่งออกและนำเข้า

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

ชื่อการดำเนินการจะขึ้นต้นด้วย projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/ เช่น

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

อย่างไรก็ตาม คุณสามารถละเว้นคำนำหน้าได้เมื่อระบุชื่อการดำเนินการสำหรับคำสั่ง describe, cancel และ delete

แสดงรายการการดำเนินการส่งออกและนำเข้าทั้งหมด

gcloud firestore operations list

ตรวจสอบสถานะการดำเนินการ

gcloud firestore operations describe [OPERATION_NAME]

ประเมินเวลาที่ใช้ในการดำเนินการให้เสร็จสมบูรณ์

คำขอสถานะของการดำเนินการที่ใช้เวลานานจะแสดงผลเมตริก workEstimated และ workCompleted ระบบจะแสดงผลเมตริกแต่ละรายการทั้งในรูปแบบจำนวนไบต์และจำนวนเอนทิตี ดังนี้

• workEstimated แสดงจำนวนไบต์และเอกสารทั้งหมดโดยประมาณที่การดำเนินการจะประมวลผล Cloud Firestore อาจละเว้นเมตริกนี้หากไม่สามารถประมาณได้

• workCompleted แสดงจำนวนไบต์และเอกสารที่ประมวลผลจนถึงตอนนี้ หลังจากดำเนินการเสร็จสิ้น ค่าจะแสดงจำนวนไบต์และเอกสารทั้งหมดที่ประมวลผลจริง ซึ่งอาจมากกว่าค่าของ workEstimated

หาร workCompleted ด้วย workEstimated เพื่อดูความคืบหน้าโดยประมาณ ค่าประมาณนี้อาจไม่ถูกต้อง เนื่องจากขึ้นอยู่กับการรวบรวมสถิติที่ล่าช้า

ยกเลิกการดำเนินการ

gcloud firestore operations cancel [OPERATION_NAME]

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

ลบการดำเนินการ

ใช้คำสั่ง gcloud firestore operations delete เพื่อนำการดำเนินการออกจากรายการการดำเนินการล่าสุด คำสั่งนี้จะไม่ลบไฟล์ที่ส่งออกจาก Cloud Storage

gcloud firestore operations delete [OPERATION_NAME]

การเรียกเก็บเงินและการกำหนดราคาสำหรับการดำเนินการส่งออกและนำเข้า

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

ระบบจะเรียกเก็บเงินสำหรับการดำเนินการส่งออกและนำเข้าสำหรับหน่วยการอ่านและหน่วยการเขียนตามอัตราที่ระบุไว้ในราคาของ Cloud Firestore

ไฟล์เอาต์พุตที่จัดเก็บไว้ใน Cloud Storage จะนับรวมในค่าใช้จ่ายในการจัดเก็บข้อมูล Cloud Storage

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

การดูค่าใช้จ่ายในการส่งออกและนำเข้า

การดำเนินการส่งออกและนำเข้าจะใช้ป้ายกำกับ goog-firestoremanaged:exportimport กับการดำเนินการที่เรียกเก็บเงิน ในหน้ารายงานการเรียกเก็บเงินใน Cloud คุณสามารถใช้ป้ายกำกับนี้เพื่อดูค่าใช้จ่ายที่เกี่ยวข้องกับการดำเนินการนำเข้าและส่งออกได้ ดังนี้

ส่งออกไปยัง BigQuery

คุณสามารถโหลดข้อมูลจากการส่งออก Cloud Firestore ไปยัง BigQuery ได้ แต่เฉพาะในกรณีที่คุณระบุตัวกรอง collection-ids ไว้เท่านั้น ดูการโหลดข้อมูลจากการส่งออก Cloud Firestore

เมื่อโหลดข้อมูล Cloud Firestore ลงใน BigQuery ประเภทข้อมูล BSON จะแสดงด้วยประเภทข้อมูล STRING

ขีดจำกัด BigQuery คอลัมน์

BigQuery กำหนดขีดจำกัดไว้ที่ 10,000 คอลัมน์ต่อตาราง การดำเนินการส่งออก Cloud Firestore จะสร้างสคีมาตาราง BigQuery สำหรับแต่ละคอลเล็กชัน ในสคีมานี้ ชื่อฟิลด์ที่ไม่ซ้ำกันแต่ละชื่อภายในคอลเล็กชันจะกลายเป็นคอลัมน์สคีมา

หากสคีมา BigQuery ของคอลเล็กชันมีคอลัมน์เกิน 10,000 คอลัมน์ การดำเนินการส่งออก Cloud Firestore จะพยายามรักษาจำนวนคอลัมน์ให้ต่ำกว่าขีดจำกัดโดยถือว่าช่องแผนที่เป็นไบต์ หากการแปลงนี้ทำให้จำนวนคอลัมน์ต่ำกว่า 10,000 คอลัมน์ คุณจะโหลดข้อมูลลงใน BigQuery ได้ แต่จะค้นหาฟิลด์ย่อยภายในฟิลด์แผนที่ไม่ได้ หากจำนวนคอลัมน์ยังคงเกิน 10,000 คอลัมน์ การดำเนินการส่งออกจะไม่สร้างสคีมา BigQuery สำหรับคอลเล็กชัน และคุณจะโหลดข้อมูลลงใน BigQuery ไม่ได้

ส่งออกไฟล์รูปแบบและข้อมูลเมตา

เอาต์พุตของการส่งออกที่มีการจัดการจะใช้รูปแบบบันทึก LevelDB

ไฟล์ข้อมูลเมตา

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

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

protoc --decode_raw < export0.export_metadata