Bermigrasi ke Cloud NDB

Lokasi App Engine

App Engine bersifat regional. Artinya, infrastruktur yang menjalankan aplikasi Anda terletak di region tertentu, dan Google mengelolanya sehingga aplikasi Anda tersedia secara redundan di semua zona dalam region tersebut.

Memenuhi persyaratan latensi, ketersediaan, atau ketahanan adalah faktor utama untuk memilih region tempat aplikasi dijalankan. Secara umum, Anda dapat memilih region yang paling dekat dengan pengguna aplikasi Anda, tetapi Anda harus mempertimbangkan lokasi tempat App Engine tersedia serta lokasi dari produk dan layanan Google Cloud lainnya yang digunakan aplikasi Anda. Penggunaan layanan di beberapa lokasi dapat memengaruhi latensi dan harga aplikasi.

Anda tidak dapat mengubah region aplikasi setelah menyetelnya.

Catatan: Dua lokasi, yang disebut europe-west dan us-central dalam perintah App Engine dan di konsol Google Cloud, masing-masing disebut europe-west1 dan us-central1, di bagian lain dalam dokumentasi Google.

Jika sudah membuat aplikasi App Engine, Anda dapat melihat region-nya dengan melakukan salah satu tindakan berikut:

• Jalankan perintah gcloud app describe.

• Buka Dasbor App Engine di konsol Google Cloud. Region muncul di dekat bagian atas halaman.

Oke

Cloud NDB adalah library klien untuk Python yang menggantikan App Engine NDB. App Engine NDB memungkinkan aplikasi Python 2 menyimpan dan membuat kueri data di database Datastore. Cloud NDB memungkinkan aplikasi Python 2 dan Python 3 untuk menyimpan dan melakukan kueri data dalam database yang sama. Namun, produk yang mengelola database tersebut telah berubah dari Datastore menjadi Firestore dalam mode Datastore. Meskipun library Cloud NDB dapat mengakses data apa pun yang dibuat dengan App Engine NDB, beberapa jenis data terstruktur yang disimpan menggunakan Cloud NDB tidak dapat diakses dengan App Engine NDB. Oleh karena itu, migrasi ke Cloud NDB harus dianggap tidak dapat dibatalkan.

Sebaiknya lakukan migrasi ke Cloud NDB sebelum mengupgrade aplikasi ke Python 3. Pendekatan inkremental untuk migrasi ini memungkinkan Anda mempertahankan aplikasi yang berfungsi dan dapat diuji selama proses migrasi.

Cloud NDB dimaksudkan untuk menggantikan fitur di App Engine NDB, sehingga tidak akan mendukung fitur baru Firestore dalam mode Datastore. Sebaiknya aplikasi Python 3 yang baru menggunakan library klien mode Datastore, bukan Cloud NDB.

Untuk mengetahui informasi selengkapnya tentang Cloud NDB, lihat halaman berikut di GitHub:

• Dokumentasi Cloud NDB

• Kode sumber Cloud NDB

Perbandingan App Engine NDB dan Cloud NDB

Kesamaan:

• Cloud NDB mendukung hampir semua fitur yang didukung oleh App Engine NDB dengan hanya sedikit perbedaan dalam sintaksis metodenya.

Perbedaan:

• App Engine NDB API yang mengandalkan layanan khusus runtime App Engine Python 2.7 telah diupdate atau dihapus dari Cloud NDB.

• Fitur baru di Python 3 dan Django telah menghilangkan kebutuhan akan google.appengine.ext.ndb.django_middleware. Sebagai gantinya, Anda dapat dengan mudah menulis middleware Anda sendiri hanya dengan beberapa baris kode.

• App Engine NDB mengharuskan aplikasi dan database Datastore berada di project Google Cloud yang sama, dengan App Engine memberikan kredensial secara otomatis. Cloud NDB dapat mengakses database mode Datastore dalam project apa pun, selama Anda mengautentikasi klien dengan benar. Hal ini sesuai dengan Google Cloud API dan library klien lainnya.

