صادرات و واردات داده ها

شما می‌توانید از سرویس مدیریت‌شده‌ی صادرات و واردات Cloud Firestore برای بازیابی داده‌ها در صورت حذف تصادفی و صادرات داده‌ها برای پردازش آفلاین استفاده کنید. می‌توانید تمام اسناد یا فقط مجموعه‌های خاص را صادرات کنید. به همین ترتیب، می‌توانید تمام داده‌ها را از یک صادرات یا فقط مجموعه‌های خاص وارد کنید. داده‌های صادر شده از یک پایگاه داده Cloud Firestore را می‌توان به یک پایگاه داده Cloud Firestore دیگر وارد کرد. همچنین می‌توانید صادرات Cloud Firestore را در BigQuery بارگذاری کنید .

این صفحه نحوه‌ی خروجی گرفتن و وارد کردن اسناد Cloud Firestore را با استفاده از سرویس خروجی گرفتن و وارد کردن مدیریت‌شده و Cloud Storage شرح می‌دهد. سرویس خروجی گرفتن و وارد کردن مدیریت‌شده‌ی Cloud Firestore از طریق ابزار خط فرمان gcloud و API Cloud Firestore ( REST ، RPC ) در دسترس است.

قبل از اینکه شروع کنی

قبل از اینکه بتوانید از سرویس صادرات و واردات مدیریت‌شده استفاده کنید، باید مراحل زیر را انجام دهید:

  1. فعال کردن صورتحساب برای پروژه Google Cloud شما. فقط پروژه‌های Google Cloud که صورتحساب آنها فعال است می‌توانند از قابلیت صادرات و واردات استفاده کنند.
  2. یک مخزن Cloud Storage برای پروژه خود در مکانی نزدیک به محل پایگاه داده Cloud Firestore خود ایجاد کنید. شما نمی‌توانید از مخزن Requester Pays برای عملیات صادرات و واردات استفاده کنید.

  3. مطمئن شوید که حساب کاربری شما مجوزهای لازم برای Cloud Firestore و Cloud Storage را دارد. اگر شما مالک پروژه هستید، حساب کاربری شما مجوزهای لازم را دارد. در غیر این صورت، نقش‌های زیر مجوزهای لازم را برای عملیات صادرات و واردات و دسترسی به Cloud Storage اعطا می‌کنند:

مجوزهای عامل خدمات

عملیات صادرات و واردات از یک عامل سرویس Cloud Firestore برای تأیید عملیات Cloud Storage استفاده می‌کنند. عامل سرویس Cloud Firestore از قرارداد نامگذاری زیر استفاده می‌کند:

نماینده خدمات Cloud Firestore
service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

برای کسب اطلاعات بیشتر در مورد نمایندگان خدمات، به نمایندگان خدمات مراجعه کنید.

عامل سرویس Cloud Firestore نیاز به دسترسی به سطل Cloud Storage مورد استفاده در عملیات صادرات یا واردات دارد. اگر سطل Cloud Storage شما در همان پروژه‌ای باشد که پایگاه داده Cloud Firestore شما در آن قرار دارد، عامل سرویس Cloud Firestore می‌تواند به طور پیش‌فرض به سطل دسترسی داشته باشد .

اگر سطل Cloud Storage در پروژه دیگری است، باید به نماینده سرویس Cloud Firestore دسترسی به سطل Cloud Storage بدهید.

اختصاص نقش‌ها به عامل سرویس

شما می‌توانید از ابزار خط فرمان gsutil برای اختصاص یکی از نقش‌های زیر استفاده کنید. به عنوان مثال، برای اختصاص نقش Storage Admin به نماینده سرویس 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 شما استفاده می‌شود. برای مشاهده نام عامل سرویس، به مشاهده نام عامل سرویس مراجعه کنید.

روش دیگر، شما می‌توانید این نقش را با استفاده از کنسول Google Cloud اختصاص دهید .

مشاهده نام نماینده خدمات

