وارد کردن و صادر کردن داده‌ها

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

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

قبل از شروع

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

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

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

   • نقش‌های Cloud Firestore: 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 bucket در همان پروژه Cloud Firestore پایگاه داده شما باشد، سپس Cloud Firestore عامل سرویس می‌تواند به‌طور پیش‌فرض به bucket دسترسی داشته باشد.

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

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

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

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

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

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

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

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

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

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

• بااستفاده از Cloud Shell، از کنسول Google Cloud به gcloud دسترسی پیدا کنید.

  شروع Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• کیت توسعه نرم‌افزار Google Cloud را نصب و مقداردهی اولیه کنید.

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

وقتی فایل‌های صادرشده را در 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 از صادر کردن با انواع BSON ناموفق است زیرا انواع BSON در نسخه Firestore Standard پشتیبانی نمی‌شود.

• وارد کردن به پایگاه داده 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 bucket کپی می‌کند. توجه داشته باشید که صادر کردن، عکس آنی دقیق از پایگاه داده نیست که در زمان شروع صادر کردن گرفته شده باشد. ممکن است صادر کردن شامل تغییراتی باشد که درحین اجرای عملیات انجام شده است.

صادر کردن همه اسناد

  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 نباشد. اگر داده‌ها دیگر در مُهر زمان مشخص‌شده وجود نداشته باشد، خطایی ایجاد می‌شود.
• هزینه‌ای بابت صادر کردن ناموفق «بازیابی نقطه‌زمانی» از شما کسر نمی‌شود.

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

صادر کردن به BigQuery

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

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

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

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

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

قالب صادر کردن و فایل‌های فراداده

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

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

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

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

protoc --decode_raw < export0.export_metadata