Verileri içe ve dışa aktarma

Verilerin yanlışlıkla silinmesinden kurtulmak ve verileri çevrimdışı işleme için dışa aktarmak üzere yönetilen dışa aktarma ve içe aktarma hizmetini kullanabilirsiniz. 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. Bir Cloud Firestore veritabanından dışa aktarılan veriler başka bir Cloud Firestore veritabanına aktarılabilir. Dışa aktarılan dosyaları Cloud FirestoreBigQuery'a da yükleyebilirsiniz.

Bu sayfada, yönetilen dışa aktarma ve içe aktarma hizmeti ile Cloud Storage kullanılarak Cloud Firestore dokümanlarının nasıl dışa ve içe aktarılacağı açıklanmaktadır. Cloud Firestore yönetilen dışa aktarma ve içe aktarma hizmeti, gcloud komut satırı aracı ve Cloud Firestore API (REST, RPC) aracılığıyla kullanılabilir.

Başlamadan önce

Yönetilen dışa aktarma 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 Google Cloud faturalandırma özelliği etkinleştirilmiş projeler kullanabilir.
2. Projeniz için Cloud Storage paketini veritabanı Cloud Firestore konumunuza yakın bir yerde oluşturun. Dışa ve içe aktarma işlemleri için Rapid paketi veya istekte bulunanın ödeme yaptığı bir paket kullanamazsınız.

3. Hesabınızın Cloud Firestore ve Cloud Storage 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 için gerekli izinleri ve Cloud Storage erişimini verir:

   • Cloud Firestore rolleri: 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, Cloud Firestore hizmet aracısı kullanarak Cloud Storage işlemleri yetkilendirir. 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 yer alıyorsa Cloud Firestore hizmet aracısı, 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 rol 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 kısmını, Cloud Firestore hizmet aracınıza ad vermek için kullanılan proje numaranızla değiştirin. 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 aktarma veya içe aktarma işlemi için kullanılacak Cloud Storage bucket'ında Storage Admin rolü olması gerekir.

Projeniz için gcloud ayarlama

İçe ve dışa aktarma işlemlerini Google Cloud Console veya gcloud komut satırı aracı üzerinden başlatabilirsiniz. gcloud 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'ya erişin.

  Başlat Cloud Shell

  gcloud'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 hizmetinde dışa aktarma dosyalarınız olduğunda bu dosyalardaki belgeleri projenize veya başka bir projeye tekrar 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ı içermiyor.

• İçe aktarma işlemlerinde yeni doküman kimlikleri atanmaz. İçe aktarma işlemlerinde, dışa aktarma sırasında yakalanan kimlikler kullanılır. İçe aktarılan belgelerin kimlik çakışmasını önlemek için kimlikleri 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 etkilenmezse 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 çıktı dosyalarını taşırsanız veya kopyalarsanız PARENT_FOLDER_NAME ve .overall_export_metadata dosya adını aynı tutun.

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

• BSON türleri, Firestore Standard sürümünde desteklenmediğinden BSON türleriyle dışa aktarılan verilerin Firestore Standard sürümü veri tabanına aktarılması başarısız olur.

• Cloud Firestore veritabanına yapılan bir içe aktarma işleminde, varsayılan olmayan ad alanlarındaki (Datastore API) veriler içe aktarılamaz.

  Varsayılan olmayan ad alanlarını içeren veri dosyalarından Cloud Firestore veritabanına aktarma işlemi yalnızca dışa aktarma işlemine varsayılan ad alanına sahip bir --namespace-ids filtresi dahil edilmişse izin verilir. 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 mevcut olan belgelerin ü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 çalışırken yapılan değişiklikleri içerebilir.

Tüm belgeleri 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'ya 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 belgelerin dışa aktarılması ve belirli koleksiyonların dışa aktarılması da dahil olmak üzere tüm filtreleri destekler.

PITR verilerini dışa aktarmadan önce aşağıdaki noktaları göz önünde bulundurun:

• 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 tam dakika zaman damgası olduğundan ve earliestVersionTime tarihinden önce olmadığından emin olun. Belirtilen zaman damgasında veri artık mevcut değilse hata oluşturulur.
• Başarısız bir PITR dışa aktarma işlemi için sizden ücret alınmaz.

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

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

Dışa veya içe aktarma işlemi başlattıktan sonra 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/ 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. 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 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 içinde 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

Son işlemler listesinden bir işlemi kaldırmak için gcloud firestore operations delete komutunu kullanın. Bu komut, Cloud Storage içindeki dışa aktarma dosyalarını silmez.

gcloud firestore operations delete [OPERATION_NAME]

Dışa ve içe aktarma işlemleri için faturalandırma ve fiyatlandırma

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

Dışa aktarma ve içe aktarma işlemleri, Cloud Firestore fiyatlandırmasında listelenen fiyatlar üzerinden okuma birimleri ve yazma birimleri için ücretlendirilir.

Cloud Storage içinde depolanan çıkış dosyaları, Cloud Storage veri depolama alanı 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 Billing 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

Cloud Firestore dışa aktarma işleminden BigQuery'e veri yükleyebilirsiniz ancak yalnızca collection-ids filtresi belirtmeniz koşuluyla. Cloud Firestore dışa aktarma işlemlerinden veri yükleme başlıklı makaleyi inceleyin.

BigQuery'ye Cloud Firestore verileri 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. 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 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 çıktısı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