شما می‌توانید حسابی را که عملیات واردات و صادرات شما برای تأیید درخواست‌ها استفاده می‌کند، از صفحه واردات/صادرات در کنسول Google Cloud مشاهده کنید. همچنین می‌توانید مشاهده کنید که آیا پایگاه داده شما از عامل سرویس Cloud Firestore یا حساب سرویس قدیمی App Engine استفاده می‌کند یا خیر.

  1. حساب مجوز را در کنار برچسب کارهای واردات/صادرات که اجرا می‌شوند، مشاهده کنید.

برای اینکه بتوان از باکت Cloud Storage برای عملیات صادرات یا واردات استفاده کرد، نماینده سرویس به نقش Storage Admin نیاز دارد.

راه‌اندازی gcloud برای پروژه شما

شما می‌توانید عملیات واردات و صادرات را از طریق کنسول Google Cloud یا ابزار خط فرمان gcloud آغاز کنید. برای استفاده از gcloud ، ابزار خط فرمان را تنظیم کرده و به یکی از روش‌های زیر به پروژه خود متصل شوید:

صادرات داده

یک عملیات اکسپورت، اسناد موجود در پایگاه داده شما را به مجموعه‌ای از فایل‌ها در یک فضای Cloud Storage کپی می‌کند. توجه داشته باشید که اکسپورت دقیقاً همان اسنپ‌شات پایگاه داده نیست که در زمان شروع اکسپورت گرفته شده است. یک اکسپورت ممکن است شامل تغییراتی باشد که در حین اجرای عملیات ایجاد شده‌اند.

صادرات تمام اسناد

کنسول ابری گوگل

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. روی «صادر کردن» کلیک کنید.

  5. روی گزینه‌ی «خروجی کل پایگاه داده» کلیک کنید.

  6. در زیر گزینه «انتخاب مقصد» ، نام یک مخزن Cloud Storage را وارد کنید یا از دکمه «مرور» برای انتخاب یک مخزن استفاده کنید.

  7. روی «صادر کردن» کلیک کنید.

کنسول به صفحه Import/Export برمی‌گردد. اگر عملیات با موفقیت شروع شود، صفحه یک ورودی به صفحه import و export اخیر اضافه می‌کند. در صورت عدم موفقیت، صفحه یک پیام خطا نمایش می‌دهد.

جی‌کلاود

از دستور firestore export برای خروجی گرفتن از تمام اسناد موجود در پایگاه داده خود استفاده کنید و به جای [BUCKET_NAME] نام باکت Cloud Storage خود را قرار دهید. برای جلوگیری از انتظار ابزار gcloud برای تکمیل عملیات، پرچم --async را اضافه کنید.

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

موارد زیر را جایگزین کنید:

  • BUCKET_NAME : با اضافه کردن یک پیشوند فایل بعد از نام باکت، خروجی‌های خود را سازماندهی کنید، برای مثال، BUCKET_NAME/my-exports-folder/export-name . اگر پیشوند فایلی ارائه ندهید، سرویس خروجی مدیریت‌شده بر اساس مهر زمانی فعلی، یکی ایجاد می‌کند.

  • DATABASE : نام پایگاه داده‌ای که می‌خواهید اسناد را از آن صادر کنید. برای پایگاه داده پیش‌فرض، از --database='(default)' استفاده کنید.

زمانی که عملیات صادرات را شروع می‌کنید، بستن ترمینال عملیات را لغو نمی‌کند، به لغو عملیات مراجعه کنید.

صادرات مجموعه‌های خاص

کنسول ابری گوگل

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. روی «صادر کردن» کلیک کنید.

  5. روی گزینه « خروجی یک یا چند گروه مجموعه» کلیک کنید. از منوی کشویی برای انتخاب یک یا چند گروه مجموعه استفاده کنید.

  6. در زیر گزینه «انتخاب مقصد» ، نام یک مخزن Cloud Storage را وارد کنید یا از دکمه «مرور» برای انتخاب یک مخزن استفاده کنید.

  7. روی «صادر کردن» کلیک کنید.