• Cloud NDB tidak menggunakan layanan Memcache App Engine untuk menyimpan data dalam cache.

  Sebagai gantinya, Cloud NDB dapat menyimpan data dalam cache di penyimpanan data dalam memori Redis yang dikelola oleh Memorystore, Redis Labs, atau sistem lainnya. Meskipun saat ini hanya penyimpanan data Redis yang didukung, Cloud NDB memiliki penyimpanan cache umum dan ditentukan dalam antarmuka GlobalCache abstrak, yang dapat mendukung implementasi konkret tambahan.

  Untuk mengakses Memorystore for Redis, aplikasi Anda perlu menggunakan Akses VPC Serveless.

  Memorystore for Redis maupun Serverless Access tidak menyediakan paket gratis, dan produk ini mungkin tidak tersedia di region aplikasi Anda. Lihat Sebelum memulai migrasi untuk informasi selengkapnya.

Daftar lengkap perbedaan tersedia di catatan migrasi untuk project GitHub Cloud NDB.

Contoh kode:

• Operasi database dasar menggunakan App Engine NDB

• Operasi database dasar menggunakan Cloud NDB

Sebelum mulai memigrasikan

Sebelum mulai bermigrasi:

1. Jika Anda belum melakukannya, siapkan lingkungan pengembangan Python Anda untuk menggunakan versi Python yang kompatibel dengan Google Cloud, dan instal alat pengujian untuk membuat Python yang terisolasi yang berbeda.

2. Tentukan apakah Anda perlu menyimpan data dalam cache.

3. Jika Anda perlu menyimpan data dalam cache, pastikan region aplikasi Anda didukung oleh Akses VPC Serverless dan Memorystore for Redis.

4. Memahami izin mode Datastore.

Menentukan apakah Anda perlu menyimpan data dalam cache

Jika aplikasi Anda perlu menyimpan data dalam cache, perlu diketahui bahwa Memorystore for Redis dan Akses VPC Serverless tidak memiliki paket gratis dan tidak mendukung semua region Google Cloud.

Secara umum:

• Jika aplikasi Anda sering membaca data yang sama, penyimpanan dalam cache dapat mengurangi latensi.

• Makin banyak permintaan yang dilayani aplikasi Anda, makin besar dampak yang dapat ditimbulkan oleh penyimpanan dalam cache.

Untuk mengetahui seberapa banyak Anda saat ini mengandalkan data yang disimpan dalam cache, lihat dasbor Memcache untuk melihat rasio cache yang ditemukan hingga yang tidak ditemukan. Jika rasionya tinggi, penggunaan cache data kemungkinan akan berdampak besar dalam mengurangi latensi aplikasi.

Buka Memcache App Engine

Untuk mengetahui informasi tentang harga, lihat Harga Memorystore dan Harga Akses VPC Serverless.

Mengonfirmasi region aplikasi Anda

Jika Anda perlu menyimpan data dalam cache, pastikan region aplikasi Anda didukung oleh Memorystore for Redis dan Akses VPC Serverless:

1. Lihat region aplikasi Anda, yang muncul di dekat bagian atas Dasbor App Engine di Konsol Google Cloud.

   Buka App Engine

   Region ini muncul di dekat bagian atas halaman, tepat di bawah URL aplikasi Anda.

2. Pastikan aplikasi Anda berada di salah satu region yang didukung oleh Akses VPC Serverless.

3. Pastikan bahwa aplikasi Anda berada di salah satu region yang didukung oleh Memorystore for Redis dengan membuka halaman Buat konektor dan melihat region dalam daftar Region.

   Buka Akses VPC Serverless

Jika aplikasi Anda tidak berada di region yang didukung oleh Memorystore for Redis dan Akses VPC Serverless:

1. Buat project Google Cloud.

2. Buat aplikasi App Engine baru di project dan pilih region yang didukung.

