Verileri içe ve dışa aktarma

Yönetilen dışa ve içe aktarma hizmetini kullanarak yanlışlıkla silinen verileri kurtarabilir ve çevrimdışı işleme için verileri dışa aktarabilirsiniz. Tüm dokümanları veya yalnızca belirli koleksiyonları dışa aktarabilirsiniz. Aynı şekilde, dışa aktarma işleminden tüm verileri veya yalnızca belirli koleksiyonları içe aktarabilirsiniz. MongoDB uyumluluğu olan bir Cloud Firestore veritabanından dışa aktarılan veriler, MongoDB uyumluluğu olan başka bir Cloud Firestore veritabanına aktarılabilir. MongoDB uyumlu dışa aktarma işlemlerini kullanarak Cloud Firestore'u BigQuery ile de yükleyebilirsiniz.

Bu sayfada, yönetilen dışa ve içe aktarma hizmeti ile Cloud Storage kullanarak MongoDB uyumluluğu olan Cloud Firestore belgelerini nasıl dışa ve içe aktaracağınız açıklanmaktadır. MongoDB uyumluluğu ile Cloud Firestore'un yönetilen dışa aktarma ve içe aktarma hizmeti, gcloud komut satırı aracı ve MongoDB uyumluluğu ile Cloud Firestore API'si (REST, RPC) aracılığıyla kullanılabilir.

Başlamadan önce

Yönetilen dışa ve içe aktarma hizmetini kullanabilmek için aşağıdaki görevleri tamamlamanız gerekir:

1. Google Cloud projeniz için faturalandırmayı etkinleştirin. Dışa ve içe aktarma işlevini yalnızca faturalandırma özelliği etkinleştirilmiş Google Cloud projeler kullanabilir.
2. Projeniz için Cloud Storage paketi oluşturun. Bu paket, MongoDB uyumluluğu olan Cloud Firestore veritabanı konumunuza yakın bir konumda olmalıdır. Dışa aktarma ve içe aktarma işlemleri için İstek Sahibi Öder (Requester Pays) grubu kullanamazsınız.

3. Hesabınızın, MongoDB uyumluluğu ve Cloud Storage ile Cloud Firestore için gerekli izinlere sahip olduğundan emin olun. Proje sahibiyseniz hesabınızda gerekli izinler vardır. Aksi takdirde, aşağıdaki roller dışa ve içe aktarma işlemleri ile Cloud Storage'ya erişim için gerekli izinleri verir:

   • MongoDB uyumluluğu rolleriyle Cloud Firestore: Owner, Cloud Datastore Owner veya Cloud Datastore Import Export Admin

   • Cloud Storage rolleri: Owner veya Storage Admin

Hizmet aracısı izinleri

Dışa ve içe aktarma işlemleri, işlemleri Cloud Firestore yetkilendirmek için Cloud Storage bir hizmet aracısı kullanır. Cloud Firestore hizmet aracısı şu adlandırma kuralını kullanır:

Cloud Firestore hizmet aracısı

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

Servis temsilcileri hakkında daha fazla bilgi edinmek için Servis temsilcileri başlıklı makaleyi inceleyin.

Cloud Firestore hizmet aracısının, dışa veya içe aktarma işleminde kullanılan Cloud Storage paketine erişmesi gerekir. Cloud Storage paketi, Cloud Firestore veritabanınızla aynı projede bulunuyorsa Cloud Firestore hizmet aracısı, Cloud Firestore pakete varsayılan olarak erişebilir.

Cloud Storage paketi başka bir projede bulunuyorsa Cloud Firestore hizmet aracısına Cloud Storage paketine erişim izni vermeniz gerekir.

Hizmet aracısına roller atama

Aşağıdaki rollerden birini atamak için gsutil komut satırı aracını kullanabilirsiniz. Örneğin, Cloud Firestore hizmet aracısına Depolama Alanı Yöneticisi rolünü atamak için aşağıdakileri çalıştırın:

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

PROJECT_NUMBER yerine proje numaranızı yazın. Bu numara, Cloud Firestore hizmet aracınıza ad vermek için kullanılır. Hizmet aracısı adını görüntülemek için Hizmet aracısı adını görüntüleme başlıklı makaleyi inceleyin.