کنسول به صفحه Import/Export برمی‌گردد. اگر عملیات با موفقیت شروع شود، صفحه یک ورودی به صفحه import و export اخیر اضافه می‌کند. در صورت عدم موفقیت، صفحه یک پیام خطا نمایش می‌دهد.

جی‌کلاود

برای استخراج گروه‌های خاص مجموعه، از فلگ --collection-ids استفاده کنید. این عملیات فقط گروه‌های مجموعه با شناسه‌های مجموعه داده شده را استخراج می‌کند. گروه مجموعه شامل تمام مجموعه‌ها و زیرمجموعه‌ها (در هر مسیری) با شناسه مجموعه مشخص شده است.

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

برای مثال، می‌توانید یک مجموعه restaurants در پایگاه داده foo طوری طراحی کنید که شامل چندین زیرمجموعه مانند ratings ، reviews یا outlets باشد. برای خروجی گرفتن از مجموعه خاصی از restaurants و reviews ، دستور شما به شکل زیر خواهد بود:

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

خروجی گرفتن از یک مهر زمانی PITR

شما می‌توانید پایگاه داده خود را از داده‌های PITR به Cloud Storage صادر کنید. می‌توانید داده‌های PITR را که مهر زمانی آنها یک مهر زمانی یک دقیقه کامل در هفت روز گذشته است، اما نه زودتر از earliestVersionTime صادر کنید. اگر داده‌ها دیگر در مهر زمانی مشخص شده وجود نداشته باشند، عملیات صادرات با شکست مواجه می‌شود.

عملیات خروجی PITR از همه فیلترها، از جمله خروجی گرفتن از همه اسناد و خروجی گرفتن از مجموعه‌های خاص، پشتیبانی می‌کند.

قبل از خروجی گرفتن از داده‌های PITR به نکات زیر توجه کنید:

  • مهر زمانی را با فرمت RFC 3339 مشخص کنید. برای مثال، 2023-05-26T10:20:00.00Z .
  • مطمئن شوید که مهر زمانی که مشخص می‌کنید، یک مهر زمانی یک دقیقه‌ای کامل در هفت روز گذشته باشد، اما نه زودتر از earliestVersionTime . اگر داده‌ها دیگر در مهر زمانی مشخص شده وجود نداشته باشند، خطایی ایجاد می‌شود.
  • برای صادرات ناموفق PITR هزینه‌ای از شما دریافت نمی‌شود.

کنسول

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید
  2. یک پایگاه داده از لیست پایگاه‌های داده انتخاب کنید.
  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.
  4. روی «صادر کردن» کلیک کنید.
  5. منبع خروجی را طوری پیکربندی کنید که کل پایگاه داده یا فقط مجموعه‌های خاصی را خروجی بگیرد.

  6. در بخش «انتخاب وضعیت پایگاه داده برای صادرات» ، «صادرات از یک نقطه زمانی قبلی» را انتخاب کنید.

    یک زمان snapshot برای استفاده جهت خروجی گرفتن انتخاب کنید

  7. در بخش مقصد ، نام یک مخزن Cloud Storage را وارد کنید یا از دکمه مرور برای انتخاب یک مخزن استفاده کنید.

  8. روی «صادر کردن» کلیک کنید.

    کنسول به صفحه Import/Export برمی‌گردد. اگر عملیات با موفقیت شروع شود، صفحه یک ورودی به صفحه import و export اخیر اضافه می‌کند. در صورت عدم موفقیت، صفحه یک پیام خطا نمایش می‌دهد.

جی‌کلاود

شما می‌توانید با استفاده از دستور gcloud firestore export پایگاه داده خود را از داده‌های PITR به Cloud Storage صادر کنید.

پایگاه داده را با مشخص کردن پارامتر snapshot-time به یک مهر زمانی بازیابی، صادر کنید. دستور زیر را برای صادر کردن پایگاه داده به سطل خود اجرا کنید.

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

که در آن PITR_TIMESTAMP یک مهر زمانی PITR بر اساس جزئیات دقیقه است، برای مثال، 2023-05-26T10:20:00.00Z .

برای خروجی گرفتن از مجموعه‌های خاص، فلگ --collection-ids را اضافه کنید.

