NDB 函式

函式

ndb.add_flow_exception(exc)
指定某個例外狀況只是正常程式流程的一部分,「不」應予以記錄。(若引發例外狀況,通常會在應用程式的記錄中寫入警告)。

引數

exc
不應記錄的例外狀況類別。

預設不記錄以下例外狀況:

  • webob.exc.HTTPException (及其子類別)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
會刪除所傳遞之金鑰序列指定的實體。

引數

keys
金鑰的序列
**ctx_options
內容選項
ndb.delete_multi_async(keys, **ctx_options)
非同步刪除所傳遞之金鑰序列指定的實體。

引數

keys
金鑰的序列
**ctx_options
內容選項

會傳回 Future 物件的清單。future 的每一個結果都會是 None

ndb.get_multi(keys, **ctx_options)
會擷取所傳遞之金鑰序列指定的實體。

引數

keys
金鑰的序列
**ctx_options
內容選項

會傳回清單。若找不到金鑰,每一個清單項目各會是模型執行個體或 None

ndb.get_multi_async(keys, **ctx_options)
非同步擷取所傳遞之金鑰序列指定的實體。

引數

keys
金鑰的序列
**ctx_options
內容選項

會傳回 Future 物件的清單。若找不到金鑰,future 的每一個結果各會是模型執行個體或 None

ndb.in_transaction()
會傳回布林值,表示交易在當下是否有效。
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
裝飾項目,用於確定函式會在交易「以外」執行。

引數:

allow_existing
True (預設值) 且交易程式碼呼叫該裝飾函式,該函式會與交易分開執行。若為 False,且交易程式碼呼叫該裝飾函式,則會引發例外狀況。
ndb.put_multi(entities, **ctx_options)
會儲存模型執行個體的序列。

引數

entities
模型執行個體的序列
**ctx_options
內容選項

會傳回含預存金鑰的清單。

ndb.put_multi_async(entities, **ctx_options)
非同步儲存模型執行個體的序列。

引數

entities
模型執行個體的序列
**ctx_options
內容選項

會傳回 Future 物件的清單。 future 的每一個結果都會是一個預存的金鑰

ndb.transaction(callback, **ctx_options)
在交易中執行回呼。

引數

callback
要呼叫的函式或 tasklet
**ctx_options
交易選項

會傳回回呼傳回的任何資料。會引發回呼引發的任何狀況,若交易失敗,則會引發 TransactionFailedError 例外狀況。

若要傳送引數至回呼函式,請使用 lambda。例如:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
在交易中非同步執行回呼。

引數

callback
要呼叫的函式或 tasklet
**ctx_options
交易選項

會傳回 Future。future 會傳回回呼傳回的任何資料,或者會引發回呼引發的任何狀況,若交易失敗,則會引發 TransactionFailedError

若要傳送引數至回呼函式,請使用 lambda。例如:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
@ndb.transactional
@ndb.transactional(**ctx_options)
讓函式在交易中自動執行的裝飾項目。

引數:

這個裝飾項目可以有交易選項

內容選項與交易選項

內容選項可讓您使用不同的設定,執行特定資料儲存庫作業。例如,您可以變更個別要求的讀取政策或遠端程序呼叫 (RPC) 期限。將「內容選項」傳送至幾乎一項任何作業都能達到這個目的。某些與交易相關的函式會接受「交易選項」,除了一組內容選項外,這些交易選項還包括其他選項。

以下列舉幾個使用內容選項的範例。若要在讀取實體時將 RPC 期限設為 1 秒,可以使用:

key.get(deadline=1)

若要在寫入實體時將 memcache 逾時設為 30 秒,可以使用:

ent.put(ndb_memcache_timeout=30)

若要刪除已經快取的項目並強制其重新載入,可以使用:

key.delete(use_datastore=False)

特殊關鍵字引數 optionsconfig (因歷史記錄而具有相同的意義) 可用於將數個選項指定為設定物件,可以是 ndb.ContextOptions 物件或 (交易函式和裝飾項目) 的 ndb.TransactionOptions 物件。例如,key.get(options=ndb.ContextOptions(use_cache=True)) 等同於 key.get(use_cache=True)。可以使用關鍵字參數覆寫在此類選項物件中設定的選項。

