Modul 3: Bermigrasi dari Google Cloud NDB ke Cloud Datastore

1. Ringkasan

Rangkaian codelab ini (tutorial interaktif dan mandiri) bertujuan untuk membantu developer Google App Engine (lingkungan standar) memodernisasi aplikasi mereka dengan memandu mereka melalui serangkaian migrasi. Langkah yang paling signifikan adalah beralih dari layanan paket runtime asli karena runtime generasi berikutnya lebih fleksibel, sehingga memberikan opsi layanan yang lebih beragam kepada pengguna. Peralihan ke runtime generasi baru memungkinkan Anda berintegrasi dengan produk Google Cloud dengan lebih mudah, menggunakan berbagai layanan yang didukung, dan mendukung rilis bahasa saat ini.

Tutorial opsional ini menunjukkan kepada developer cara melakukan migrasi dari Cloud NDB ke Cloud Datastore sebagai library klien untuk berkomunikasi dengan layanan Datastore. Developer yang lebih memilih NDB dapat tetap menggunakannya karena kompatibel dengan Python 3, sehingga migrasi ini bersifat opsional. Migrasi ini hanya untuk mereka yang ingin membangun codebase yang konsisten dan library bersama dengan aplikasi lain yang sudah menggunakan Cloud Datastore. Hal ini dijelaskan di "Latar belakang" bagian.

Anda akan mempelajari cara

  • Menggunakan Cloud NDB (jika Anda belum terbiasa dengannya)
  • Bermigrasi dari Cloud NDB ke Cloud Datastore
  • Melakukan migrasi aplikasi Anda lebih lanjut ke Python 3

Yang Anda butuhkan

  • Project Google Cloud Platform dengan akun penagihan GCP yang aktif
  • Keterampilan Python dasar
  • Pengetahuan perintah Linux dasar yang berfungsi
  • Pengetahuan dasar tentang mengembangkan dan men-deploy aplikasi App Engine
  • Aplikasi App Engine Modul 2 2.x atau 3.x yang berfungsi.

Survei

Bagaimana Anda akan menggunakan codelab ini?

Hanya membacanya Membacanya dan menyelesaikan latihan

2. Latar belakang

Meskipun Cloud NDB adalah solusi Datastore yang bagus untuk developer App Engine lama dan membantu transisi ke Python 3, ini bukan satu-satunya cara developer App Engine dapat mengakses Datastore. Saat Datastore App Engine menjadi produknya sendiri pada tahun 2013, Google Cloud Datastore, library klien baru telah dibuat sehingga semua pengguna dapat menggunakan Datastore.

Developer Python 3 App Engine dan non-App Engine diarahkan untuk menggunakan Cloud Datastore (bukan Cloud NDB). Developer Python 2 App Engine dianjurkan untuk bermigrasi dari ndb ke Cloud NDB dan melakukan port ke Python 3 dari sana, tetapi mereka juga dapat memilih untuk bermigrasi lebih lanjut ke Cloud Datastore. Ini adalah keputusan logis terutama bagi developer yang sudah memiliki kode yang menggunakan Cloud Datastore, seperti yang baru saja disebutkan, dan ingin membuat library bersama di semua aplikasi mereka. Penggunaan ulang kode merupakan praktik terbaik sebagaimana konsistensi kode, dan keduanya berkontribusi pada pengurangan biaya pemeliharaan secara keseluruhan, seperti yang diringkas di sini:

Migrasi dari Cloud NDB ke Cloud Datastore

  • Memungkinkan developer berfokus pada satu codebase untuk akses Datastore
  • Menghindari pemeliharaan beberapa kode menggunakan Cloud NDB dan kode lainnya menggunakan Cloud Datastore
  • Memberikan konsistensi yang lebih baik pada codebase dan penggunaan kembali kode yang lebih baik
  • Memungkinkan penggunaan library umum/bersama, yang berkontribusi pada biaya pemeliharaan yang lebih rendah secara keseluruhan

Migrasi ini menampilkan langkah-langkah utama berikut:

  1. Penyiapan/Prakerja
  2. Mengganti Cloud NDB dengan library klien Cloud Datastore
  3. Update 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