3. Buat layanan Google Cloud yang digunakan aplikasi Anda di project baru.

   Atau, Anda dapat mengupdate aplikasi untuk menggunakan layanan yang ada di project lama, tetapi harga dan penggunaan resource mungkin berbeda jika Anda menggunakan layanan di project dan region yang berbeda. Baca dokumentasi setiap layanan untuk mengetahui informasi selengkapnya.

4. Deploy aplikasi Anda ke project baru.

Memahami izin mode Datastore

Setiap interaksi dengan layanan Google Cloud perlu diotorisasi. Misalnya, untuk menyimpan atau membuat kueri data dalam database mode Datastore, aplikasi Anda harus menyediakan kredensial dari akun yang diotorisasi untuk mengakses database.

Secara default, aplikasi Anda memberikan kredensial akun layanan default App Engine, yang diberi otorisasi untuk mengakses database dalam project yang sama dengan aplikasi Anda.

Anda harus menggunakan teknik autentikasi alternatif yang secara eksplisit memberikan kredensial jika salah satu kondisi berikut terpenuhi:

• Aplikasi Anda dan database mode Datastore berada di project Google Cloud yang berbeda.

• Anda telah mengubah peran yang ditetapkan ke akun layanan App Engine default.

Untuk mengetahui informasi tentang teknik autentikasi alternatif, lihat Menyiapkan Autentikasi untuk Aplikasi Produksi Server ke Server.

Ringkasan proses migrasi

Untuk bermigrasi ke Cloud NDB:

1. Update aplikasi Python Anda:

   1. Instal library klien Cloud NDB.

   2. Update pernyataan import untuk mengimpor modul dari Cloud NDB.

   3. Tambahkan kode yang membuat klien Cloud NDB. Klien dapat membaca variabel lingkungan aplikasi Anda dan menggunakan data untuk melakukan autentikasi dengan mode Datastore.

   4. Tambahkan kode yang menggunakan konteks runtime klien untuk menjaga penyimpanan dalam cache dan transaksi tetap terpisah antara rangkaian pesan.

   5. Hapus atau perbarui kode yang menggunakan metode dan properti yang tidak lagi didukung.

2. Aktifkan penyimpanan dalam cache.

3. Uji pembaruan Anda.

4. Deploy aplikasi Anda ke App Engine.

   Seperti halnya perubahan yang Anda lakukan pada aplikasi, pertimbangkan untuk menggunakan pemisahan traffic untuk meningkatkan traffic secara perlahan. Pantau aplikasi dengan cermat untuk menemukan masalah database sebelum mengarahkan lebih banyak traffic ke aplikasi yang telah diupdate.

Mengupdate aplikasi Python Anda

Menginstal library Cloud NDB untuk aplikasi Python

Untuk menginstal library klien Cloud NDB di aplikasi App Engine Python Anda:

1. Perbarui file app.yaml. Ikuti petunjuk untuk versi Python Anda:

   Python 2

   Untuk aplikasi Python 2, tambahkan versi terbaru library grpcio dan setuptools.

   Berikut adalah contoh file app.yaml:

   runtime: python27
   threadsafe: yes
   api_version: 1
   
   libraries:
   - name: grpcio
     version: latest
   - name: setuptools
     version: latest
   

   Python 3

   Untuk aplikasi Python 3, tentukan elemen runtime dengan versi Python 3 yang didukung, dan hapus baris yang tidak diperlukan. Misalnya, file app.yaml Anda mungkin terlihat seperti berikut:

   runtime: python310 # or another support version
   

   Runtime Python 3 menginstal library secara otomatis, sehingga Anda tidak perlu menentukan library bawaan dari runtime Python 2 sebelumnya. Jika aplikasi Python 3 Anda menggunakan layanan paket lama lainnya saat bermigrasi, biarkan file app.yaml apa adanya.

2. Update file requirements.txt. Ikuti petunjuk untuk versi python Anda:

   Python 2

   Tambahkan Library Klien Cloud untuk Cloud NDB ke daftar dependensi dalam file requirements.txt.

   google-cloud-ndb
   

   Lalu, jalankan pip install -t lib -r requirements.txt untuk memperbarui daftar library yang tersedia untuk aplikasi Anda.

   Python 3

   Tambahkan Library Klien Cloud untuk Cloud NDB ke daftar dependensi dalam file requirements.txt.

   google-cloud-ndb
   

   App Engine otomatis menginstal dependensi ini selama deployment aplikasi di runtime Python 3, jadi hapus folder lib jika ada.

