Modul 6: Bermigrasi dari Cloud Datastore ke Cloud Firestore

1. Ringkasan

Rangkaian codelab ini (tutorial praktik mandiri) bertujuan untuk membantu developer Google App Engine (Standar) memodernisasi aplikasi mereka dengan memandu mereka melalui serangkaian migrasi. Sebagian besar migrasi tersebut melibatkan peralihan dari layanan paket runtime asli karena runtime generasi berikutnya lebih fleksibel, sehingga memberikan opsi layanan yang lebih beragam kepada pengguna. Cara lain untuk memodernisasi aplikasi adalah dengan mengupgrade ke produk yang lebih baru, dan itulah topik codelab ini.

Pengguna App Engine yang mengakses Datastore dengan library klien Cloud NDB atau Cloud Datastore tidak perlu melakukan migrasi lebih lanjut. Namun, Cloud Firestore adalah penyimpanan data NoSQL terbaru, skalabel, dan sangat tersedia dengan fitur dari Firebase Realtime Database.

Anda berada di tempat yang tepat jika Anda adalah developer yang merasa perlu menggunakan Firestore untuk memanfaatkan fiturnya atau setidaknya cukup tertarik untuk mempelajari apa saja yang diperlukan dalam migrasi ini. Tutorial ini mengajarkan cara memigrasikan aplikasi App Engine yang menggunakan Cloud Datastore ke Cloud Firestore.

PERINGATAN: Migrasi ini bersifat opsional dan mahal. Beralih ke Firestore mengharuskan pengguna menggunakan project yang berbeda (dan mungkin baru). Project cloud dapat menggunakan Datastore atau Firestore, tetapi tidak keduanya. Setelah disetel, lokasi tidak dapat diubah. Karena semua aplikasi App Engine lama menggunakan Datastore, project yang berbeda harus digunakan untuk penggunaan Firestore.

Anda akan mempelajari cara

• Mengenali perbedaan antara Datastore dan Firestore
• Bermigrasi dari Cloud Datastore ke Cloud Firestore

Yang Anda butuhkan

• Project Google Cloud Platform dengan:
  • Akun penagihan GCP aktif
  • App Engine yang diaktifkan
• Keterampilan Python dasar
• Pengetahuan perintah Linux umum yang berfungsi
• Pengetahuan dasar tentang mengembangkan dan men-deploy aplikasi App Engine
• Anda disarankan untuk menyelesaikan codelab Modul 3, termasuk memigrasikannya ke Python 3, sebelum memulai codelab ini (Modul 6).
• Aplikasi App Engine Python 3 Cloud Datastore Modul 3 yang berfungsi.

Survei

Bagaimana Anda akan menggunakan codelab ini?

Hanya membacanya Membaca dan menyelesaikan latihannya

2. Latar belakang

Datastore App Engine menjadi produknya sendiri pada tahun 2013, Google Cloud Datastore, dan kini dapat diakses oleh developer di luar App Engine. Tahun berikutnya, Firebase diakuisisi oleh Google. Pada saat itu, Firebase dikenal dengan database real-time-nya.

Selama beberapa tahun berikutnya, tim Firebase dan Cloud Datastore berupaya mengintegrasikan beberapa fitur Firebase ke Datastore. Akibatnya, pada tahun 2017, Cloud Datastore generasi berikutnya dirilis. Untuk mencerminkan pewarisan beberapa fitur Firebase, layanan ini diubah namanya menjadi Cloud Firestore.

Cloud Firestore menjadi mekanisme penyimpanan NoSQL default untuk project Google Cloud. Aplikasi baru dapat menggunakan Cloud Firestore secara native, sementara database Datastore yang ada dikonversi ke Firestore di balik layar dan kini beroperasi sebagai "Firestore dalam mode Datastore" untuk mempertahankan kompatibilitas dengan operasi Datastore. Akibatnya, aplikasi hanya dapat mengoperasikan Cloud Firestore dalam salah satu mode tersebut, dan setelah ditetapkan, tidak dapat diubah.

