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
內容選項

會傳回清單。若找不到金鑰，每一個清單項目各會是 Model 例項或 None。

ndb.get_multi_async(keys, **ctx_options)
以非同步方式擷取由傳遞的鍵序列所標示的實體。

引數

keys
鍵
的序列
**ctx_options
內容選項

會傳回 Future 物件的清單。若找不到金鑰，future 的每一個結果各會是 Model 例項或 None。

ndb.in_transaction()
會傳回布林值，表示交易在當下是否有效。
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
裝飾子，可確保函式在交易外執行。

引數：

allow_existing
如果 True (預設) 且交易中的程式碼呼叫經過修飾的函式，則函式會獨立於交易執行。如果 False 和經過修飾的函式是由交易中的程式碼呼叫，則會引發例外狀況。
ndb.put_multi(entities, **ctx_options)
儲存 Model 例項的序列。

引數

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

傳回儲存的鍵清單。

ndb.put_multi_async(entities, **ctx_options)
以非同步方式儲存 Model 例項序列。

引數

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

會傳回 Future 物件的清單。每個 Future 的結果都會是已儲存的 金鑰。

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

引數

回呼
要呼叫的函式或子工作
**ctx_options
交易選項

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

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

def my_callback(key, inc):
  ...

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

引數

回呼
要呼叫的函式或子工作
**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)

特殊關鍵字引數 options 和 config (因歷史記錄而具有相同的意義) 可用於將數個選項指定為設定物件，這可以是 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 中儲存實體；覆寫此作業的 Memcache 政策。
use_datastore bool 指定是否要在 Datastore 中儲存實體，並覆寫此操作的 Datastore 政策。
memcache_timeout int Memcache 中實體的最長生命週期；會覆寫此作業的 Memcache 逾時政策。
max_memcache_items int Context 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)，仍然會是如此。