3. Untuk aplikasi Python 2, jika aplikasi Anda menggunakan library bawaan atau yang salinan yang ditentukan dalam direktori lib, Anda harus menentukan jalur tersebut di file appengine_config.py:

   import pkg_resources
   from google.appengine.ext import vendor
   
   # Set PATH to your libraries folder.
   PATH = 'lib'
   # Add libraries installed in the PATH folder.
   vendor.add(PATH)
   # Add libraries to pkg_resources working set to find the distribution.
   pkg_resources.working_set.add_entry(PATH)
   

   Pastikan Anda menggunakan modul pkg_resources, yang memastikan bahwa aplikasi Anda menggunakan distribusi library klien yang benar.

   File appengine_config.py dalam contoh sebelumnya mengasumsikan bahwa folder lib berada di direktori kerja saat ini. Jika Anda tidak dapat menjamin bahwa lib akan selalu berada di direktori kerja saat ini, tentukan jalur lengkap ke folder lib. Contoh:

   import os
   path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')

   Saat Anda men-deploy aplikasi, App Engine mengupload semua library di direktori yang Anda tentukan dalam file appengine_config.py.

Memperbarui pernyataan import

Lokasi modul NDB telah dipindahkan ke google.cloud.ndb. Perbarui pernyataan import aplikasi Anda seperti yang ditunjukkan dalam tabel berikut:

Hapus	Ganti dengan
from google.appengine.ext import ndb	from google.cloud import ndb

Membuat Klien Cloud NDB

Seperti library klien lainnya yang didasarkan pada Google Cloud API, langkah pertama dalam menggunakan Cloud NDB adalah membuat objek Client. Klien berisi kredensial dan data lain yang diperlukan untuk terhubung ke mode Datastore. Contoh:

from google.cloud import ndb

client = ndb.Client()

Dalam skenario otorisasi default yang dijelaskan sebelumnya, klien Cloud NDB berisi kredensial dari akun layanan default App Engine, yang diberi otorisasi untuk berinteraksi dengan mode Datastore. Jika Anda tidak menangani skenario default ini, lihat Kredensial Default Aplikasi (ADC) untuk mengetahui informasi tentang cara memberikan kredensial.

Menggunakan konteks runtime klien

Selain menyediakan kredensial yang diperlukan untuk berinteraksi dengan mode Datastore, klien Cloud NDB berisi metode context() yang menampilkan konteks runtime. Konteks runtime mengisolasi permintaan cache dan transaksi dari interaksi mode Datastore serentak lainnya.

Semua interaksi dengan mode Datastore harus terjadi dalam konteks runtime NDB. Karena pembuatan definisi model tidak akan berinteraksi dengan mode Datastore, Anda dapat menentukan class model sebelum membuat klien Cloud NDB dan mengambil konteks runtime, lalu menggunakan konteks runtime di pengendali permintaan untuk mendapatkan data dari.

Contoh:

from google.cloud import ndb


class Book(ndb.Model):
    title = ndb.StringProperty()


client = ndb.Client()


def list_books():
    with client.context():
        books = Book.query()
        for book in books:
            print(book.to_dict())

Aplikasi multi-thread

Konteks runtime yang ditampilkan oleh klien Cloud NDB hanya berlaku untuk satu rangkaian pesan. Jika aplikasi Anda menggunakan beberapa thread untuk satu permintaan, Anda harus mengambil konteks runtime terpisah untuk setiap thread yang akan menggunakan library Cloud NDB.

Menggunakan konteks runtime dengan framework WSGI

Jika aplikasi web Anda menggunakan framework WSGI, Anda dapat otomatis membuat konteks runtime baru untuk setiap permintaan dengan membuat objek middleware yang mengambil konteks runtime, lalu menggabungkan aplikasi dalam objek middleware.