وارد کردن داده

وقتی فایل‌های خروجی را در Cloud Storage ذخیره کردید، می‌توانید اسناد موجود در آن فایل‌ها را دوباره به پروژه خود یا پروژه دیگری وارد کنید. به نکات زیر در مورد عملیات وارد کردن توجه کنید:

  • وقتی داده‌ها را وارد می‌کنید، شاخص‌های مورد نیاز با استفاده از تعاریف شاخص فعلی پایگاه داده شما به‌روزرسانی می‌شوند. یک export شامل تعاریف شاخص نیست.

  • ایمپورت‌ها شناسه‌های سند جدیدی اختصاص نمی‌دهند. ایمپورت‌ها از شناسه‌های ثبت‌شده در زمان اکسپورت استفاده می‌کنند. هنگام ایمپورت یک سند، شناسه آن برای جلوگیری از تداخل شناسه‌ها رزرو می‌شود. اگر سندی با شناسه مشابه از قبل وجود داشته باشد، ایمپورت سند موجود را بازنویسی می‌کند.

  • اگر سندی در پایگاه داده شما تحت تأثیر واردات قرار نگیرد، پس از واردات در پایگاه داده شما باقی خواهد ماند.

  • عملیات‌های ایمپورت، توابع ابری را فعال نمی‌کنند. شنوندگان اسنپ‌شات به‌روزرسانی‌های مربوط به عملیات ایمپورت را دریافت می‌کنند.

  • نام فایل .overall_export_metadata ‎ باید با نام پوشه والد آن مطابقت داشته باشد:

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

    اگر فایل‌های خروجی یک خروجی را جابجا یا کپی می‌کنید، نام فایل PARENT_FOLDER_NAME و .overall_export_metadata را یکسان نگه دارید.

تمام اسناد را از یک خروجی وارد کنید

کنسول ابری گوگل

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. روی وارد کردن کلیک کنید.

  5. در فیلد نام فایل ، نام فایل .overall_export_metadata را از یک عملیات خروجی تکمیل شده وارد کنید. می‌توانید از دکمه مرور برای انتخاب فایل استفاده کنید.

  6. روی وارد کردن کلیک کنید.

کنسول به صفحه Import/Export برمی‌گردد. اگر عملیات با موفقیت شروع شود، صفحه یک ورودی به صفحه import و export اخیر اضافه می‌کند. در صورت عدم موفقیت، صفحه یک پیام خطا نمایش می‌دهد.

جی‌کلاود

از دستور firestore import برای وارد کردن اسناد از عملیات export قبلی استفاده کنید.

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

موارد زیر را جایگزین کنید:

  • BUCKET_NAME/EXPORT_PREFIX : محل فایل‌های خروجی شما.

  • DATABASE : نام پایگاه داده. برای پایگاه داده پیش‌فرض، از --database='(default)' استفاده کنید.

برای مثال:

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

می‌توانید محل فایل‌های خروجی خود را در مرورگر Cloud Storage در کنسول Google Cloud تأیید کنید:

مرورگر Cloud Storage باز کنید

زمانی که یک عملیات واردات را شروع می‌کنید، بستن ترمینال عملیات را لغو نمی‌کند، به لغو عملیات مراجعه کنید.

وارد کردن مجموعه‌های خاص

کنسول ابری گوگل

شما نمی‌توانید مجموعه‌های خاصی را در کنسول انتخاب کنید. به جای آن از gcloud استفاده کنید.

جی‌کلاود

برای وارد کردن گروه‌های خاص مجموعه از مجموعه‌ای از فایل‌های خروجی، از پرچم --collection-ids استفاده کنید. این عملیات فقط گروه‌های مجموعه با شناسه‌های مجموعه داده شده را وارد می‌کند. گروه مجموعه شامل تمام مجموعه‌ها و زیرمجموعه‌ها (در هر مسیری) با شناسه مجموعه مشخص شده است. نام پایگاه داده را با استفاده از پرچم --database مشخص کنید. برای پایگاه داده پیش‌فرض، از --database='(default)' استفاده کنید.

