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

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

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

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

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

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

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

   • نقش‌های سازگاری Cloud Firestore با MongoDB: Owner ، Cloud Datastore Owner یا Cloud Datastore Import Export Admin

   • نقش‌های Cloud Storage : Owner یا Storage Admin

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

عملیات صادرات و واردات از یک عامل سرویس 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 Shell از کنسول Google Cloud gcloud دسترسی پیدا کنید.

  شروع Cloud Shell

  مطمئن شوید که gcloud برای پروژه صحیح پیکربندی شده است:

  gcloud config set project [PROJECT_ID]
  

• Google Cloud SDK را نصب و راه‌اندازی کنید.

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

وقتی فایل‌های خروجی را در 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 را یکسان نگه دارید.

• وارد کردن (import) از یک خروجی با زیرمجموعه‌ها به یک پایگاه داده Cloud Firestore با سازگاری MongoDB با شکست مواجه می‌شود، زیرا زیرمجموعه‌ها در Cloud Firestore با سازگاری MongoDB پشتیبانی نمی‌شوند.

• وارد کردن (import) یک پایگاه داده نسخه استاندارد Cloud Firestore از یک خروجی با انواع BSON با شکست مواجه می‌شود زیرا انواع BSON در نسخه استاندارد Cloud Firestore پشتیبانی نمی‌شوند.

• وارد کردن داده‌ها به یک فروشگاه ابری Firestore با پایگاه داده سازگاری MongoDB نمی‌تواند داده‌ها را از فضاهای نام غیر پیش‌فرض ( Datastore API) وارد کند.

  وارد کردن فایل‌های داده‌ای که حاوی فضاهای نام غیر پیش‌فرض هستند به یک Cloud Firestore با پایگاه داده سازگاری MongoDB تنها در صورتی مجاز است که عملیات صادرات شامل یک فیلتر --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

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

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

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

• مهر زمانی را با فرمت RFC 3339 مشخص کنید. برای مثال، 2020-09-01T23:59:30.234233Z .
• مطمئن شوید که مهر زمانی که مشخص می‌کنید، یک مهر زمانی یک دقیقه‌ای کامل در هفت روز گذشته باشد، اما نه زودتر از earliestVersionTime . اگر داده‌ها دیگر در مهر زمانی مشخص شده وجود نداشته باشند، خطایی ایجاد می‌شود.
• برای صادرات ناموفق PITR هزینه‌ای از شما دریافت نمی‌شود.

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

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

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

نام عملیات‌ها با پیشوند 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 با سازگاری MongoDB اگر نتواند تخمینی انجام دهد، ممکن است این معیار را حذف کند.

• 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 با قیمت‌گذاری سازگاری MongoDB محاسبه می‌شود.

فایل‌های خروجی ذخیره شده در Cloud Storage جزو هزینه‌های ذخیره‌سازی داده‌های Cloud Storage شما محسوب می‌شوند.

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

مشاهده هزینه‌های صادرات و واردات

عملیات صادرات و واردات، برچسب goog-firestoremanaged:exportimport را برای عملیات صورتحساب اعمال می‌کند. در صفحه گزارش‌های صورتحساب ابری ، می‌توانید از این برچسب برای مشاهده هزینه‌های مربوط به عملیات واردات و صادرات استفاده کنید:

صادرات به BigQuery

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

هنگام بارگذاری Cloud Firestore با داده‌های سازگاری MongoDB در BigQuery، انواع داده‌های BSON با نوع داده STRING نمایش داده می‌شوند.

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

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

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

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

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

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

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

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

protoc --decode_raw < export0.export_metadata