Pada contoh penggunaan middleware dengan Flask berikut:

• Metode middleware membuat objek middleware WSGI dalam konteks runtime klien NDB.

• Aplikasi Flask digabungkan dalam objek middleware.

• Flask kemudian akan meneruskan setiap permintaan melalui objek middleware, yang mengambil konteks runtime NDB baru untuk setiap permintaan.

from flask import Flask

from google.cloud import ndb


client = ndb.Client()


def ndb_wsgi_middleware(wsgi_app):
    def middleware(environ, start_response):
        with client.context():
            return wsgi_app(environ, start_response)

    return middleware


app = Flask(__name__)
app.wsgi_app = ndb_wsgi_middleware(app.wsgi_app)  # Wrap the app in middleware.


class Book(ndb.Model):
    title = ndb.StringProperty()


@app.route("/")
def list_books():
    books = Book.query()
    return str([book.to_dict() for book in books])

Menggunakan konteks runtime dengan Django

Middleware Django yang disediakan oleh library App Engine NDB tidak didukung oleh library Cloud NDB. Jika Anda menggunakan middleware (google.appengine.ext.ndb.django_middleware) ini di aplikasi, ikuti langkah-langkah berikut untuk mengupdate aplikasi:

1. Gunakan sistem middleware Django untuk membuat konteks runtime baru untuk setiap permintaan.

   Dalam contoh berikut:

   • Metode ndb_django_middleware membuat klien Cloud NDB.

   • Metode middleware membuat objek middleware dalam konteks runtime klien NDB.

   from google.cloud import ndb
   
   
   # Once this middleware is activated in Django settings, NDB calls inside Django
   # views will be executed in context, with a separate context for each request.
   def ndb_django_middleware(get_response):
       client = ndb.Client()
   
       def middleware(request):
           with client.context():
               return get_response(request)
   
       return middleware
   
   

2. Di file settings.py Django, perbarui setelan MIDDLEWARE agar mencantumkan middleware baru yang Anda buat, bukan google.appengine.ext.ndb.NdbDjangoMiddleware.

Django kini akan meneruskan setiap permintaan melalui objek middleware yang Anda cantumkan dalam setelan MIDDLEWARE, dan objek ini akan mengambil konteks runtime NDB baru untuk setiap permintaan.

Memperbarui kode untuk NDB API yang dihapus atau diubah

NDB API yang mengandalkan API dan layanan khusus App Engine telah diupdate atau dihapus dari library Cloud NDB.

Anda harus mengupdate kode jika menggunakan salah satu NDB API berikut:

• Properti google.appengine.ext.ndb.Model dan model
• google.appengine.ext.ndb.Key
• google.appengine.ext.ndb.query.QueryOptions dan PropertyOrder
• google.appengine.ext.ndb.utils
• google.appengine.api.namespacemanager
• google.appengine.api.ext.ndb.tasklets
• google.appengine.api.datastore_errors

Model dan Properti model

Metode dari google.appengine.ext.ndb.Model berikut tidak tersedia di library Cloud NDB karena menggunakan API khusus App Engine yang tidak lagi tersedia.

API yang Dihapus	Penggantian
Model.get_indexes dan Model.get_indexes_async	Tidak ada
Model._deserialize dan Model._serialize	Tidak ada
Model.make_connection	Tidak ada

Tabel berikut menjelaskan properti google.appengine.ext.ndb.Model tertentu yang telah berubah di library Cloud NDB:

Properti	Ubah
TextProperty	google.cloud.ndb.TextProperty tidak dapat diindeks. Jika Anda mencoba menetapkan google.cloud.ndb.TextProperty.indexed, NotImplementedError akan dimunculkan.
StringProperty	StringProperty selalu diindeks. Jika Anda mencoba menetapkan google.cloud.ndb.StringProperty.indexed, NotImplementedError akan dimunculkan.
Semua properti dengan argumen name atau kind di konstruktor.	name atau kind harus berupa jenis data str, karena unicode telah diganti dengan str di Python 3.