Jika Anda telah menyelesaikan codelab Modul 2, sebaiknya gunakan kembali project (dan kode) yang sama. 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 adalah memiliki aplikasi contoh Modul 2 yang berfungsi. Gunakan solusi Anda jika telah menyelesaikan tutorial tersebut. Anda dapat menyelesaikannya sekarang (link di atas), atau jika Anda ingin melewatinya, salin repositori Modul 2 (link di bawah).

Baik Anda menggunakan kode Anda atau kode kami, kode Modul 2 adalah tempat kita akan memulai. Codelab Modul 3 ini akan memandu Anda melalui setiap langkah, dan jika sudah selesai, codelab ini akan menyerupai kode pada titik FINISH. Ada versi Python 2 dan 3 dari tutorial ini, jadi ambil repo kode yang benar di bawah ini.

Python 2

File awal (START) di direktori Python 2 Modul 2 (kode Anda atau kode kami) akan terlihat seperti ini:

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

Jika sudah menyelesaikan tutorial Modul 2, Anda juga akan memiliki folder lib dengan Flask dan dependensinya. Jika Anda tidak memiliki folder lib, buat dengan perintah pip install -t lib -r requirements.txt agar kita dapat men-deploy aplikasi pengukuran dasar ini di langkah berikutnya. Jika Anda memiliki Python 2 maupun 3, sebaiknya gunakan pip2 bukan pip untuk menghindari kebingungan dengan Python 3.

Python 3

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

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

lib atau appengine_config.py tidak digunakan untuk Python 3.

3. Deploy (ulang) aplikasi Modul 2

Langkah prakerja yang tersisa untuk dijalankan sekarang:

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

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

4. Mengganti Cloud NDB dengan library klien Cloud Datastore

Satu-satunya perubahan konfigurasi adalah pertukaran paket minor di file requirements.txt Anda.

1. Mengupdate requirements.txt

Setelah menyelesaikan Modul 2, file requirements.txt Anda akan terlihat seperti ini:

  • SEBELUM (Python 2 dan 3):
Flask==1.1.2
google-cloud-ndb==1.7.1

Update requirements.txt dengan mengganti library Cloud NDB (google-cloud-ndb) dengan library Cloud Datastore versi terbaru (google-cloud-datastore), sehingga entri untuk Flask tetap utuh, mengingat versi final Cloud Datastore yang kompatibel dengan Python 2 adalah 1.15.3:

  • SETELAH (Python 2):
Flask==1.1.2
google-cloud-datastore==1.15.3
  • SETELAH (Python 3):
Flask==1.1.2
google-cloud-datastore==2.1.0

Perlu diingat bahwa repo dikelola lebih sering daripada tutorial ini, sehingga mungkin saja file requirements.txt mencerminkan versi yang lebih baru. Sebaiknya gunakan versi terbaru dari setiap library, tetapi jika tidak berfungsi, Anda dapat melakukan roll back ke rilis yang lebih lama. Nomor versi di atas adalah yang terbaru saat codelab ini terakhir diperbarui.

2. File konfigurasi lainnya

File konfigurasi lainnya, app.yaml dan appengine_config.py, tidak akan berubah dari langkah migrasi sebelumnya:

  • app.yaml harus (masih) mereferensikan paket grpcio dan setuptools dari paket pihak ketiga.
  • appengine_config.py harus (masih) mengarahkan pkg_resources dan google.appengine.ext.vendor ke resource pihak ketiga di lib.

Sekarang mari kita beralih ke file aplikasi.

5. Memperbarui file aplikasi

Tidak ada perubahan pada template/index.html, tetapi ada beberapa update untuk main.py.

1. Impor

Kode awal untuk bagian impor akan terlihat seperti berikut:

  • SEBELUM:
from flask import Flask, render_template, request
from google.cloud import ndb

Ganti impor google.cloud.ndb dengan impor untuk Cloud Datastore: google.cloud.datastore. Karena library klien Datastore tidak mendukung pembuatan otomatis kolom stempel waktu di Entity, impor juga modul datetime library standar untuk membuatnya secara manual. Berdasarkan konvensi, impor library standar melebihi impor paket pihak ketiga. Setelah selesai melakukan perubahan ini, tampilannya akan terlihat seperti ini:

  • SETELAH:
from datetime import datetime
from flask import Flask, render_template, request
from google.cloud import datastore

2. Inisialisasi dan model data

Setelah menginisialisasi Flask, aplikasi contoh Modul 2 akan membuat class model data NDB dan lokasi kolomnya sebagai berikut:

  • SEBELUM:
app = Flask(__name__)
ds_client = ndb.Client()

class Visit(ndb.Model):
    visitor   = ndb.StringProperty()
    timestamp = ndb.DateTimeProperty(auto_now_add=True)

Library Cloud Datastore tidak memiliki class seperti itu, jadi hapus deklarasi class Visit. Anda masih memerlukan klien untuk berbicara dengan Datastore, jadi ubah ndb.Client() menjadi datastore.Client(). Library Datastore lebih "fleksibel," memungkinkan Anda membuat Entity tanpa "mendeklarasikan sebelumnya" strukturnya seperti NDB. Setelah diperbarui, bagian main.py ini akan terlihat seperti:

  • SETELAH:
app = Flask(__name__)
ds_client = datastore.Client()

3. Akses Datastore

Untuk bermigrasi ke Cloud Datastore, Anda harus mengubah cara Anda membuat, menyimpan, dan membuat kueri permintaan Datastore (di tingkat pengguna). Untuk aplikasi Anda, tingkat kesulitan migrasi ini bergantung pada seberapa rumit kode Datastore Anda. Dalam aplikasi contoh, kami mencoba membuat update sesederhana mungkin. Berikut adalah kode awal kita:

  • SEBELUM:
def store_visit(remote_addr, user_agent):
    with ds_client.context():
        Visit(visitor='{}: {}'.format(remote_addr, user_agent)).put()

def fetch_visits(limit):
    with ds_client.context():
        return (v.to_dict() for v in Visit.query().order(
                -Visit.timestamp).fetch_page(limit)[0])

Dengan Cloud Datastore, buat entity generik, yang mengidentifikasi objek yang dikelompokkan dalam Entity Anda dengan "kunci". Buat kumpulan data dengan objek JSON (Python dict) dari key-value pair, lalu tulis ke Datastore dengan put() yang diharapkan. Pembuatan kueri serupa, tetapi lebih mudah dengan Datastore. Di sini Anda dapat melihat perbedaan kode Datastore yang setara:

  • SETELAH:
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)

Update isi fungsi untuk store_visit() dan fetch_visits() seperti di atas, sehingga tanda tangannya tetap identik dengan versi sebelumnya. Tidak ada perubahan sama sekali pada pengendali utama root(). Setelah menyelesaikan perubahan ini, aplikasi Anda kini dilengkapi untuk menggunakan Cloud Datastore dan siap diuji.

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 folder repo Modul 3:

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:

aplikasi visitme

Selamat, Anda telah menyelesaikan codelab Modul 3 ini. Sekarang Anda tahu bahwa Anda dapat menggunakan library klien Cloud NDB dan Cloud Datastore untuk mengakses Datastore. Dengan bermigrasi ke platform yang kedua, Anda kini bisa mendapatkan manfaatnya adalah library bersama, penggunaan ulang kode dan kode umum untuk konsistensi dan mengurangi biaya pemeliharaan.

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.

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 Datastore 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

Dari sini, Anda dapat mempelajari modul migrasi berikutnya:

  • Bonus Modul 3: Lanjutkan ke bagian bonus untuk mempelajari cara melakukan port ke Python 3 dan runtime App Engine generasi berikutnya.
  • 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
    • Memungkinkan Anda tetap berada di Python 2
  • Modul 5: Melakukan Migrasi ke Cloud Run dengan Cloud Buildpacks
    • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Cloud Buildpacks
    • Tidak perlu mengetahui apa pun tentang Docker, container, atau Dockerfile
    • Anda harus sudah memigrasikan aplikasi ke Python 3
  • Modul 6: Melakukan Migrasi ke Cloud Firestore
    • Melakukan migrasi ke Cloud Firestore untuk mengakses fitur Firebase
    • Meskipun Cloud Firestore mendukung Python 2, codelab ini hanya tersedia di Python 3.