فقط خروجی گرفتن از گروه‌های خاص مجموعه، از ورودی گرفتن از گروه‌های خاص مجموعه پشتیبانی می‌کند. شما نمی‌توانید مجموعه‌های خاص را از خروجی گرفتن از همه اسناد، وارد کنید.

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

وارد کردن یک خروجی PITR

برای وارد کردن پایگاه داده‌ی خروجی گرفته شده، از مراحل موجود در «وارد کردن همه اسناد» استفاده کنید. اگر سندی از قبل در پایگاه داده شما وجود داشته باشد، رونویسی خواهد شد.

مدیریت عملیات صادرات و واردات

پس از شروع عملیات صادرات یا واردات، Cloud Firestore یک نام منحصر به فرد به عملیات اختصاص می‌دهد. می‌توانید از نام عملیات برای حذف، لغو یا بررسی وضعیت عملیات استفاده کنید.

نام عملیات‌ها با پیشوند projects/[PROJECT_ID]/databases/(default)/operations/ شروع می‌شوند، برای مثال: 

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

با این حال، می‌توانید هنگام مشخص کردن نام عملیات برای دستورات describe ، cancel و delete پیشوند را حذف کنید.

فهرست تمام عملیات صادرات و واردات

کنسول ابری گوگل

می‌توانید فهرستی از عملیات‌های اخیر صادرات و واردات را در صفحه واردات/صادرات کنسول Google Cloud مشاهده کنید.

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

جی‌کلاود

برای مشاهده‌ی تمام عملیات‌های اکسپورت و ایمپورت در حال اجرا و اخیراً تکمیل‌شده، از دستور operations list استفاده کنید: 

gcloud firestore operations list

بررسی وضعیت عملیات

کنسول ابری گوگل

می‌توانید وضعیت عملیات صادرات یا واردات اخیر را در صفحه واردات/صادرات کنسول Google Cloud مشاهده کنید.

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

جی‌کلاود

از دستور operations describe برای نمایش وضعیت یک عملیات export یا import استفاده کنید. 

gcloud firestore operations describe [OPERATION_NAME]

تخمین زمان تکمیل

درخواست وضعیت یک عملیات طولانی‌مدت، معیارهای workEstimated و workCompleted را برمی‌گرداند. هر یک از این معیارها هم بر حسب تعداد بایت‌ها و هم بر حسب تعداد موجودیت‌ها برگردانده می‌شوند:

  • workEstimated تعداد کل تخمینی بایت‌ها و اسنادی را که یک عملیات پردازش خواهد کرد، نشان می‌دهد. اگر Cloud Firestore نتواند تخمینی ارائه دهد، ممکن است این معیار را حذف کند.

  • workCompleted تعداد بایت‌ها و اسناد پردازش‌شده تاکنون را نشان می‌دهد. پس از اتمام عملیات، مقدار آن تعداد کل بایت‌ها و اسنادی را که واقعاً پردازش شده‌اند نشان می‌دهد که ممکن است از مقدار workEstimated بیشتر باشد.

تقسیم workCompleted بر اساس workEstimated برای یک تخمین پیشرفت تقریبی. این تخمین ممکن است دقیق نباشد، زیرا به جمع‌آوری آمار با تأخیر بستگی دارد.

لغو یک عملیات

کنسول ابری گوگل

می‌توانید عملیات صادرات یا واردات در حال اجرا را در صفحه واردات/صادرات کنسول Google Cloud لغو کنید.

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

در جدول واردات و صادرات اخیر ، عملیات در حال اجرا شامل یک دکمه لغو در ستون تکمیل‌شده هستند. برای توقف عملیات، روی دکمه لغو کلیک کنید. این دکمه به یک پیام لغو و سپس وقتی عملیات به طور کامل متوقف می‌شود، به لغو شده تغییر می‌کند.

جدول واردات و صادرات اخیر در کنسول که واردات داده در حال انجام را با گزینه لغو برای توقف عملیات نشان می‌دهد.

جی‌کلاود

