Catatan: Python 2.7 telah mencapai akhir dukungan pada 31 Januari 2024. Aplikasi Python 2.7 yang ada akan terus berjalan dan menerima traffic. Namun, App Engine mungkin memblokir deployment ulang aplikasi yang menggunakan runtime setelah tanggal akhir dukungannya. Sebaiknya Anda bermigrasi ke versi Python terbaru yang didukung.

Halaman ini diterjemahkan oleh Cloud Translation API.

Class Model

Catatan: Developer yang membuat aplikasi baru sangat dianjurkan untuk menggunakan Library Klien NDB, yang memiliki beberapa manfaat dibandingkan dengan library klien ini, seperti menyimpan entity dalam cache secara otomatis melalui Memcache API. Jika saat ini Anda menggunakan Library Klien DB versi lama, baca Panduan Migrasi DB ke NDB

Class Model adalah superclass untuk definisi model data.

Model ditentukan dalam modul google.appengine.ext.db.

Pengantar

Aplikasi menentukan model data dengan menentukan class yang membuat subclass Model. Properti model ditentukan menggunakan atribut class dan instance class Property. Contoh:

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

Aplikasi membuat entity data baru dengan membuat instance subclass dari class Model. Properti entity dapat ditetapkan menggunakan atribut instance, atau sebagai argumen kata kunci untuk konstruktor.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

Nama sub-class model digunakan sebagai nama jenis entity Datastore. Datastore mencadangkan semua jenis nama yang dimulai dengan dua garis bawah (__). Sub-class model tidak boleh menggunakan nama tersebut.

Nama atribut digunakan sebagai nama properti yang sesuai pada suatu entity. Atribut instance model yang namanya diawali dengan garis bawah (_) akan diabaikan, sehingga aplikasi Anda dapat menggunakan atribut tersebut untuk menyimpan data pada instance model yang tidak disimpan ke Datastore.

Datastore dan API class model memberlakukan beberapa batasan pada nama properti dan atribut instance model. Lihat Nama Properti yang Tidak Diizinkan untuk deskripsi lengkapnya.

Setiap entity memiliki kunci, ID unik yang mewakili entity. Kunci tersebut dapat menyertakan nama kunci opsional, yaitu string unik di seluruh entity dari jenis tertentu. Jenis dan nama kunci entity dapat digunakan dengan metode Key.from_path() dan Model.get_by_key_name() untuk mengambil entity.

Entity juga dapat memiliki parent entity opsional. Hubungan induk-turunan tersebut membentuk grup entity, yang digunakan untuk mengontrol transaksional dan lokalitas data di Datastore. Aplikasi membuat hubungan induk-turunan antara dua entity dengan meneruskan parent entity ke konstruktor entity turunan, sebagai argumen parent.

Metode Model.get_or_insert() dapat digunakan untuk mengambil entity yang mungkin tidak ada, dan membuatnya di Datastore jika diperlukan:

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

Catatan: Instance model tidak memiliki entity yang sesuai dalam Datastore kecuali dibuatkan (put) untuk pertama kalinya, baik secara eksplisit maupun melalui Model.get_or_insert()

Untuk membuat dict yang merupakan salinan data instance model, gunakan fungsi db.to_dict.

Konstruktor

Konstruktor untuk class Model ditentukan sebagai berikut:

class Model (parent=None, key_name=None, **kwds)

Superclass untuk definisi model data.

Selama konstruksi, metode validate() setiap properti dipanggil. Pengecualian dari panggilan tersebut diterapkan ke pemanggil konstruktor ini.

Argumen

parent

Instance model atau kunci untuk entity yang merupakan induk entity baru.

key_name

Nama kunci untuk entity. Nama yang akan menjadi bagian dari kunci utama. Jika None adalah ID numerik yang dihasilkan sistem, maka akan digunakan untuk kunci tersebut.

Nilai untuk key_name tidak boleh dalam format __*__.

Nama kunci disimpan sebagai string Unicode, dengan nilai str dikonversi sebagai teks ASCII.

Memanggil put() pada objek ini akan menggantikan entity Datastore yang ada dengan kunci yang sama.

kwds

Nilai awal untuk properti instance, sebagai argumen kata kunci. Setiap nama sesuai dengan atribut yang ditentukan di class Model.

Argumen kata kunci tambahan

key

Instance Key eksplisit untuk entity. Tidak dapat digunakan dengan key_name atau parent. Jika Nonekembali ke perilaku untuk key_name dan parent. Berguna saat menggunakan allocate_ids() untuk mencadangkan ID numerik untuk entity baru.

Nilai untuk key harus berupa instance Key yang valid.

Memanggil put() pada objek ini akan menggantikan entity Datastore yang ada dengan kunci yang sama.