Alternatif olarak, bu rolü Google Cloud Console'u kullanarak da atayabilirsiniz.

Hizmet aracısı adını görüntüleme

İçe ve dışa aktarma işlemlerinizin istekleri yetkilendirmek için kullandığı hesabı Google Cloud Console'daki İçe/Dışa Aktarma sayfasında görüntüleyebilirsiniz. Veritabanınızın Cloud Firestore hizmet aracısını mı yoksa eski App Engine hizmet hesabını mı kullandığını da görebilirsiniz.

1. İçe/Dışa aktarma işleri şu şekilde çalıştırılır: etiketinin yanındaki yetkilendirme hesabını görüntüleyin.

Hizmet aracısının, dışa veya içe aktarma işlemi için kullanılacak Cloud Storage paketi için Storage Admin rolüne sahip olması gerekir.

Projeniz için gcloud oluşturma

İçe ve dışa aktarma işlemlerini Google Cloud Console veya gcloud komut satırı aracı üzerinden başlatabilirsiniz. gcloud aracını kullanmak için komut satırı aracını ayarlayın ve aşağıdaki yöntemlerden birini kullanarak projenize bağlanın:

• Cloud Shell kullanarak Google Cloud konsolundan gcloud erişin.

  Başlat Cloud Shell

  gcloud cihazının doğru proje için yapılandırıldığından emin olun:

  gcloud config set project [PROJECT_ID]
  

• Google Cloud SDK'yı yükleyip başlatın.

Verileri içe aktarma

Cloud Storage içinde dışa aktarma dosyalarınız olduğunda bu dosyalardaki dokümanları projenize veya başka bir projeye yeniden içe aktarabilirsiniz. İçe aktarma işlemleriyle ilgili aşağıdaki noktalara dikkat edin:

• Verileri içe aktardığınızda, gerekli dizinler veritabanınızın mevcut dizin tanımları kullanılarak güncellenir. Dışa aktarma işlemi dizin tanımlarını içermez.

• İçe aktarma işlemlerinde yeni doküman kimlikleri atanmaz. İçe aktarma işlemlerinde, dışa aktarma sırasında yakalanan kimlikler kullanılır. Bir doküman içe aktarılırken kimlik çakışmalarını önlemek için dokümanın kimliği ayrılır. Aynı kimliğe sahip bir doküman zaten varsa içe aktarma işlemi mevcut dokümanın üzerine yazar.

• Veritabanınızdaki bir doküman içe aktarma işleminden etkilenmiyorsa içe aktarma işleminden sonra veritabanınızda kalır.

• .overall_export_metadata dosya adı, üst klasörünün adıyla eşleşmelidir:

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

  Dışa aktarma işleminden elde edilen çıkış dosyalarını taşırsanız veya kopyalarsanız PARENT_FOLDER_NAME ve .overall_export_metadata dosya adını aynı tutun.

• Alt koleksiyonlar, MongoDB uyumluluğu olan Cloud Firestore'da desteklenmediğinden alt koleksiyon içeren bir dışa aktarma işleminden MongoDB uyumluluğu olan Cloud Firestore veritabanına yapılan içe aktarma işlemi başarısız olur.

• BSON türlerini içeren bir dışa aktarma işleminden Cloud Firestore Standard Edition veritabanına yapılan içe aktarma işlemi, BSON türleri Cloud Firestore Standard Edition'da desteklenmediği için başarısız olur.

• MongoDB uyumluluğu olan bir Cloud Firestore veritabanına yapılan içe aktarma işleminde, varsayılan olmayan ad alanlarından (Datastore API) veri içe aktarılamaz.

  Varsayılan olmayan ad alanlarını içeren veri dosyalarından MongoDB uyumluluğu olan bir Cloud Firestore veritabanına içe aktarma işlemi yalnızca dışa aktarma işleminde varsayılan ad alanıyla bir --namespace-ids filtresi varsa gerçekleştirilebilir. Yalnızca varsayılan ad alanındaki veriler içe aktarılır.