برای متوقف کردن عملیاتی که در حال انجام است، از دستور operations cancel استفاده کنید: 

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 را برای عملیات صورتحساب اعمال می‌کند. در صفحه گزارش‌های صورتحساب ابری ، می‌توانید از این برچسب برای مشاهده هزینه‌های مربوط به عملیات واردات و صادرات استفاده کنید:

از منوی فیلترها به برچسب goog-firestoremanaged دسترسی پیدا کنید.

صادرات به BigQuery

شما می‌توانید داده‌ها را از خروجی Cloud Firestore در BigQuery بارگذاری کنید، اما فقط در صورتی که فیلتر collection-ids را مشخص کرده باشید. به بخش «بارگذاری داده‌ها از خروجی‌های Cloud Firestore مراجعه کنید.

محدودیت ستون BigQuery

BigQuery محدودیت ۱۰۰۰۰ ستون در هر جدول را اعمال می‌کند. عملیات اکسپورت Cloud Firestore برای هر گروه مجموعه، یک طرحواره جدول BigQuery ایجاد می‌کند. در این طرحواره، هر نام فیلد منحصر به فرد در یک گروه مجموعه به یک ستون طرحواره تبدیل می‌شود.

اگر طرح BigQuery یک گروه مجموعه از 10،000 ستون فراتر رود، عملیات صادرات Cloud Firestore سعی می‌کند با در نظر گرفتن فیلدهای نقشه به عنوان بایت، زیر محدودیت ستون باقی بماند. اگر این تبدیل تعداد ستون‌ها را به کمتر از 10،000 برساند، می‌توانید داده‌ها را در BigQuery بارگذاری کنید، اما نمی‌توانید زیرفیلدهای درون فیلدهای نقشه را جستجو کنید. اگر تعداد ستون‌ها هنوز از 10،000 بیشتر باشد، عملیات صادرات یک طرح BigQuery برای گروه مجموعه ایجاد نمی‌کند و نمی‌توانید داده‌های آن را در BigQuery بارگذاری کنید.

فرمت خروجی و فایل‌های فراداده

خروجی یک خروجی مدیریت‌شده از قالب گزارش LevelDB استفاده می‌کند.

فایل‌های فراداده

یک عملیات export برای هر گروه مجموعه که مشخص می‌کنید، یک فایل metadata ایجاد می‌کند. فایل‌های metadata معمولاً ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata نامگذاری می‌شوند.

فایل‌های فراداده، بافرهای پروتکل هستند و شما می‌توانید آن‌ها را با کامپایلر پروتکل protoc رمزگشایی کنید. برای مثال، می‌توانید یک فایل فراداده را رمزگشایی کنید تا گروه‌های مجموعه‌ای که فایل‌های خروجی شامل آن‌ها هستند را تعیین کنید: 

protoc --decode_raw < export0.export_metadata

مهاجرت عامل خدمات

Cloud Firestore به جای استفاده از حساب سرویس App Engine از یک عامل سرویس Cloud Firestore برای تأیید عملیات واردات و صادرات استفاده می‌کند. عامل سرویس و حساب سرویس از قراردادهای نامگذاری زیر استفاده می‌کنند:

نماینده خدمات Cloud Firestore
service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore قبلاً به جای سرویس Agent Cloud Firestore از حساب سرویس پیش‌فرض App Engine استفاده می‌کرد. اگر پایگاه داده شما هنوز از حساب سرویس App Engine برای وارد کردن یا صادر کردن داده‌ها استفاده می‌کند، توصیه می‌کنیم دستورالعمل‌های این بخش را برای مهاجرت به استفاده از سرویس Agent Cloud Firestore دنبال کنید.

حساب سرویس App Engine
PROJECT_ID @appspot.gserviceaccount.com

عامل سرویس Cloud Firestore ترجیح داده می‌شود زیرا مختص Cloud Firestore است. حساب سرویس App Engine توسط بیش از یک سرویس به اشتراک گذاشته می‌شود.

مشاهده حساب مجوز

