Python 2.7 telah mencapai akhir dukungan
dan akan dihentikan penggunaannya
pada 31 Januari 2026. Setelah penghentian penggunaan, Anda tidak akan dapat men-deploy aplikasi Python 2.7, meskipun organisasi Anda sebelumnya menggunakan kebijakan organisasi untuk mengaktifkan kembali deployment runtime lama. Aplikasi Python 2.7 yang ada akan terus berjalan dan menerima traffic setelah
tanggal penghentiannya. Sebaiknya Anda bermigrasi ke versi Python terbaru yang didukung.
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Functions
ndb.add_flow_exception(exc)
Tentukan bahwa pengecualian tidak boleh dicatat, tetapi hanya boleh menjadi bagian dari alur program normal. (Biasanya, memunculkan pengecualian akan menulis pesan peringatan ke log aplikasi.)
Argumen
exc
Class pengecualian yang tidak boleh dicatat.
Secara default, pengecualian berikut tidak dicatat:
webob.exc.HTTPException (dan subclass-nya)
ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Menghapus entity yang diidentifikasi oleh urutan kunci yang diteruskan.
Dekorator untuk memastikan bahwa fungsi berjalan di luar transaksi.
Argumen:
allow_existing
Jika True (default) dan jika fungsi yang didekorasi dipanggil oleh kode dalam transaksi, fungsi ini akan berjalan secara independen dari transaksi tersebut. Jika False dan jika fungsi yang didekorasi dipanggil oleh kode dalam transaksi, fungsi tersebut akan memunculkan pengecualian.
Menampilkan Future.
Kode future ini menunjukkan callback apa pun yang ditampilkan, atau memunculkan callback apa pun atau TransactionFailedError jika transaksi gagal.
Untuk meneruskan argumen ke fungsi callback, gunakan lambda. Misalnya,
Opsi konteks memungkinkan Anda menjalankan operasi datastore tertentu dengan konfigurasi yang berbeda. Misalnya, Anda mungkin ingin memvariasikan kebijakan baca atau batas waktu RPC untuk setiap permintaan.
Anda dapat melakukannya dengan meneruskan opsi konteks ke hampir semua operasi.
Beberapa fungsi terkait transaksi menggunakan opsi transaksi, yang mencakup opsi tambahan selain serangkaian opsi konteks.
Berikut beberapa contoh penggunaan opsi konteks. Untuk menetapkan batas waktu RPC ke 1 detik saat membaca entity, Anda dapat menggunakan:
key.get(deadline=1)
Untuk menetapkan waktu tunggu memcache ke 30 detik saat menulis entity, Anda dapat menggunakan:
ent.put(ndb_memcache_timeout=30)
Untuk menghapus item yang telah di-cache dan memaksanya dimuat ulang, Anda dapat menggunakan:
key.delete(use_datastore=False)
Argumen kata kunci khusus options dan config (yang memiliki arti identik untuk alasan historis) memungkinkan seseorang menentukan beberapa opsi sebagai objek Konfigurasi. Ini dapat berupa objek ndb.ContextOptions atau (untuk fungsi dan dekorator transaksional) objek ndb.TransactionOptions.
Misalnya, key.get(options=ndb.ContextOptions(use_cache=True)) setara dengan key.get(use_cache=True).
Opsi yang ditetapkan dalam objek opsi tersebut dapat diganti oleh parameter kata kunci.
Tersedia opsi konteks berikut:
Opsi
Jenis
Deskripsi
deadline
float
Batas waktu panggilan datastore, ditetapkan sebagai jumlah detik.
(Secara default, panggilan hanya diganggu oleh batas waktu pengendali permintaan.)
read_policy
ndb.EVENTUAL_CONSISTENCY
Tetapkan ini ke ndb.EVENTUAL_CONSISTENCY jika, alih-alih menunggu Datastore menyelesaikan penerapan perubahan ke semua hasil yang ditampilkan, Anda ingin mendapatkan hasil yang mungkin bukan hasil terkini lebih cepat.
force_writes
bool
Menentukan apakah permintaan tulis akan berhasil meskipun aplikasi bersifat hanya baca.
(Ini hanya berlaku untuk periode hanya baca yang dikontrol pengguna.)
use_cache
bool
Menentukan apakah akan menyimpan entity pada cache dalam proses; mengganti kebijakan cache dalam proses untuk operasi ini.
use_memcache
bool
Menentukan apakah akan menyimpan entity dalam memcache; menggantikan kebijakan memcache untuk operasi ini.
use_datastore
bool
Menentukan apakah akan menyimpan entity di Datastore; menggantikan kebijakan Datastore untuk operasi ini.
memcache_timeout
int
Masa pakai maksimum untuk entity dalam memcache; menggantikan kebijakan waktu tunggu memcache untuk operasi ini.
max_memcache_items
int
Ukuran batch maksimum untuk fitur pembuatan batch otomatis metode memcache Konteks.
Misalnya, dengan ukuran default max_memcache_items (100), hingga 100 operasi yang ditetapkan memcache akan digabungkan menjadi satu operasi set_multi.
Untuk beberapa fungsi terkait transaksi, opsi transaksi berikut tersedia (beserta opsi konteks yang diwariskan yang tercantum di atas):
Opsi
Jenis
Deskripsi
xg
bool
Izinkan transaksi lintas grup (XG).
False secara default.
propagation
int
NDB memberikan dukungan terbatas untuk transaksi dalam transaksi, yang dikenal sebagai "transaksi bertingkat".
Parameter penerapan mengontrol hal yang terjadi jika kode Anda mencoba memulai transaksi bertingkat.
Kebijakan penerapan untuk @ndb.transactional ditetapkan secara default ke ALLOWED.
Kebijakan penerapan untuk ndb.transaction() ditetapkan secara default ke NESTED.
Kebijakan NESTED tidak didukung oleh NDB sehingga kode Anda akan menampilkan pengecualian BadRequestError. Dalam hal ini, NDB menetapkan nilai default yang tidak didukung sehingga programmer mengetahui secara eksplisit batasan transaksi bertingkat.
Parameter penerapan dapat berupa salah satu nilai berikut:
ndb.TransactionOptions.NESTED
Kebijakan penerapan NESTED akan meng-commit semua perubahan pada transaksi luar dan dalam secara bersamaan saat kebijakan luar di-commit. Namun, jika pengecualian ditampilkan dalam transaksi internal, semua perubahan akan dihapus, tetapi memungkinkan transaksi luar dapat dipulihkan dan dilanjutkan secara opsional. Kebijakan NESTED tidak didukung. Jika menggunakan kebijakan ini, kode Anda akan menampilkan pengecualian BadRequestError.
ndb.TransactionOptions.MANDATORY
Selalu menerapkan transaksi yang sudah ada; memberikan pengecualian jika tidak ada transaksi yang ada.
Jika fungsi yang menggunakan kebijakan ini menampilkan pengecualian, mungkin tidak aman untuk menangkap pengecualian tersebut dan meng-commit transaksi luar; fungsi tersebut mungkin telah meninggalkan transaksi luar dalam kondisi buruk.
ndb.TransactionOptions.ALLOWED
Jika sudah ada transaksi, terapkan transaksi tersebut.
Jika fungsi yang menggunakan kebijakan ini menampilkan pengecualian, mungkin tidak aman untuk menangkap pengecualian tersebut dan meng-commit transaksi luar; fungsi tersebut mungkin telah meninggalkan transaksi luar dalam kondisi buruk.
ndb.TransactionOptions.INDEPENDENT
Selalu gunakan transaksi baru, "menjeda" transaksi yang sudah ada.
Fungsi yang menggunakan kebijakan ini tidak boleh menampilkan entity apa pun yang dibaca dalam transaksi baru, karena entity tersebut tidak konsisten secara transaksi dengan transaksi pemanggil.
retries
int
Jumlah percobaan ulang secara otomatis jika terjadi kegagalan transaksi.
Nol berarti mencoba sekali, tetapi bukan mencoba lagi.
Dalam beberapa kasus, opsi diabaikan karena penyimpanan dalam cache.
Misalnya, jika Anda menentukan batas waktu RPC untuk operasi baca yang terpenuhi dari cache dalam konteks, batas waktu tersebut akan diabaikan.
Di sisi lain, opsi yang tidak dikenal menyebabkan TypeError dimunculkan.
Operasi dengan berbagai opsi dikelompokkan bersama saat pembuatan batch otomatis diterapkan. Misalnya, jika Anda menggunakan put_async() untuk menulis beberapa entity dengan deadline = 5 dan beberapa entity tanpa menentukan batas waktu, dan semuanya memenuhi syarat untuk pembuatan batch otomatis, batcher otomatis akan membuat dua panggilan RPC terpisah—satu untuk grup entity dengan deadline = 5 dan satu untuk grup lainnya—meskipun batas waktu RPC default juga 5.
Hal ini berlaku meskipun opsi yang ditentukan tidak relevan dengan operasi RPC (misalnya ndb_should_cache).
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-04 UTC."],[[["\u003cp\u003eThis page documents the use of legacy bundled services and APIs, which are specifically designed for first-generation runtimes in the App Engine standard environment.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003endb\u003c/code\u003e API provides functions for managing entities, including operations like fetching, deleting, and storing entities, both synchronously and asynchronously.\u003c/p\u003e\n"],["\u003cp\u003eTransactions can be managed through the \u003ccode\u003endb\u003c/code\u003e API, allowing you to run operations in a transactional context, which can be done either directly or using decorators like \u003ccode\u003e@ndb.transactional\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eContext and transaction options are available to configure datastore operations, allowing customization of settings like deadlines, caching behavior, and read policies for individual requests.\u003c/p\u003e\n"],["\u003cp\u003eSpecific exceptions, such as \u003ccode\u003ewebob.exc.HTTPException\u003c/code\u003e and \u003ccode\u003endb.Rollback\u003c/code\u003e, are not logged by default, and users can specify additional exceptions to be excluded from logging via \u003ccode\u003endb.add_flow_exception\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# NDB Functions\n\nFunctions\n---------\n\n| This page describes how to use the legacy bundled services and APIs. This API can only run in first-generation runtimes in the App Engine standard environment. If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nndb.add_flow_exception(exc)\n: Specify that an exception should *not* be logged, but is just part of\n normal program flow. (Normally, raising an exception writes a warning\n message to the application's logs.)\n\n **Arguments**\n\n exc\n\n : Exception class that should not be logged. By default, the following exceptions are not logged:\n\n - `webob.exc.HTTPException` (and its subclasses)\n - `ndb.Rollback`\n\nndb.delete_multi(keys, \\*\\*ctx_options)\n\n: Deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\nndb.delete_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result will be `None`.\n\nndb.get_multi(keys, \\*\\*ctx_options)\n\n: Fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list. Each list item is either a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.get_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result is a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.in_transaction()\n: Returns a Boolean indicating whether a transaction is currently active.\n\n@ndb.non_transactional \n\n@ndb.non_transactional(allow_existing=True)\n: Decorator to ensure that a function runs *outside* a transaction.\n\n **Arguments:**\n\n allow_existing\n : If `True` (the default) and if the decorated function\n is called by code in a transaction, the function runs independent\n of the transaction. If `False` and if the decorated function\n is called by code in a transaction, it raises an exception.\n\nndb.put_multi(entities, \\*\\*ctx_options)\n: Stores a sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list with the stored [keys](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.put_multi_async(entities, \\*\\*ctx_options)\n: Asynchronously stores a sequence of\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects.\n Each future's result will be a stored [key](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.transaction(callback, \\*\\*ctx_options)\n\n: Run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns whatever callback returns.\n Raises whatever callback raises or a\n `TransactionFailedError` exception if the transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\nndb.transaction_async(callback, \\*\\*ctx_options)\n\n: Asynchronously run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns a [Future](/appengine/docs/legacy/standard/python/ndb/futureclass).\n The future returns whatever callback returns, or\n raises whatever callback raises or a\n `TransactionFailedError` if the\n transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\n@ndb.transactional \n\n@ndb.transactional(\\*\\*ctx_options)\n\n: Decorator to make a function automatically run in a transaction. **Arguments:**\n\n This decorator can have [transaction options](#context_options).\n\nContext Options, Transaction Options\n------------------------------------\n\nContext options allow you to run specific datastore operations with different\nconfigurations. For example, you might want to vary the read policy\nor the RPC deadline for individual requests.\nYou can do this by passing *context options* to almost any operation.\nSome transaction-related functions take *transaction options*, which include additional options\non top of a set of context options.\n\nHere are a few examples using context options. To set the RPC deadline to 1 second when reading an entity,\nyou can use:\n\n```python\nkey.get(deadline=1)\n```\n\nTo set the memcache timeout to 30 seconds when writing an entity,\nyou can use:\n\n```python\nent.put(ndb_memcache_timeout=30)\n```\n\nTo delete an item that has been cached and force its reload, you can use:\n\n```python\nkey.delete(use_datastore=False)\n```\n\nThe special keyword arguments `options` and `config`\n(which have identical meanings for historical reasons) allow one to specify\nseveral options as a Configuration object. This can be an\n`ndb.ContextOptions` object or\n(for the transactional functions and decorator) an\n`ndb.TransactionOptions` object.\nFor example,\n`key.get(options=ndb.ContextOptions(use_cache=True))`\nis equivalent to\n`key.get(use_cache=True)`.\nThe options set in such an options object can be overridden by\nkeyword parameters.\n\nThe following **context options** are available:\n\nIn some cases, options are ignored because of caching.\nFor example, if you specify an RPC deadline for a read\noperation that is satisfied from the in-context cache,\nthe deadline is ignored.\nOn the other hand,\nunrecognized options cause `TypeError` to be raised.\n\nOperations with different options are grouped together when\nauto-batching applies. For example, if you use `put_async()`\nto write some entities with\n`deadline = 5`\nand some without specifying a deadline, and all are eligible for\nauto-batching, the auto-batcher will make two separate RPC\ncalls---one for the group of entities with\n`deadline = 5`\nand one for the other group---even though the default\nRPC deadline is also 5!\nThis applies even if the option specified is irrelevant to\nthe RPC operation (for example, `ndb_should_cache`)."]]
