Verileri içe ve dışa aktarma

Yönetilen dışa ve içe aktarma hizmetini kullanarak verilerin yanlışlıkla silinmesi durumunda kurtarma işlemi yapabilir ve verileri çevrimdışı işleme için dışa aktarabilirsiniz. Tüm dokümanları veya yalnızca belirli koleksiyonları dışa aktarabilirsiniz. Benzer şekilde, dışa aktarılan 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 Cloud Firestore dosyalarını BigQuery'e de yükleyebilirsiniz.

Bu sayfada, yönetilen dışa ve içe aktarma hizmeti ile Cloud Storage kullanılarak Cloud Firestore belgelerinin nasıl dışa ve içe aktarılacağı açıklanmaktadır. Cloud Firestore yönetilen dışa 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 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. Yalnızca faturalandırmanın etkin olduğu Google Cloud projeler, dışa ve içe aktarma işlevini kullanabilir.
2. Cloud Storage veritabanı konumunuza yakın bir konumda projeniz için bir Cloud Firestore paketi oluşturun. Dışa ve içe aktarma işlemleri için Masrafları İstek Sahibi Öder türünde bir paket veya Rapid paketi 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ız gerekli izinlere sahiptir. Aksi takdirde, aşağıdaki roller dışa ve içe aktarma işlemleri ile Cloud Storage erişimi için gerekli izinleri 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 Storage işlemlerini yetkilendirmek için bir Cloud Firestore hizmet aracısı kullanır. Cloud Firestore hizmet aracısı, aşağıdaki adlandırma kuralını kullanır:

Cloud Firestore hizmet aracısı

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

Hizmet aracıları hakkında daha fazla bilgi edinmek için Hizmet aracıları 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 paketiniz, 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 projedeyse 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ğıdaki komutu ç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, Cloud Firestore hizmet aracınızı adlandırmak için kullanılan proje numaranızı yazın. 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 konsolunu kullanarak 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ından görüntüleyebilirsiniz. Ayrıca veritabanınızın Cloud Firestore hizmet aracısını mı yoksa eski App Engine hizmet hesabını mı kullandığını da görüntüleyebilirsiniz.

1. İçe/dışa aktarma işleri şu hesapla ç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 hizmetini ayarlama

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

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

  Başlat Cloud Shell

  gcloud aracı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 dokümanları projenize veya başka bir projeye geri 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şlemi yeni doküman kimlikleri atamaz. İç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 kimliği ayrılır. Aynı kimliğe sahip bir doküman zaten varsa içe aktarma işlemi mevcut dokümanın üzerine yazılır.

• 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şleminin çıkış dosyalarını taşır veya kopyalarsanız PARENT_FOLDER_NAME ve .overall_export_metadata dosya adını aynı tutun.

• Alt koleksiyonlar Cloud Firestore tarafından desteklenmediğinden, alt koleksiyonlar 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ürleri içeren bir dışa aktarma işleminden Firestore Standard sürümü veritabanına yapılan içe aktarma işlemi başarısız olur.

• Cloud Firestore veritabanına yapılan içe aktarma işlemi, varsayılan olmayan ad alanlarından (Datastore API) veri aktaramaz.

  Varsayılan olmayan ad alanları içeren veri dosyalarından bir Cloud Firestore veritabanına içe aktarma işlemine yalnızca dışa aktarma işleminde varsayılan ad alanını içeren bir --namespace-ids filtresi varsa 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 zaten mevcut olan belgelerin üzerine yazılır.

Verileri dışa aktarın

Dışa aktarma işlemi, veritabanınızdaki belgeleri bir Cloud Storage paketindeki dosya grubuna 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 devam ederken 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'

Belirli bir zamana geri yükleme zaman damgasından dışa aktarma

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

PITR dışa aktarma işlemi, tüm belgeleri ve belirli koleksiyonları dışa aktarma 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 ancak earliestVersionTime tarihinden önce olmadığından emin olun. Belirtilen zaman damgasında veri yoksa hata oluşur.
• Başarısız olan belirli bir zamana geri yükleme dışa aktarma işlemleri için ücret alınmaz.

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

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

Bir 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 ön eki kullanmayabilirsiniz.

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

gcloud firestore operations list

Faaliyet durumunu kontrol etme

gcloud firestore operations describe [OPERATION_NAME]

Tamamlanma süresini tahmin etme

Uzun süreli bir işlemin durumuna yönelik istek, workEstimated ve workCompleted metriklerini döndürür. Bu metriklerin her biri hem bayt sayısı hem de varlık sayısı olarak döndürülür:

• workEstimated, bir işlemin işleyeceği tahmini toplam bayt ve doküman sayısını gösterir. Cloud Firestore, tahmin yapamazsa 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 doküman sayısını gösterir. Bu sayı, workEstimated değerinden daha büyük olabilir.

Yaklaşık ilerleme tahmini için workCompleted değerini workEstimated değerine bölün. Bu tahmin, gecikmeli istatistik toplamaya bağlı olduğundan doğru olmayabilir.

İşlemleri iptal etme

gcloud firestore operations cancel [OPERATION_NAME]

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

İşlemleri silme

Son işlemler listesinden bir işlemi kaldırmak için gcloud firestore operations delete komutunu kullanın. Bu komut, dışa aktarma dosyalarını Cloud Storage konumundan 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 ve içe aktarma işlemleri, Cloud Firestore fiyatlandırması bölümünde listelenen ücretler üzerinden okuma ve yazma birimleri için ücretlendirilir.

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

Dışa veya içe aktarma işlemleri tamamlanana kadar Google Cloud bü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 fatura 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şlemindeki verileri BigQuery hizmetine yükleyebilirsiniz ancak bunun için collection-ids filtresi belirtmeniz gerekir. Cloud Firestore dışa aktarma işlemlerinden veri yükleme başlıklı makaleyi inceleyin.

Cloud Firestore verileri BigQuery'ye yüklenirken BSON veri türleri STRING veri türüyle temsil edilir.

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 olur.

Bir koleksiyonun BigQuery şeması 10.000 sütunu aşarsa Cloud Firestore dışa aktarma işlemi, harita alanlarını bayt olarak değerlendirerek sütun sınırının altında kalmaya çalışır. Bu dönüşüm, sütun sayısını 10.000'in altına düşürürse verileri BigQuery içine 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'e yükleyemezsiniz.

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

Yönetilen dışa aktarma işleminin çıkışı, LevelDB günlük biçimini kullanı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 çözebilirsiniz. Örneğin, dışa aktarma dosyalarının içerdiği koleksiyonları belirlemek için bir meta veri dosyasının kodunu çözebilirsiniz:

protoc --decode_raw < export0.export_metadata