可用的內容選項如下:

選項類型說明
deadline float 資料儲存庫呼叫期限 (以秒數指定)。 (預設只有要求處理常式期限能中斷呼叫。)
read_policy ndb.EVENTUAL_CONSISTENCY 將此設為 ndb.EVENTUAL_CONSISTENCY (若您不想等資料儲存庫將變更套用於所有傳回的結果,而想更快得到可能並非最新的結果)。
force_writes bool 指定當應用程式處於唯讀狀態時,是否仍可寫入成功 (只適用於使用者控制的唯讀期間)。
use_cache bool 指定是否要將實體儲存於處理中快取;會覆寫此作業的處理中快取政策。
use_memcache bool 指定是否要將實體儲存於 memcache;會覆寫此作業的 mcache 政策。
use_datastore bool 指定是否要將實體儲存於資料儲存庫;會覆寫此作業的資料儲存庫政策。
memcache_timeout int 實體在 memcache 中的生命週期上限;會覆寫此作業的 memcache 逾時政策。
max_memcache_items int 內容 memcache 方法自動批次功能的批次大小上限。 例如,若預設大小是 max_memcache_items (100),則最多 100 個 memcache 組合作業會合併為單一 set_multi 作業。

某些與交易相關的函式可以使用下列交易選項 (以及上方所列的沿用內容選項):

選項類型說明
xg bool 允許跨群組 (XG) 交易。 預設是 False
propagation int

NDB 針對交易內的交易提供有限支援,這類交易稱為「巢狀交易」。

傳播參數用於控制程式碼嘗試開始巢狀交易時會發生的狀況。

@ndb.transactional 的傳播政策預設是 ALLOWED

ndb.transaction() 的傳播政策預設是 NESTED。NDB 不支援 NESTED 政策,因此您的程式碼會擲回 BadRequestError 例外狀況。在此情況下,NDB 會設定不支援的預設值,讓程式設計師明確知道巢狀交易的限制。

傳播參數的值可以是以下任何一個值:

ndb.TransactionOptions.NESTED
外部政策提交時,NESTED 傳播政策會同時在外部和內部交易提交所有變更。不過,若例外狀況擲入到內部交易中,則系統會擲回該交易中的所有變更,只允許外部交易選擇性地復原並繼續。不支援 NESTED 政策。若使用此政策,您的程式碼會擲回 BadRequestError 例外狀況。
ndb.TransactionOptions.MANDATORY
一律傳播現有交易;若沒有現有交易,會擲回例外狀況。若使用此政策的函式擲回例外狀況,擷取例外狀況並提交外部交易可能並不安全;此函式可能會導致外部交易陷入不良狀態。
ndb.TransactionOptions.ALLOWED
若存在現有交易,則傳播該交易。若使用此政策的函式擲回例外狀況,擷取例外狀況並提交外部交易可能並不安全;此函式可能會導致外部交易陷入不良狀態。
ndb.TransactionOptions.INDEPENDENT
一律「暫停」任何現有交易並使用新的交易。使用此政策的函式不應傳回在新交易中讀取到的任何政策,因為實體在交易方面與呼叫端的交易並不一致。
retries int 交易失敗時自動重試的次數。零表示只嘗試一次,而不「重試」

在某些情況下,選項會因為快取的緣故而遭到選項。例如,若指定讀取作業的 RPC 期限,且內容快取能滿足這項讀取作業,就會忽略期限。另一方面,無法辨識的選項會引發 TypeError

套用自動批次處理功能時,系統會將選項不同的作業分成不同群組。例如,若使用 put_async() 寫入實體,其中部分實體的設定為 deadline = 5,部分則未指定期限,且所有實體均符合自動批次處理條件,則自動分批處理器會進行兩次獨立的 RPC 呼叫,一次呼叫 deadline = 5 的實體群組,另一次則呼叫另一個群組,即使預設 RPC 期限也是 5 也一樣。即使您指定的選項與 RPC 作業無關 (例如 ndb_should_cache),仍然會是如此。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境