Metode Class

Class Model memiliki metode class berikut:

Model.get (keys)

Mengambil instance model (atau instance) untuk kunci yang ditentukan. Kunci harus mewakili entity jenis model. Jika kunci yang diberikan bukan jenis yang tepat, pengecualian KindError akan dimunculkan.

Metode ini mirip dengan fungsi db.get() dengan pemeriksaan jenis tambahan.

Argumen

keys

Kunci entity yang akan diambil, representasi string dari kunci tersebut, atau daftar kunci atau representasi stringnya.

read_policy

Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:

STRONG_CONSISTENCY: Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY: Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline

Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan diturunkan untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi lain, atau menambahkan operasi ke task queue).

Jika keys terdiri dari kunci tunggal (atau representasi string-nya), metode ini akan menampilkan instance model yang terkait dengan kunci tersebut jika kunci tersebut ada dalam Datastore, jika tidak, None akan ditampilkan. Jika keys berupa daftar, nilai yang ditampilkan adalah daftar instance model yang sesuai, dengan nilai None jika tidak ada entity untuk kunci yang diberikan.

Lihat juga fungsi db.get().

Model.get_by_id (ids, parent=None)

Mengambil instance model (atau instance) untuk ID numerik (atau ID) yang ditentukan.

Argumen

ids

ID entity numerik atau daftar ID numerik.

parent

Parent entity untuk entity yang diminta, sebagai model atau kunci, atau None (default) jika entity yang diminta tidak memiliki induk. Beberapa entity yang diminta oleh satu panggilan harus memiliki induk yang sama.

read_policy

Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:

STRONG_CONSISTENCY: Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY: Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline

Jika ids terdiri dari ID numerik tunggal, metode ini akan menampilkan instance model yang terkait dengan ID tersebut jika ID tersebut ada di Datastore, jika tidak, None. Jika ids berupa daftar, nilai yang ditampilkan adalah daftar instance model yang sesuai, dengan nilai None jika tidak ada entity untuk ID numerik yang diberikan.

Model.get_by_key_name (key_names, parent=None)

Mengambil instance model (atau instance) untuk kunci yang ditentukan.

Argumen

key_names

Nama kunci, atau daftar nama kunci.

parent

Parent entity untuk entity yang diminta, sebagai instance atau kunci model , atau None (default) jika entity yang diminta tidak memiliki induk. Beberapa entity yang diminta oleh satu panggilan harus memiliki induk yang sama.

read_policy

Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:

STRONG_CONSISTENCY: Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY: Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline

Jika key_names terdiri dari nama kunci tunggal, metode ini akan menampilkan instance model yang terkait dengan nama tersebut jika nama tersebut ada di Datastore. Jika tidak, metode ini akan menampilkan None. Jika key_names berupa daftar, nilai yang ditampilkan adalah daftar instance model yang sesuai, dengan nilai None jika tidak ada entity untuk nama kunci yang diberikan.

Model.get_or_insert (key_name, **kwds)

Upaya mendapatkan entity jenis model dengan nama kunci yang diberikan. Jika ada, maka get_or_insert() akan menampilkannya. Jika tidak ada, entity baru dengan jenis, nama, dan parameter yang diberikan di kwds akan dibuat, disimpan, dan ditampilkan.

Operasi get dan put berikutnya (yang memungkinkan) digabungkan ke dalam transaksi untuk memastikan atomicity. Ini berarti get_or_insert() tidak akan pernah menggantikan entity yang ada, dan akan memasukkan entity baru jika dan hanya jika entity dengan jenis dan nama yang diberikan tidak ada. Dengan kata lain, get_or_insert() setara dengan kode Python berikut:

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

Argumen

key_name: Nama untuk kunci entity
kwds: Argumen kata kunci yang akan diteruskan ke konstruktor class model jika instance dengan nama kunci yang ditentukan tidak ada. Argumen parent diperlukan jika entity yang diinginkan memiliki induk.

Catatan: get_or_insert() tidak menerima argumen read_policy atau deadline.

Metode ini akan menampilkan instance class model yang mewakili entity yang diminta, baik instance tersebut ada maupun yang dibuat oleh metode. Seperti semua operasi Datastore, metode ini dapat memunculkan TransactionFailedError jika transaksi tidak dapat diselesaikan.

Model.all (keys_only=False)

Menampilkan objek Query yang mewakili semua entity untuk jenis yang sesuai dengan model ini. Metode pada objek kueri dapat menerapkan filter dan tata urutan ke kueri sebelum dieksekusi; lihat halaman class Query untuk informasi selengkapnya.

Argumen