Dışa aktarılan tüm dokümanları içe aktarma

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

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

Belirli koleksiyonları içe aktarma

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

PITR verileri içeren bir dışa aktarma işleminden içe aktarma

PITR verilerini içe aktarmak için Tüm dokümanları içe aktarma veya Belirli koleksiyonları içe aktarma bölümündeki adımları uygulayın. Veritabanınızda zaten bulunan dokümanların üzerine yazılır.

Verileri dışa aktarın

Dışa aktarma işlemi, veritabanınızdaki dokümanları bir Cloud Storage paketindeki bir dizi dosyaya kopyalar. Dışa aktarma işleminin, dışa aktarma başlangıç zamanında alınan tam bir veritabanı anlık görüntüsü olmadığını unutmayın. Dışa aktarma işlemi, işlem yürütülürken yapılan değişiklikleri içerebilir.

Tüm dokümanları dışa aktarma

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

Belirli koleksiyonları dışa aktarma

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 zaman damgasından dışa aktarma

Veritabanınızı PITR verilerinden Cloud Storage biçiminde dışa aktarabilirsiniz. Zaman damgasının son yedi gün içinde tam dakika zaman damgası olduğu PITR verilerini dışa aktarabilirsiniz ancak earliestVersionTime tarihinden önceki verileri dışa aktaramazsınız. Belirtilen zaman damgasında artık veri yoksa dışa aktarma işlemi başarısız olur.

PITR dışa aktarma işlemi, tüm filtreleri destekler. Bu kapsamda, tüm belgelerin ve belirli koleksiyonların dışa aktarılması da yer alır.

PITR verilerini dışa aktarmadan önce aşağıdaki noktalara dikkat edin:

• Zaman damgasını RFC 3339 biçiminde belirtin. Örneğin, 2020-09-01T23:59:30.234233Z.
• Belirttiğiniz zaman damgasının, son yedi gün içinde ancak earliestVersionTime tarihinden önce olmayan tam dakikalık bir zaman damgası olduğundan emin olun. Belirtilen zaman damgasında artık veri yoksa hata oluşturulur.
• Başarısız bir PITR dışa aktarma işlemi için ücretlendirilmezsiniz.

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

Dışa ve içe aktarma işlemlerini yönetme

Bir dışa aktarma veya içe aktarma işlemini başlattıktan sonra MongoDB uyumlu Cloud Firestore, işleme benzersiz bir ad atar. İşlemi silmek, iptal etmek veya durumunu kontrol etmek için işlem adını kullanabilirsiniz.

İşlem adlarının önüne projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/ ön eki eklenir. Örneğin:

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

Ancak describe, cancel ve delete komutları için işlem adı belirtirken öneki atlayabilirsiniz.

Tüm dışa ve içe aktarma işlemlerini listeleme

gcloud firestore operations list

İşlem durumunu kontrol etme

gcloud firestore operations describe [OPERATION_NAME]

Tamamlanma süresini tahmin etme

Uzun süreli bir işlemin durumuyla ilgili istek, workEstimated ve workCompleted metriklerini döndürür. Bu metriklerin her biri hem bayt sayısı hem de öğe sayısı olarak döndürülür:

• workEstimated, bir işlemin işleyeceği tahmini toplam bayt ve belge sayısını gösterir. MongoDB uyumluluğu olan Cloud Firestore, tahmin yapamıyorsa bu metriği atlayabilir.

• workCompleted, şu ana kadar işlenen bayt ve doküman sayısını gösterir. İşlem tamamlandıktan sonra değer, gerçekte işlenen toplam bayt ve belge sayısını gösterir. Bu sayı, workEstimated değerinden daha büyük olabilir.

Kabaca bir ilerleme durumu tahmini için workCompleted değerini workEstimated değerine bölün. Bu tahmin, gecikmeli istatistik toplama işlemine bağlı olduğundan yanlış olabilir.

İşlemi iptal etme

gcloud firestore operations cancel [OPERATION_NAME]