Saat ini, saat pengguna membuat project baru dan memilih solusi NoSQL, mereka akan diminta untuk memilih Firestore dalam mode Datastore atau Firestore dalam mode native. Setelah pengguna menambahkan entity Datastore, mereka tidak dapat beralih ke Firestore, dan begitu juga, setelah mode native Firestore dipilih, mereka tidak dapat lagi beralih kembali ke Datastore (atau lebih tepatnya, Firestore dalam mode Datastore). Baca halaman memilih antara Cloud Firestore dalam mode Datastore atau mode Firestore native di dokumentasi untuk mengetahui detail selengkapnya. Untuk memigrasikan aplikasi ke Firestore, project baru harus dibuat, Datastore diekspor, lalu diimpor ke Firestore. Tujuan tutorial ini adalah untuk memberi developer gambaran tentang perbedaan antara penggunaan Cloud Datastore dan Cloud Firestore.

Migrasi ini bukan migrasi yang diharapkan dilakukan pengguna, itulah sebabnya migrasi ini bersifat opsional. Meskipun ada keuntungan yang jelas dalam menggunakan Cloud Firestore secara native seperti autentikasi klien, integrasi aturan Firebase, dan tentu saja, database real-time Firebase, langkah-langkah migrasinya "tidak praktis":

• Anda harus menggunakan project yang berbeda dengan project aplikasi Anda saat ini.
• Project tempat aplikasi telah menambahkan entity Datastore tidak dapat dialihkan ke Firestore dalam mode native
• Demikian pula, project yang telah memilih Firestore dalam mode native tidak dapat dikembalikan ke Firestore dalam mode Datastore.
• Tidak ada alat migrasi yang dapat melakukan streaming data dari satu project ke project lain.
• Beberapa fitur Datastore penting, termasuk namespace dan throughput penulisan yang lebih tinggi (>10 ribu/dtk), tidak tersedia dari Firestore.
• Alat ekspor dan impor adalah skenario "primitif" dan "semua atau tidak sama sekali".
  • Jika aplikasi Anda memiliki banyak entity Datastore, proses ekspor lalu impor ke Firestore dapat memakan waktu berjam-jam.
  • Selama waktu ini, aplikasi/layanan Anda tidak akan dapat menulis/memperbarui data.
  • Aktivitas migrasi dihitung sebagai penggunaan normal; Anda dapat menyebarkannya (di seluruh kuota harian jika memungkinkan) untuk meminimalkan biaya.
  • Karena layanan baru Anda berjalan di project yang berbeda, Anda memerlukan waktu agar update DNS diterapkan.
• Datastore dan Firestore memiliki model data yang serupa tetapi berbeda, sehingga migrasi memerlukan pembaruan cara kerja aplikasi/layanan
  • Kueri turunan dari Datastore kini menjadi Kueri koleksi Firestore (default)
  • Kueri jenis luas dari Datastore adalah Kueri grup koleksi Firestore
  • Pengindeksan dan penanganan berbeda, dll.

Dengan demikian, jika Anda memiliki aplikasi yang cukup sederhana untuk dipertimbangkan migrasinya, bersiap untuk menyimulasikan migrasi tersebut, atau hanya ingin mempelajari Datastore vs. Firestore, silakan lanjutkan!

Pengguna Python 2: Codelab migrasi opsional ini hanya disajikan dalam Python 3, tetapi karena Cloud Firestore juga mendukung 2.x, pengguna dapat menginterpolasi perbedaan dalam penggunaan. Salah satu contohnya adalah bahwa rekaman Firestore menggunakan string Unicode (bukan string byte), sehingga indikator utama u'' diperlukan untuk literal string Python 2, yang berarti fungsi store_visit() 2.x akan terlihat seperti ini:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection(u'Visit')
    doc_ref.add({
        u'timestamp': datetime.now(),
        u'visitor': u'{}: {}'.format(remote_addr, user_agent),
    })

Selain itu, library klien harus beroperasi dengan cara yang sama. Satu-satunya masalah lain yang perlu dipertimbangkan adalah bahwa library Cloud Firestore 2.x "dibekukan" dalam hal pengembangan, sehingga semakin banyak fitur baru yang hanya akan tersedia di library klien Firestore 3.x.

Untuk melanjutkan migrasi ini, berikut adalah langkah-langkah utama dalam tutorial ini:

1. Penyiapan/Prakerja
2. Tambahkan library Cloud Firestore
3. Memperbarui file aplikasi

3. Penyiapan/Prakerja

Sebelum memulai bagian utama tutorial, mari kita siapkan project, dapatkan kodenya, lalu deploy aplikasi dasar pengukuran sehingga kita tahu bahwa kita memulai dengan kode yang berfungsi.

1. Siapkan project

Sebaiknya gunakan kembali project yang sama dengan yang Anda gunakan untuk menyelesaikan codelab Modul 3. Atau, Anda dapat membuat project baru atau menggunakan kembali project lain yang sudah ada. Pastikan project memiliki akun penagihan yang aktif dan App Engine (aplikasi) diaktifkan.

2. Dapatkan aplikasi contoh dasar pengukuran

Salah satu prasyarat untuk codelab ini adalah memiliki aplikasi contoh Modul 3 yang berfungsi. Jika Anda tidak memilikinya, selesaikan tutorial Modul 3 (link di atas) sebelum melanjutkan ke sini. Jika sudah terbiasa dengan kontennya, Anda bisa memulai dengan mengambil kode Modul 3 di bawah.

Baik Anda menggunakan kode Anda atau kode kami, kode Modul 3 adalah tempat kita akan memulai (START). Codelab Modul 6 ini akan memandu Anda melalui setiap langkah, dan setelah selesai, kode akan menyerupai kode pada titik FINISH. (Tutorial ini hanya tersedia untuk Python 3.)

• START: Repo Modul 3
• FINISH: Repo Modul 6
• Seluruh repo (clone atau download ZIP)

Direktori file Modul 3 (milik Anda atau milik kami) akan terlihat seperti ini:

$ ls
README.md               main.py                 templates
app.yaml                requirements.txt

3. Deploy (ulang) aplikasi Modul 3

Langkah prakerja yang tersisa untuk dijalankan sekarang:

1. Biasakan kembali diri Anda dengan alat command-line gcloud (jika perlu)
2. Deploy (ulang) kode Modul 3 ke App Engine (jika perlu)

Setelah Anda berhasil menjalankan langkah-langkah tersebut dan mengonfirmasikan operasinya, kita akan melanjutkan tutorial ini, dimulai dengan file konfigurasi.

CATATAN: Tutorial ini hanya mendukung Python 3; jika Anda memiliki aplikasi Python 2 dan ingin bermigrasi dari Datastore ke Firestore, lihat bagian persyaratan di bawah.

Persyaratan Python 2

• Pastikan app.yaml (masih) mereferensikan paket pihak ketiga: grpcio dan setuptools.
• Pastikan appengine_config.py masih menggunakan pkg_resources dan google.appengine.ext.vendor untuk mengarahkan aplikasi ke resource pihak ketiga.
• Di bagian berikutnya, saat mengupdate requirements.txt, Anda harus menggunakan google-cloud-firestore==1.9.0 karena versi tersebut adalah versi akhir library klien Python Firestore yang kompatibel dengan 2.x.
  • Jika requirements.txt Anda memiliki entri untuk google-cloud-core, biarkan seperti apa adanya.
  • Hapus lib dan instal ulang dengan pip install -t lib -r requirements.txt.

4. Memperbarui file konfigurasi (tambahkan library Cloud Firestore)

Selain penyiapan, langkah berikutnya yang diperlukan adalah memperbarui konfigurasi, diikuti dengan file aplikasi. Untuk yang pertama, satu-satunya perubahan konfigurasi adalah penggantian paket kecil dalam file requirements.txt Anda, jadi mari kita lakukan sekarang.

Ganti baris google-cloud-datastore dengan google-cloud-firestore di requirements.txt sehingga terlihat seperti ini:

Flask==1.1.2
google-cloud-firestore==2.0.2

Sebaiknya gunakan versi terbaru dari setiap library; nomor versi di atas adalah yang terbaru pada saat penulisan tutorial ini. Kode dalam folder repo FINISH lebih sering diperbarui dan mungkin memiliki versi yang lebih baru.

Tidak ada perubahan konfigurasi lainnya, sehingga app.yaml dan templates/index.html tetap seperti semula.

5. Memperbarui file aplikasi