Class dan metode dalam tabel berikut tidak lagi tersedia karena menggunakan resource khusus App Engine yang tidak lagi tersedia.

API yang Dihapus	Penggantian
google.appengine.ext.ndb.msgprop.MessageProperty dan google.appengine.ext.ndb.msgprop.EnumProperty	Tidak ada Jika Anda mencoba membuat objek ini, NotImplementedError akan dimunculkan.
dari google.appengine.ext.ndb.model.Property: _db_get_value _db_set_value _db_set_compressed_meaning _db_set_uncompressed_meaning __creation_counter_global	Tidak ada Metode ini bergantung pada buffering protokol mode Datastore yang telah berubah.
Model.make_connection	Tidak ada

Kunci

Metode dari google.appengine.ext.ndb.Key berikut tidak tersedia di library Cloud NDB. Metode ini digunakan untuk meneruskan kunci ke dan dari DB Datastore API, yang tidak lagi didukung (DB adalah pendahulu dari App Engine NDB).

API yang Dihapus	Penggantian
Key.from_old_key dan Key.to_old_key	Tidak ada

Selain itu, perhatikan perubahan berikut:

App Engine NDB	Cloud NDB
Jenis dan ID string harus kurang dari 500 byte	Jenis dan ID string harus kurang dari 1.500 byte.
Key.app() menampilkan project ID yang Anda tentukan saat membuat kunci.	Nilai yang ditampilkan oleh google.cloud.ndb.Key.app() dapat berbeda dengan ID asli yang diteruskan ke konstruktor. Hal ini karena ID aplikasi berawalan seperti s~example adalah ID lama dari App Engine. Fungsi tersebut telah diganti dengan project ID yang setara, seperti example.

Kueri

Seperti App Engine NDB, Cloud NDB menyediakan class QueryOptions (google.cloud.ndb.query.QueryOptions) yang memungkinkan Anda menggunakan kembali sekumpulan opsi kueri tertentu, bukan menentukan ulang opsi kueri tersebut untuk setiap kueri. Namun, QueryOptions di Cloud NDB tidak mewarisi dari google.appengine.datastore.datastore_rpc.Configuration sehingga tidak mendukung metode ...datastore_rpc.Configuration.

Selain itu, google.appengine.datastore.datastore_query.Order telah diganti dengan google.cloud.ndb.query.PropertyOrder. Seperti halnya Order, class PropertyOrder memungkinkan Anda menentukan tata urutan di beberapa kueri. Konstruktor PropertyOrder sama dengan konstruktor untuk Order. Hanya nama class-nya yang berubah.

API yang Dihapus	Penggantian
dari google.appengine.datastore.datastore_rpc.Configuration: deadline(value) on_completion(value) read_policy(value) force_writes(value) max_entity_groups_per_rpc(value) max_allocate_ids_keys(value) max_rpc_bytes(value) max_get_keys(value) max_put_entities(value) max_delete_keys(value) Lihat kode sumber untuk deskripsi metode ini.	Tidak ada
google.appengine.ext.ndb.Order Contoh: order=Order(-Account.birthday, Account.name)	google.cloud.ndb.PropertyOrder Contoh: google.cloud.ndb.PropertyOrder(-Account.birthday, Account.name)

Utils

Modul ndb.utils (google.appengine.ext.ndb.utils) tidak lagi tersedia. Sebagian besar metode dalam modul tersebut bersifat internal untuk App Engine NDB, beberapa metode telah dihapus karena perbedaan implementasi pada ndb baru, sementara metode lainnya tidak dipergunakan lagi oleh fitur Python 3 yang baru.

Misalnya, dekorator posisi dalam modul utils lama mendeklarasikan bahwa hanya argumen n pertama dari suatu fungsi atau metode yang dapat posisi. Namun, Python 3 dapat melakukannya menggunakan argumen khusus kata kunci. Yang sebelumnya ditulis sebagai:

@utils.positional(2)
def function1(arg1, arg2, arg3=None, arg4=None)
  pass

Dapat ditulis seperti ini di Python 3:

def function1(arg1, arg2, *, arg3=None, arg4=None)
  pass

Namespace

Namespace memungkinkan aplikasi multitenant untuk menggunakan silo data terpisah bagi setiap tenant sambil tetap menggunakan database mode Datastore yang sama. Artinya, setiap tenant menyimpan data di namespace-nya sendiri.

Daripada menggunakan google.appengine.api.namespacemanager khusus App Engine, Anda perlu menentukan namespace default saat membuat klien Cloud NDB, lalu menggunakan namespace default dengan memanggil Cloud metode NDB dalam konteks runtime klien. Hal ini mengikuti pola yang sama dengan Google Cloud API lainnya yang mendukung namespace.

API yang Dihapus	Penggantian
google.appengine.api.namespace_manager.namespace_manager.set_namespace(str) dan google.appengine.api.namespacemanager.getnamespace()	client=google.cloud.ndb.Client(namespace="my namespace") with client.context() as context: key = ndb.Key("SomeKind", "SomeId") atau key-non-default-namespace=ndb.Key("SomeKind," "AnotherId", namespace="non-default-nspace")
Semua metode google.appengine.api.namespacemanager lainnya	Tidak ada

Tasklet

Tasklet kini dapat menggunakan pernyataan return standar untuk menampilkan hasil, bukan memunculkan pengecualian Return. Contoh:

Library App Engine NDB	Library Cloud NDB
@ndb.tasklet def get_cart(): cart = yield CartItem.query().fetch_async() raise Return(cart)	@ndb.tasklet def get_cart(): cart = yield CartItem.query().fetch_async() return cart

Harap diingat bahwa Anda tetap dapat menampilkan hasil di Cloud NDB dengan memunculkan pengecualian Return, tetapi tindakan itu tidak direkomendasikan.

Selain itu, metode dan subclass Tasklets berikut tidak lagi tersedia, karena kebanyakan perubahan pada cara konteks NDB dibuat dan digunakan di library Cloud NDB.

API yang Dihapus	Penggantian
dari google.appengine.api.ext.ndb.tasklets: add_flow_exception make_context make_default_context set_context	Tidak ada
dari google.appengine.api.ext.ndb.tasklets: QueueFuture ReducedFuture SerialQueueFuture	Tidak ada

Pengecualian

Meskipun modul google.cloud.ndb.exceptions dalam library Cloud NDB berisi banyak pengecualian yang sama dari library App Engine NDB, tidak semua pengecualian lama tersedia di perpustakaan baru. Tabel berikut mencantumkan pengecualian yang tidak lagi tersedia:

API yang Dihapus	Penggantian
dari google.appengine.api.datastore_errors: BadKeyError BadPropertyError CommittedButStillApplying EntityNotFoundError InternalError NeedIndexError QueryNotFoundError ReferencePropertyResolveError Timeout TransactionFailedError TransactionNotFoundError	google.cloud.ndb.exceptions

Mengaktifkan penyimpanan dalam cache data

Cloud NDB dapat menyimpan data dalam cache di penyimpanan data dalam memori Redis yang dikelola oleh Memorystore, Redis Labs, atau sistem lainnya. Panduan ini menjelaskan cara menggunakan Memorystore for Redis untuk menyimpan data dalam cache:

1. Menyiapkan Akses VPC Serverless.

2. Menyiapkan Memorystore for Redis.

3. Menambahkan URL koneksi Redis ke aplikasi Anda.

4. Membuat objek RedisCache.

Menyiapkan Akses VPC Serverless

Aplikasi Anda hanya dapat berkomunikasi dengan Memorystore melalui konektor Akses VPC Serverless. Untuk menyiapkan konektor Akses VPC Serverless:

1. Buat konektor Akses VPC Serverless.

2. Konfigurasikan aplikasi Anda untuk menggunakan konektor.

Menyiapkan Memorystore for Redis

Untuk menyiapkan Memorystore for Redis:

1. Buat instance Redis di Memorystore. Saat Anda membuat instance:

   • Di bagian Region, pilih region yang sama dengan tempat aplikasi App Engine Anda berada.

   • Di bagian Authorized network, pilih jaringan yang sama dengan yang digunakan konektor Akses VPC Serverless Anda.

2. Catat alamat IP dan nomor port instance Redis yang Anda buat. Anda akan menggunakan informasi ini saat mengaktifkan penyimpanan dalam cache data untuk Cloud NDB.

   Pastikan Anda menggunakan perintah gcloud beta untuk men-deploy update aplikasi. Hanya perintah beta yang dapat memperbarui aplikasi untuk menggunakan konektor VPC.

Menambahkan URL koneksi Redis

Anda dapat terhubung ke cache Redis dengan menambahkan variabel lingkungan REDIS_CACHE_URL ke file app.yaml aplikasi Anda. Nilai REDIS_CACHE_URL berbentuk sebagai berikut:

redis://IP address for your instance:port

Misalnya, Anda dapat menambahkan baris berikut ke file app.yaml aplikasi Anda:

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

Membuat dan menggunakan objek cache Redis

Jika sudah menetapkan REDIS_CACHE_URL sebagai variabel lingkungan, Anda dapat membuat objek RedisCache dengan satu baris kode, lalu menggunakan cache dengan meneruskannya ke Client.context() saat menyiapkan konteks runtime:

client = ndb.Client()
global_cache = ndb.RedisCache.from_environment()

with client.context(global_cache=global_cache):
  books = Book.query()
  for book in books:
      print(book.to_dict())

Jika REDIS_CACHE_URL tidak ditetapkan sebagai variabel lingkungan, Anda harus membuat klien Redis dan meneruskan klien ke konstruktor ndb.RedisCache(). Contoh:

global_cache = ndb.RedisCache(redis.StrictRedis(host=IP-address, port=redis_port))

Harap diingat bahwa Anda tidak perlu mendeklarasikan dependensi pada library klien Redis, karena library Cloud NDB sudah bergantung pada library klien Redis.

Lihat aplikasi contoh Memorystore untuk mengetahui contoh pembuatan klien Redis.

Menguji update Anda

Untuk menyiapkan database pengujian dan menjalankan aplikasi secara lokal sebelum men-deploy-nya ke App Engine:

1. Jalankan emulator lokal mode Datastore untuk menyimpan dan mengambil data.

   Pastikan untuk mengikuti petunjuk untuk menetapkan variabel lingkungan agar aplikasi Anda terhubung ke emulator, bukan ke lingkungan mode Datastore production.

   Anda juga dapat mengimpor data ke emulator jika ingin memulai pengujian dengan data yang telah dimuat sebelumnya ke dalam database.

2. Gunakan server pengembangan lokal untuk menjalankan aplikasi Anda.

   Untuk memastikan variabel lingkungan GOOGLE_CLOUD_PROJECT ditetapkan dengan benar selama pengembangan lokal, lakukan inisialisasi dev_appserver menggunakan parameter berikut:

   --application=PROJECT_ID

   Ganti PROJECT_ID dengan project ID Google Cloud Anda. Anda dapat menemukan project ID dengan menjalankan perintah gcloud config list project atau melihat halaman project Anda di Konsol Google Cloud.

Men-deploy aplikasi Anda

Setelah aplikasi Anda berjalan di server pengembangan lokal tanpa error:

1. Uji aplikasi di App Engine.

2. Jika aplikasi berjalan tanpa error, gunakan pemisahan traffic untuk meningkatkan traffic aplikasi yang diupdate secara perlahan. Pantau aplikasi dengan cermat untuk menemukan masalah database sebelum mengarahkan lebih banyak traffic ke aplikasi yang telah diupdate.

Langkah berikutnya

• Untuk tutorial langsung, lihat Codelab Bermigrasi dari App Engine ndb ke Cloud NDB.
• Lihat dokumentasi Cloud NDB untuk mengetahui detail selengkapnya.