شما می‌توانید از صفحه Import/Export در کنسول Google Cloud مشاهده کنید که عملیات واردات و صادرات شما از کدام حساب برای تأیید درخواست‌ها استفاده می‌کند. همچنین می‌توانید مشاهده کنید که آیا پایگاه داده شما از قبل از عامل سرویس Cloud Firestore استفاده می‌کند یا خیر.

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. حساب مجوز را در کنار برچسب کارهای واردات/صادرات که اجرا می‌شوند، مشاهده کنید.

اگر پروژه شما از عامل سرویس Cloud Firestore استفاده نمی‌کند، می‌توانید با استفاده از هر یک از این تکنیک‌ها به عامل سرویس Cloud Firestore مهاجرت کنید:

اولین تکنیک از این دو تکنیک ترجیح داده می‌شود زیرا دامنه تأثیر را به یک پروژه واحد Cloud Firestore محدود می‌کند. تکنیک دوم ترجیح داده نمی‌شود زیرا مجوزهای موجود در Cloud Storage bucket را منتقل نمی‌کند. با این حال، انطباق امنیتی را در سطح سازمان ارائه می‌دهد.

با بررسی و به‌روزرسانی مجوزهای Cloud Storage مهاجرت کنید

فرآیند مهاجرت دو مرحله دارد:

  1. مجوزهای مخزن Cloud Storage را به‌روزرسانی کنید. برای جزئیات بیشتر به بخش زیر مراجعه کنید.
  2. مهاجرت به نماینده سرویس Cloud Firestore را تأیید کنید.

مجوزهای سطل عامل خدمات

برای هرگونه عملیات صادرات یا واردات که از یک سطل Cloud Storage در پروژه دیگری استفاده می‌کند، باید مجوزهای عامل سرویس Cloud Firestore را برای آن سطل اعطا کنید. به عنوان مثال، عملیاتی که داده‌ها را به پروژه دیگری منتقل می‌کنند، باید به یک سطل در آن پروژه دیگر دسترسی داشته باشند. در غیر این صورت، این عملیات پس از مهاجرت به عامل سرویس Cloud Firestore با شکست مواجه می‌شوند.

گردش‌های کاری واردات و صادرات که در همان پروژه باقی می‌مانند، نیازی به تغییر در مجوزها ندارند. نماینده سرویس Cloud Firestore می‌تواند به طور پیش‌فرض به سطل‌های موجود در همان پروژه دسترسی داشته باشد.

مجوزهای مربوط به مخازن Cloud Storage از پروژه‌های دیگر را به‌روزرسانی کنید تا به service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com service agent. به service agent نقش Firestore Service Agent را اعطا کنید.

نقش Firestore Service Agent مجوزهای خواندن و نوشتن را برای یک مخزن Cloud Storage اعطا می‌کند. اگر نیاز دارید فقط مجوزهای خواندن یا فقط نوشتن را اعطا کنید، از یک نقش سفارشی استفاده کنید.

فرآیند مهاجرت شرح داده شده در بخش زیر به شما کمک می‌کند تا سطل‌های Cloud Storage را که ممکن است نیاز به به‌روزرسانی مجوز داشته باشند، شناسایی کنید.

انتقال یک پروژه به نماینده خدمات Firestore