Çalışan bir işlemi iptal etmek, işlemi geri almaz. İptal edilen bir dışa aktarma işlemi, daha önce dışa aktarılan dokümanları Cloud Storage'da bırakır. İptal edilen bir içe aktarma işlemi ise veritabanınızda yapılan güncellemeleri olduğu gibi bırakır. Kısmen tamamlanmış bir dışa aktarma işlemini içe aktaramazsınız.

İşlem silme

gcloud firestore operations delete komutunu kullanarak bir işlemi son işlemler listesinden kaldırın. Bu komut, Cloud Storage'daki dışa aktarma dosyalarını silmez.

gcloud firestore operations delete [OPERATION_NAME]

Dışa ve içe aktarma işlemlerinin faturalandırılması ve fiyatlandırması

Yönetilen dışa ve içe aktarma hizmetini kullanmadan önce Google Cloud projeniz için faturalandırmayı etkinleştirmeniz gerekir.

Dışa ve içe aktarma işlemleri, MongoDB uyumluluğu ile Cloud Firestore fiyatlandırması bölümünde listelenen fiyatlar üzerinden okuma birimleri ve yazma birimleri için ücretlendirilir.

Cloud Storage içinde depolanan çıkış dosyaları, Cloud Storage veri depolama maliyetlerinize dahil edilir.

Dışa aktarma veya içe aktarma işlemleri tamamlanana kadar Google Cloudbütçe uyarılarınızı tetiklemez. Dışa ve içe aktarma işlemleri, konsolun kullanım bölümünde gösterilen kullanımı etkilemez.

Dışa ve içe aktarma maliyetlerini görüntüleme

Dışa ve içe aktarma işlemleri, faturalandırılan işlemlere goog-firestoremanaged:exportimport etiketini uygular. Cloud Faturalandırma raporları sayfasında, içe ve dışa aktarma işlemleriyle ilgili maliyetleri görüntülemek için bu etiketi kullanabilirsiniz:

BigQuery'ye aktarın

MongoDB uyumluluğu ile Cloud Firestore dışa aktarımından BigQuery'ya veri yükleyebilirsiniz ancak yalnızca collection-ids filtresi belirtmeniz koşuluyla. MongoDB uyumluluğu dışa aktarımlarıyla Cloud Firestore'dan veri yükleme başlıklı makaleye bakın.

MongoDB uyumluluğu verileriyle Cloud Firestore'u BigQuery'ye yüklerken BSON veri türleri STRING veri türüyle gösterilir.

BigQuery sütun sınırı

BigQuery,tablo başına 10.000 sütun sınırı uygular. MongoDB uyumluluğu ile Cloud Firestore dışa aktarma işlemleri, her koleksiyon için bir BigQuery tablo şeması oluşturur. Bu şemada, bir koleksiyondaki her benzersiz alan adı bir şema sütunu haline gelir.

Bir koleksiyonun BigQuery şeması 10.000 sütunu aşarsa MongoDB uyumluluğu ile Cloud Firestore dışa aktarma işlemi, harita alanlarını bayt olarak ele alarak sütun sınırının altında kalmaya çalışır. Bu dönüştürme işlemiyle sütun sayısı 10.000'in altına düşerse verileri BigQuery'ya yükleyebilirsiniz ancak harita alanlarındaki alt alanları sorgulayamazsınız. Sütun sayısı hâlâ 10.000'i aşıyorsa dışa aktarma işlemi, koleksiyon için BigQuery şeması oluşturmaz ve verilerini BigQuery'ya yükleyemezsiniz.

Dışa aktarma biçimi ve meta veri dosyaları

Yönetilen dışa aktarma işleminin çıkışında LevelDB günlük biçimi kullanılır.

Meta veri dosyaları

Dışa aktarma işlemi, belirttiğiniz her koleksiyon için bir meta veri dosyası oluşturur. Meta veri dosyaları genellikle ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata olarak adlandırılır.

Meta veri dosyaları protokol arabellekleridir ve bunları protoc protokol derleyicisi ile kodunu çözebilirsiniz. Örneğin, dışa aktarılan dosyaların hangi koleksiyonları içerdiğini belirlemek için bir meta veri dosyasının kodunu çözebilirsiniz:

protoc --decode_raw < export0.export_metadata