Hanya ada satu file aplikasi, main.py, sehingga semua perubahan di bagian ini hanya memengaruhi file tersebut.

1. Impor

Mengalihkan impor paket adalah perubahan kecil dari datastore ke firestore:

• SEBELUM:

from google.cloud import datastore

• SETELAH:

from google.cloud import firestore

2. Akses Firestore

Setelah menginisialisasi Flask, buat klien Firestore Anda. Lakukan perubahan serupa seperti di atas, tetapi untuk inisialisasi klien:

• SEBELUM:

app = Flask(__name__)
ds_client = datastore.Client()

• SETELAH:

app = Flask(__name__)
fs_client = firestore.Client()

Dengan melakukan migrasi dari Cloud NDB ke Cloud Datastore, Anda telah melakukan pekerjaan berat untuk beralih ke Cloud Firestore. Dengan Datastore, Anda membuat catatan data dalam bentuk Entity yang terdiri dari Properti umum dan mengelompokkannya berdasarkan Kunci. Kumpulan data di Firestore adalah Dokumen, yang terdiri dari key-value pair, dan dikelompokkan menjadi Koleksi. Bermigrasi dari Datastore mengharuskan Anda memikirkan perbedaan ini karena akan terwujud saat Anda membuat serta mengkueri catatan data. Hasil Anda mungkin bervariasi, bergantung pada seberapa rumit kode Datastore Anda.

Untuk Datastore, Anda membuat kueri berdasarkan jenis Entity beserta kriteria pemfilteran dan pengurutan. Untuk Firestore, membuat kueri data serupa. Mari kita lihat contoh singkatnya, dengan asumsi nilai kueri, klien (ds_client atau fs_client), dan impor berikut:

from datetime import datetime
from firestore.Query import DESCENDING

OCT1 = datetime(2020, 10, 1)
LIMIT = 10

Untuk Datastore, mari kita kueri sepuluh entity Visit terbaru yang lebih baru dari 1 Oktober 2020 dalam urutan menurun:

query = ds_client.query(kind='Visit')
query.add_filter('timestamp', '>=', datetime(2020, 10, 1))
query.order = ['-timestamp']
return query.fetch(limit=LIMIT)

Lakukan hal yang sama untuk Firestore, dari koleksi Visit:

query = fs_client.collection('Visit')
query.where('timestamp', '>=', datetime(2020, 10, 1))
query.order_by('timestamp', direction=DESCENDING)
return query.limit(LIMIT).stream()

Kueri aplikasi contoh lebih sederhana (tidak ada klausa "WHERE"). Sebagai ulasan, berikut kode Cloud Datastore:

• SEBELUM:

def store_visit(remote_addr, user_agent):
    entity = datastore.Entity(key=ds_client.key('Visit'))
    entity.update({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })
    ds_client.put(entity)

def fetch_visits(limit):
    query = ds_client.query(kind='Visit')
    query.order = ['-timestamp']
    return query.fetch(limit=limit)

Saat bermigrasi ke Firestore, Anda akan menemukan pembuatan dokumen baru yang serupa dengan entitas, dan kueri seperti yang ditunjukkan sebelumnya.

• SETELAH:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection('Visit')
    doc_ref.add({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })

def fetch_visits(limit):
    visits_ref = fs_client.collection('Visit')
    visits = (v.to_dict() for v in visits_ref.order_by('timestamp',
            direction=firestore.Query.DESCENDING).limit(limit).stream())
    return visits

Fungsi utama root() tetap sama seperti file template index.html. Periksa kembali perubahan Anda, simpan, deploy, dan verifikasi.

6. Ringkasan/Pembersihan

Men-deploy aplikasi

Deploy ulang aplikasi Anda dengan gcloud app deploy dan konfirmasikan bahwa aplikasi berfungsi. Kode Anda sekarang seharusnya cocok dengan yang ada di repo Modul 6 (atau versi 2.x jika itu yang Anda inginkan).

Jika Anda beralih ke rangkaian ini tanpa melakukan codelab sebelumnya, aplikasi itu sendiri tidak akan berubah. Aplikasi akan mendaftarkan semua kunjungan ke halaman web utama (/) dan terlihat seperti ini setelah Anda mengunjungi situs cukup waktu:

Selamat, Anda telah menyelesaikan migrasi Modul 6 opsional ini. Ini kemungkinan merupakan salah satu, jika bukan migrasi terakhir yang dapat Anda lakukan terkait penyimpanan data App Engine. Salah satu alternatif migrasi yang dapat Anda pertimbangkan adalah membuat aplikasi dalam container untuk Cloud Run jika Anda belum melakukannya (lihat Modul 4 dan 5, codelab yang ditautkan di bawah).

Opsional: Pembersihan

Bagaimana dengan pembersihan agar tidak ditagih hingga Anda siap untuk beralih ke codelab migrasi berikutnya? Sebagai developer yang sudah ada, Anda mungkin sudah mengetahui yang terbaru tentang informasi harga App Engine.

PENTING: Runtime App Engine asli sebelumnya tidak memerlukan akun penagihan aktif, tetapi kini tidak lagi (mulai November 2019, diberlakukan mulai April 2020). Namun, kami pastikan bahwa App Engine masih memiliki tingkat akses gratis, sehingga Anda tidak akan dikenakan tagihan apa pun kecuali batas tersebut terlampaui.

Opsional: Nonaktifkan aplikasi

Jika Anda belum siap melanjutkan ke tutorial berikutnya, nonaktifkan aplikasi untuk menghindari tagihan. Jika sudah siap untuk beralih ke codelab berikutnya, Anda dapat mengaktifkannya kembali. Meskipun dinonaktifkan, aplikasi tidak akan mendapatkan traffic yang dikenakan biaya, namun hal lain yang dapat ditagih adalah penggunaan Firestore jika melebihi kuota gratis, jadi cukup hapus hingga berada di bawah batas tersebut.

Di sisi lain, jika Anda tidak akan melanjutkan migrasi dan ingin menghapus semuanya, Anda dapat mematikan project.

Langkah berikutnya

Selain tutorial ini, ada beberapa codelab modul migrasi lain yang dapat Anda pertimbangkan:

• Modul 7: Task Queues Push App Engine (diperlukan jika Anda menggunakan Task Queues [push])
  • Tambahkan tugas push taskqueue App Engine ke aplikasi Modul 1
  • Siapkan pengguna untuk bermigrasi ke Cloud Tasks di Modul 8
• Modul 4: Bermigrasi ke Cloud Run dengan Docker
  • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Docker
  • Migrasi ini memungkinkan Anda untuk tetap menggunakan Python 2.
• Modul 5: Melakukan Migrasi ke Cloud Run dengan Cloud Buildpacks
  • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Cloud Buildpacks
  • Anda tidak perlu mengetahui apa pun tentang Docker, container, atau Dockerfile.
  • Mengharuskan aplikasi Anda untuk sudah bermigrasi ke Python 3 (Buildpacks tidak mendukung Python 2)

7. Referensi lainnya

Masalah/masukan codelab modul migrasi App Engine

Jika Anda menemukan masalah dengan codelab ini, telusuri masalah Anda terlebih dahulu sebelum mengajukan masalah. Link untuk menelusuri dan membuat masalah baru:

• Telusuri masalah
• Ajukan masukan/masukan baru

Referensi migrasi

Link ke folder repo untuk Modul 3 (START) dan Modul 6 (FINISH) dapat ditemukan pada tabel di bawah. Link tersebut juga dapat diakses dari repo untuk semua migrasi App Engine yang dapat Anda clone atau download file ZIP.

Codelab	Python 2	Python 3
Modul 3	(kode)	kode
Modul 6	(T/A)	kode

Resource App Engine

Berikut adalah resource tambahan terkait migrasi khusus ini:

• Referensi Python Cloud Datastore dan Cloud Firestore
  • Dokumen library klien Google Cloud Datastore
  • Repo library klien Google Cloud Datastore
  • Dokumen library klien Google Cloud Firestore
  • Repo library klien Google Cloud Firestore
• Melakukan migrasi ke Python 3 dan runtime GAE generasi berikutnya
  • Halaman beranda migrasi
  • Melakukan migrasi file konfigurasi App Engine
• Umum
  • Python di Google Cloud Platform
  • Library klien Python Google Cloud