7. BONUS: Melakukan migrasi ke Python 3

Untuk mengakses runtime dan fitur App Engine terbaru, sebaiknya lakukan migrasi ke Python 3. Dalam aplikasi contoh kami, Datastore adalah satu-satunya layanan bawaan yang kami gunakan, dan karena kami telah bermigrasi dari ndb ke Cloud NDB, kini kami dapat melakukan porting ke runtime Python 3 App Engine.

Ringkasan

Meskipun melakukan porting ke Python 3 tidak berada dalam cakupan tutorial Google Cloud, bagian codelab ini memberikan gambaran kepada developer tentang perbedaan runtime App Engine Python 3. Salah satu fitur luar biasa dari runtime generasi berikutnya adalah akses yang disederhanakan ke paket pihak ketiga: Tidak perlu menentukan paket bawaan di app.yaml atau persyaratan untuk menyalin atau mengupload library non bawaan; secara implisit terinstal agar tidak tercantum di requirements.txt.

Karena sampel kami sangat mendasar dan Cloud Datastore kompatibel dengan Python 2-3, tidak ada kode aplikasi yang perlu ditransfer secara eksplisit ke 3.x: Aplikasi berjalan pada 2.x dan 3.x tanpa diubah, yang berarti satu-satunya perubahan yang diperlukan ada dalam konfigurasi dalam kasus ini:

  1. Sederhanakan app.yaml untuk mereferensikan Python 3 dan menghapus referensi ke paket library pihak ketiga.
  2. Hapus appengine_config.py dan folder lib karena sudah tidak diperlukan lagi.

File aplikasi main.py dan templates/index.html tetap tidak berubah.

Mengupdate requirements.txt

Versi akhir Cloud Datastore yang mendukung Python 2 adalah 1.15.3. Update requirements.txt dengan versi terbaru untuk Python 3 (mungkin sudah lebih baru sekarang). Ketika tutorial ini ditulis, versi terbaru adalah 2.1.0, jadi edit baris tersebut agar terlihat seperti ini (atau apa pun versi terbarunya):

google-cloud-datastore==2.1.0

Sederhanakan app.yaml

SEBELUM:

Satu-satunya perubahan nyata untuk aplikasi contoh ini adalah mempersingkat app.yaml secara signifikan. Sebagai pengingat, berikut yang kita miliki di app.yaml pada akhir Modul 3:

runtime: python27
threadsafe: yes
api_version: 1

handlers:
- url: /.*
  script: main.app

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0

SETELAH:

Pada Python 3, perintah threadsafe, api_version, dan libraries tidak digunakan lagi. Semua aplikasi dianggap threadsafe dan api_version tidak digunakan di Python 3. Tidak ada lagi paket pihak ketiga bawaan yang sudah terpasang di layanan App Engine, sehingga libraries juga tidak digunakan lagi. Lihat dokumentasi perubahan pada app.yaml untuk informasi selengkapnya tentang perubahan ini. Oleh karena itu, Anda harus menghapus ketiganya dari app.yaml dan memperbarui ke versi Python 3 yang didukung (lihat di bawah).

Opsional: Penggunaan perintah handlers

Selain itu, perintah handlers, yang mengarahkan traffic pada aplikasi App Engine juga tidak digunakan lagi. Karena runtime generasi berikutnya mengharapkan framework web untuk mengelola perutean aplikasi, semua "skrip pengendali" harus diubah menjadi "auto". Dengan menggabungkan perubahan-perubahan dari atas, akan dihasilkan app.yaml ini:

runtime: python38

handlers:
- url: /.*
  script: auto

Pelajari script: auto lebih lanjut dari halaman referensi app.yaml.

Menghapus perintah handlers

Karena handlers tidak digunakan lagi, Anda juga dapat menghapus seluruh bagian, sehingga menyisakan app.yaml baris tunggal:

runtime: python38

Secara default, tindakan ini akan meluncurkan server web Gunicorn WSGI yang tersedia untuk semua aplikasi. Jika Anda terbiasa dengan gunicorn, ini adalah perintah yang dijalankan ketika dimulai secara default dengan barebones app.yaml:

gunicorn main:app --workers 2 -c /config/gunicorn.py