برای مهاجرت از حساب سرویس App Engine به سرویس Cloud Firestore مراحل زیر را انجام دهید. پس از اتمام، مهاجرت قابل لغو نیست.

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. اگر پروژه شما هنوز به عامل سرویس Cloud Firestore منتقل نشده است، بنری را مشاهده می‌کنید که مهاجرت را شرح می‌دهد و دکمه‌ای با عنوان «بررسی وضعیت سطل» (Check Bucket Status) وجود دارد. مرحله بعدی به شما کمک می‌کند تا خطاهای احتمالی مجوز را شناسایی و برطرف کنید.

    روی بررسی وضعیت سطل کلیک کنید.

    منویی با گزینه تکمیل انتقال و لیستی از Cloud Storage ظاهر می‌شود. ممکن است بارگذاری کامل لیست چند دقیقه طول بکشد.

    این لیست شامل سطل‌هایی است که اخیراً در عملیات واردات و صادرات مورد استفاده قرار گرفته‌اند، اما در حال حاضر مجوزهای خواندن و نوشتن را به نماینده سرویس Cloud Firestore نمی‌دهند.

  5. به نام اصلی عامل سرویس Cloud Firestore پروژه خود توجه کنید. نام عامل سرویس در زیر عامل سرویس ظاهر می‌شود تا به برچسب دسترسی داده شود .

  6. برای هر سطل موجود در لیست که برای عملیات واردات یا صادرات آینده استفاده خواهید کرد، مراحل زیر را انجام دهید:

    1. در ردیف جدول این سطل، روی «رفع» کلیک کنید. این کار صفحه مجوزهای آن سطل را در یک برگه جدید باز می‌کند.

    2. روی افزودن کلیک کنید.
    3. در فیلد New principals ، نام نماینده خدمات Cloud Firestore خود را وارد کنید.
    4. در فیلد «انتخاب نقش» ، «نمایندگان خدمات» > «نماینده خدمات Firestore» را انتخاب کنید.
    5. روی ذخیره کلیک کنید.
    6. به برگه‌ای که صفحه‌ی وارد کردن/صادر کردن Cloud Firestore در آن قرار دارد، برگردید.
    7. این مراحل را برای سایر سطل‌های موجود در لیست تکرار کنید. مطمئن شوید که تمام صفحات لیست را مشاهده می‌کنید.

  7. روی «مهاجرت به نماینده خدمات Firestore» کلیک کنید. اگر هنوز سطل‌هایی با بررسی‌های مجوز ناموفق دارید، باید با کلیک روی «مهاجرت» مهاجرت خود را تأیید کنید.

    یک هشدار به شما اطلاع می‌دهد که چه زمانی مهاجرت شما کامل می‌شود. مهاجرت قابل لغو نیست.

مشاهده وضعیت مهاجرت

برای تأیید وضعیت مهاجرت پروژه خود:

  1. در کنسول گوگل کلود، به صفحه پایگاه‌های داده بروید.

    به پایگاه‌های داده بروید

  2. از لیست پایگاه‌های داده، پایگاه داده مورد نظر را انتخاب کنید.

  3. در منوی پیمایش، روی «وارد کردن/صادر کردن» کلیک کنید.

  4. به دنبال مدیر (Principal) در کنار کارهای Import/Export که به عنوان برچسب اجرا می‌شوند، بگردید.

    اگر مدیر اصلی service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com باشد، پروژه شما قبلاً به عامل سرویس Cloud Firestore منتقل شده است. این مهاجرت قابل لغو نیست.

    اگر پروژه منتقل نشده باشد، یک بنر در بالای صفحه با دکمه «بررسی وضعیت سطل» ظاهر می‌شود. برای تکمیل مهاجرت، به «انتقال به نماینده خدمات Firestore» مراجعه کنید.

افزودن یک محدودیت سیاست در سطح سازمان

  • محدودیت زیر را در سیاست سازمان خود تنظیم کنید:

    برای واردات/صادرات، به نماینده خدمات Firestore نیاز داشته باشید ( firestore.requireP4SAforImportExport ).

    این محدودیت مستلزم آن است که عملیات واردات و صادرات از عامل سرویس Cloud Firestore برای تأیید درخواست‌ها استفاده کنند. برای تنظیم این محدودیت، به ایجاد و مدیریت سیاست‌های سازمان مراجعه کنید.

اعمال این محدودیت سیاست سازمانی، به طور خودکار مجوزهای مناسب برای باکت Cloud Storage را برای عامل سرویس Cloud Firestore اعطا نمی‌کند.

اگر این محدودیت باعث ایجاد خطاهای مجوز برای هرگونه گردش کار واردات یا صادرات شود، می‌توانید آن را غیرفعال کنید تا به استفاده از حساب سرویس پیش‌فرض برگردید. پس از بررسی و به‌روزرسانی مجوزهای سطل Cloud Storage ، می‌توانید دوباره این محدودیت را فعال کنید.