keys_only: Apakah kueri harus menampilkan entity lengkap atau hanya kunci. Kueri yang menampilkan kunci lebih cepat dan menggunakan lebih sedikit waktu CPU dibandingkan kueri yang menampilkan entity lengkap.

Model.gql (query_string, *args, **kwds)

Menjalankan kueri GQL pada instance model ini.

Argumen

query_string: Bagian kueri GQL setelah SELECT * FROM model (yang tersirat menggunakan metode class ini).
args: Binding parameter posisi, mirip dengan konstruktor GqlQuery().
kwds: Binding parameter kata kunci, mirip dengan konstruktor GqlQuery().

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

Nilai yang ditampilkan adalah objek GqlQuery, yang dapat digunakan untuk mengakses hasilnya.

Model.kind ()

Menampilkan jenis model, biasanya nama subclass Model.

Model.properties ()

Menampilkan kamus semua properti yang ditentukan untuk class model ini.

Metode Instance

Instance model memiliki metode berikut:

key ()

Menampilkan Key Datastore untuk instance model ini.

Kunci instance model mencakup jenis entity instance bersamaan dengan ID unik. ID dapat berupa nama kunci string, yang ditetapkan secara eksplisit oleh aplikasi saat instance dibuat, atau ID numerik dalam bilangan bulat, ditetapkan secara otomatis oleh App Engine saat instance dimasukkan (put ) ke Datastore. Memanggil key() sebelum instance diberi ID akan memunculkan pengecualian NotSavedError.

put ()

Menyimpan instance model di Datastore. Jika instance model baru dibuat dan belum pernah disimpan, metode ini akan membuat entity data baru di Datastore. Jika tidak, entity data akan diperbarui dengan nilai properti saat ini.

Metode akan menampilkan kunci entity yang disimpan.

Jika data tidak dapat di-commit, ajukan pengecualian TransactionFailedError.

Argumen

deadline: Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan diturunkan untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi lain, atau menambahkan operasi ke task queue).

delete ()

Menghapus instance model dari Datastore. Jika instance belum pernah dimasukkan (put) ke Datastore, penghapusan akan memunculkan pengecualian NotSavedError.

Argumen

deadline: Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan diturunkan untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi lain, atau menambahkan operasi ke task queue).

is_saved ()

Menampilkan True jika instance model telah dimasukkan (put) ke Datastore setidaknya satu kali.

Metode ini hanya memeriksa apakah instance telah dimasukkan ke Datastore setidaknya satu kali sejak dibuat. Fungsi ini tidak memeriksa apakah properti instance telah diperbarui sejak terakhir kali dimasukkan.

dynamic_properties ()

Menampilkan daftar nama semua properti dinamis yang ditentukan untuk instance model ini. Ini hanya berlaku untuk instance class Expando. Untuk instance model non-Expando, tindakan ini akan menampilkan daftar kosong.

parent ()

Menampilkan instance model untuk parent entity dari instance ini, atau None jika instance ini tidak memiliki induk.

parent_key ()

Menampilkan Key parent entity dari instance ini, atau None jika instance ini tidak memiliki induk.

to_xml ()

Menampilkan representasi XML dari instance model.

Nilai properti sesuai dengan spesifikasi Atom dan Data.

Nama Properti yang Tidak Diizinkan

Datastore dan API-nya memberlakukan beberapa batasan pada nama untuk properti entity dan atribut instance model.

Datastore mencadangkan semua nama properti yang diawali dan diakhiri dengan dua garis bawah (__*__). Entity Datastore tidak boleh memiliki properti dengan nama tersebut.

API model Python mengabaikan semua atribut pada class Model atau Expando yang dimulai dengan garis bawah (_). Aplikasi Anda dapat menggunakan atribut ini untuk mengaitkan data dengan objek model yang tidak disimpan ke Datastore.

Terakhir, Python model API menggunakan atribut objek untuk menentukan properti model, dan secara default properti entity Datastore diberi nama berdasarkan atributnya. Karena class Model memiliki beberapa properti dan metode untuk tujuan lain, atribut tersebut tidak dapat digunakan untuk properti di Python API. Misalnya, Model tidak boleh memiliki properti yang diakses dengan atribut key.

Namun, properti dapat menentukan nama yang berbeda untuk Datastore dan nama atribut dengan memberikan argumen name ke konstruktor properti. Hal ini memungkinkan entity Datastore memiliki nama properti yang mirip dengan atribut yang dicadangkan di class Model, dan menggunakan nama atribut yang berbeda di class tersebut.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Nama atribut berikut dicadangkan oleh class Model di Python API:

all
app
copy
delete
entity
entity_type
fields
from_entity
get
gql
instance_properties

is_saved
key
key_name
kind
parent
parent_key
properties
put
setdefault
to_xml
update