Opsional: Penggunaan perintah entrypoint

Namun, jika aplikasi Anda memerlukan perintah start-up spesifik, yang dapat ditentukan dengan perintah entrypoint, sehingga menghasilkan app.yaml yang terlihat seperti ini:

runtime: python38
entrypoint: python main.py

Contoh ini secara khusus meminta server pengembangan Flask untuk digunakan, bukan gunicorn. Kode yang memulai server pengembangan juga harus ditambahkan ke aplikasi Anda untuk diluncurkan pada antarmuka 0.0.0.0 pada port 8080 dengan menambahkan bagian kecil ini ke bagian bawah main.py:

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080, debug=True)

Pelajari entrypoint lebih lanjut dari halaman referensi app.yaml. Lebih banyak contoh dan praktik terbaik dapat ditemukan di dokumen startup lingkungan standar App Engine serta dokumen startup lingkungan fleksibel App Engine.

Hapus appengine_config.py dan lib

Hapus file appengine_config.py dan folder lib. Saat bermigrasi ke Python 3, App Engine memperoleh dan menginstal paket yang tercantum di requirements.txt.

File konfigurasi appengine_config.py digunakan untuk mengenali library/paket pihak ketiga, baik Anda menyalinnya atau menggunakan yang sudah tersedia di server App Engine (bawaan). Saat beralih ke Python 3, ringkasan perubahan besar adalah:

  1. Tidak ada paket library pihak ketiga yang disalin (tercantum di requirements.txt)
  2. Tidak ada pip install dalam folder lib, artinya tidak ada periode folder lib
  3. Tidak ada pencantuman library pihak ketiga bawaan di app.yaml
  4. Tidak perlu merujuk aplikasi ke library pihak ketiga, sehingga tidak ada file appengine_config.py

Anda hanya perlu mencantumkan semua library pihak ketiga yang diperlukan di requirements.txt.

Deploy aplikasi

Deploy ulang aplikasi Anda untuk memastikannya berfungsi. Anda juga dapat mengonfirmasi seberapa dekat solusi Anda dengan kode Python 3 contoh Modul 3. Untuk memvisualisasikan perbedaan dengan Python 2, bandingkan kode dengan versi Python 2.

Selamat, Anda telah menyelesaikan langkah bonus di Modul 3! Buka dokumentasi tentang menyiapkan file konfigurasi untuk runtime Python 3. Terakhir, tinjau ringkasan sebelumnya di atas untuk mengetahui langkah selanjutnya dan pembersihan.

Menyiapkan aplikasi Anda

Saat tiba waktunya untuk memigrasikan aplikasi Anda, Anda harus mentransfer main.py Anda dan file aplikasi lain ke 3.x, jadi praktik terbaik adalah mencoba sebaik mungkin untuk membuat aplikasi 2.x Anda memiliki "kompatibilitas maju" setinggi mungkin.

Ada banyak resource online yang dapat membantu Anda mencapainya, namun beberapa tips penting:

  1. Pastikan semua dependensi aplikasi sepenuhnya kompatibel dengan versi 3.x
  2. Pastikan aplikasi Anda setidaknya bisa dijalankan minimal pada versi 2.6 (sebaiknya 2.7)
  3. Pastikan aplikasi lulus seluruh rangkaian pengujian (dan cakupan minimum 80%)
  4. Gunakan library kompatibilitas seperti six, Future, dan/atau Modernize
  5. Mendidik diri sendiri tentang perbedaan inkompatibilitas mundur 2.x vs. 3.x
  6. I/O apa pun kemungkinan besar akan menyebabkan inkompatibilitas string Unicode vs. byte

Aplikasi sampel dirancang dengan mempertimbangkan semua hal ini, itulah mengapa aplikasi langsung dapat dijalankan pada versi 2.x dan 3.x sehingga kita dapat berfokus untuk menunjukkan apa yang perlu diubah agar dapat menggunakan platform generasi berikutnya.

8. 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:

Referensi migrasi

Link ke folder repo untuk Modul 2 (START) dan Modul 3 (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 2

kode

kode

Modul 3

kode

kode

Resource App Engine

Berikut adalah resource tambahan terkait migrasi khusus ini: