Datastore 函式

注意事項:強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫。相較於這個用戶端程式庫,NDB 用戶端程式庫具備幾項優勢,例如能夠透過 Memcache API 自動快取實體。如果您目前使用的是舊版 DB 用戶端程式庫,請參閱 DB 至 NDB 遷移指南

此頁面說明的函式均在 google.appengine.ext.db 套件中定義。

函式

allocate_ids (model, count)

在 Datastore 中,為 Datastore 種類和父項組合分配一批 ID。

以此方法分配的 ID 將不會由 Datastore 的自動 ID 序列產生器使用,但可以在實體金鑰中使用,而不會產生衝突。

引數

model
分配 ID 批次的模型金鑰。這是一般金鑰。但決定使用哪個 ID 序列時,僅需要金鑰的父項和種類。
count
要配置的 ID 數值。

傳回所配置第一個和最後一個 ID 的組合。例如,如果您使用這個函式分配 10 個 ID,就會獲得格式為 (1, 10) 的傳回值,而非所建立 ID 的完整清單。

配置和使用 ID 的範例如下:

# allocate for MyModel without an instance
handmade_key = db.Key.from_path('MyModel', 1)
first_batch = db.allocate_ids(handmade_key, 10)
first_range = range(first_batch[0], first_batch[1] + 1)

# or allocate using an existing key
model_instance = MyModel.all().get()
second_batch = db.allocate_ids(model_instance.key(), 10)
second_range = range(second_batch[0], second_batch[1] + 1)

# and then use them! woo!
my_id = second_range.pop(0)
new_key = db.Key.from_path('MyModel', my_id)
new_instance = MyModel(key=new_key)
new_instance.put()
assert new_instance.key().id() == my_id

# the Datastore will not assign ids in first_batch or second_batch
another_instance = MyModel()
another_instance.put()
assert another_instance.key().id() not in first_range
assert another_instance.key().id() not in second_range
allocate_ids_async (model, count)

在 Datastore 中,以非同步方式為 Datastore 種類和父項組合分配一批 ID。

這個函式與 allocate_ids() 幾乎相同,唯一的差異在於這個函式會傳回非同步物件。您可以對傳回值呼叫 get_result(),以便封鎖呼叫並傳回結果。

引數

model
db.Model 執行個體、金鑰或字串,可用來當做指定 ID 分配序列的範本。傳回的 ID 只能用於與這組金鑰擁有相同父項 (如有) 和種類的實體。
count
要配置的 ID 數值。

傳回所配置第一個和最後一個 ID 的組合。例如,如果您使用這個函式分配 10 個 ID,就會獲得格式為 (1, 10) 的傳回值,而非所建立 ID 的完整清單。

allocate_id_range (model, start, end, **kwargs)

分配特定起迄點範圍內的 ID。這些 ID 分配好之後,即可透過手動方式指派給新建立的實體。

Datastore 的自動 ID 分配器不會指派已分配的金鑰 (無論是透過自動 ID 分配或明確呼叫 'allocate_ids')。因此,寫入指定金鑰範圍的實體便永遠不會遭到覆寫。然而,根據傳回的金鑰範圍狀態,如果將這個範圍內的金鑰手動指派給實體,則寫入這些實體時可能會覆寫現有的實體 (或是由個別要求寫入的新實體)。

請只在您有想要保留的現有數字 ID 範圍時,才使用此函式 (例如,大量載入已具有 ID 的實體)。如果您不在意收到的 ID,請改為使用 allocate_ids()

引數

model
db.Model 執行個體、金鑰或字串,可用來當做指定 ID 分配序列的範本。傳回的 ID 只能用於與這組金鑰擁有相同父項 (如有) 和種類的實體。
start
第一個要分配的 ID,這會是一個數字。
end
最後一個要分配的 ID,這會是一個數字。

傳回 (KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION, KEY_RANGE_COLLISION) 之一。若沒有 KEY_RANGE_EMPTY,這代表使用已分配金鑰範圍時可能發生問題。

create_transaction_options (**kwargs)

建立交易選項物件 (類別 TransactionOptions),以便控制交易執行。您會將產生的物件當做第一個引數傳送至 run_in_transaction_options() 函式。

引數

propagation
如果另一個交易呼叫此交易函式,則該如何處理:
允許
如果已在交易中,請繼續使用;如果不在交易中,請開始交易。

附註:如果使用此政策的函式擲回例外狀況,擷取例外狀況並修訂外部交易可能並不安全;該函式可能會讓外部交易呈現不良狀態。

必要
如果交易正在進行,則繼續執行。如果未進行交易,則傳回 BadRequestError 例外狀況。

附註:如果使用此政策的函式擲回例外狀況,擷取例外狀況並修訂外部交易可能並不安全;該函式可能會讓外部交易呈現不良狀態。

獨立
建立新的交易,暫停任何現有交易。

附註:使用此政策的函式不應傳回在新交易中讀取到的任何實體,因為實體在交易方面與外部交易並不一致。

巢狀
(尚不支援) 在既有交易中建立巢狀交易。
xg
如為 True,則允許跨群組 (XG) 交易。如果設為非布林值,則會傳送 BadArgumentError 例外狀況。
retries
交易修訂失敗時的重試次數。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

以下範例會建立後續跨群組 (XG) 交易的選項:

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_on, my_txn)
delete (models, deadline=60)

從 Datastore 刪除一或多個模型執行個體。

引數

models
要刪除的模型執行個體或實體金鑰的模型執行個體、實體金鑰或清單 (或其他可疊代項目)。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如同 put(),如果您輸入多組金鑰,可能會產生一個以上的實體群組

如果作業期間發生任何錯誤,即便系統已確實刪除部分實體,仍一律會傳回例外狀況。如果呼叫傳回時沒有傳回例外狀況,則所有實體均已成功刪除。

注意事項:如果您在單一作業中刪除多個實體,我們並不保證會一次刪除所有實體,除非該項作業是在交易中執行。即便查詢以高同步一致性執行,其他查詢 Datastore 的程序也可能會得到不一致的結果。

delete_async (models, deadline=60)

以非同步方式從 Datastore 刪除一或多個模型執行個體。

這個函式與 delete() 幾乎相同,唯一的差異在於這個函式會傳回非同步物件。您可以對傳回值呼叫 get_result(),以便封鎖呼叫並傳回結果。

引數

models
要刪除的模型執行個體或實體金鑰的模型執行個體、實體金鑰或清單 (或其他可疊代項目)。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如同 put(),如果您輸入多組金鑰,可能會產生一個以上的實體群組

這個函式傳回的物件可讓您封鎖呼叫結果。

如果作業期間發生任何錯誤,即便系統已確實刪除部分實體,仍一律會傳回例外狀況。如果呼叫傳回時沒有傳回例外狀況,則所有實體均已成功刪除。

注意事項:如果您在單一作業中刪除多個實體,我們並不保證會一次刪除所有實體,除非該項作業是在交易中執行。即便查詢以高同步一致性執行,其他查詢 Datastore 的程序也可能會得到不一致的結果。

get (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

從 Datastore 使用指定的金鑰擷取特定模型執行個體。

引數

keys
要擷取的實體金鑰、金鑰的字串表示法,或是金鑰或金鑰字串表示法的清單。
read_policy
指定所需資料一致性程度的讀取政策:
STRONG_CONSISTENCY
保證為最新結果,但限於單一實體群組
EVENTUAL_CONSISTENCY
可涵蓋多個實體群組,但可能有時會傳回過時結果。一般來說,最終一致性查詢的執行速度,比同步一致性查詢更快,但並不保證絕對如此。

注意:全域 (非祖系) 查詢會忽略這個引數。

deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如果 keys 包含多個單一金鑰 (或其字串表示法),且金鑰存在於 Datastore 之中,此函式就會傳回與金鑰相關的模型執行個體,否則為 None。如果 keys 為清單,傳回值為對應的模型執行個體清單,如果特定金鑰沒有實體,則為 None 值。

另請參閱 Model.get()

get_async (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

以非同步方式從 Datastore 中擷取特定的模型執行個體。

這個函式與 get() 幾乎相同,唯一的差異在於這個函式會傳回非同步物件。您可以對傳回值呼叫 get_result(),以便封鎖呼叫並傳回結果。

引數

keys
要擷取的實體金鑰、金鑰的字串表示法,或是金鑰或金鑰字串表示法的清單。
read_policy
指定所需資料一致性程度的讀取政策:
STRONG_CONSISTENCY
保證為最新結果,但限於單一實體群組
EVENTUAL_CONSISTENCY
可涵蓋多個實體群組,但可能有時會傳回過時結果。一般來說,最終一致性查詢的執行速度,比同步一致性查詢更快,但並不保證絕對如此。

注意:全域 (非祖系) 查詢會忽略這個引數。

deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如果 keys 包含多個單一金鑰 (或其字串表示法),且金鑰存在於 Datastore 之中,此函式就會傳回與金鑰相關的模型執行個體,否則為 None。如果 keys 為清單,傳回值為對應的模型執行個體清單,如果特定金鑰沒有實體,則為 None 值。

另請參閱 Model.get()

get_indexes ()

傳回屬於呼叫應用程式的複合索引清單。

以下範例說明如何取得和使用索引:

def get_index_state_as_string(index_state):
  return {db.Index.BUILDING:'BUILDING', db.Index.SERVING:'SERVING',
          db.Index.DELETING:'DELETING', db.Index.ERROR:'ERROR'}[index_state]

def get_sort_direction_as_string(sort_direction):
  return {db.Index.ASCENDING:'ASCENDING',
          db.Index.DESCENDING:'DESCENDING'}[sort_direction]

def dump_indexes():
  for index, state in db.get_indexes():
    print "Kind: %s" % index.kind()
    print "State: %s" % get_index_state_as_string(state)
    print "Is ancestor: %s" % index.has_ancestor()
    for property_name, sort_direction in index.properties():
      print "  %s:%s" % (property_name,
                         get_sort_direction_as_string(sort_direction))
get_indexes_async ()

以非同步方式傳回屬於呼叫應用程式的複合索引清單。

is_in_transaction ()

傳回布林值,表示交易是否正在執行目前的範圍。

model_to_protobuf (model_instance)

建立 Model 執行實體的通訊協定緩衝區序列化。通訊協定緩衝區是 Google 的序列化格式,用於遠端程序呼叫,且對於備份及還原目的的 Datastore 物件序列化十分有用。

注意事項:相較於開放原始碼的通訊協定緩衝區,這個函式會為通訊協定緩衝區使用不同 (舊版) 的格式,而且這個格式與開放原始碼部署項目不相容。

引數

model_instance
要序列化的類別 Model (或子類別)。

以位元組字串格式,傳回通訊協定緩衝區序列化的物件。

model_from_protobuf (pb)

依據通訊協定緩衝區序列化結果建立 Model 執行個體,詳情請參閱 model_to_protobuf()

引數

pb
model_to_protobuf() 傳回的通訊協定緩衝區序列化結果。

傳回適當種類類別的物件。如果種類類別不存在,系統會傳回 KindError 例外狀況。如果該物件對模型無效,則系統會傳回 BadValueError 例外狀況。

您可以與其他 Model 執行個體一樣,將新物件儲存至 Datastore,例如呼叫 put() 方法。該物件會保留建立通訊協定緩衝區時擁有的金鑰。若 Datastore 中已有具備該金鑰的物件,則儲存去序列化的物件會覆寫既有物件。

注意:如果物件的金鑰使用系統指派的 ID,且該 ID 尚未分配給指定的路徑和種類,便會成功儲存,但不會保存 ID。未來建立的物件可能會分配到該 ID,且會覆寫先前的物件。為確保安全,請只在物件序列化時所在的應用程式中還原物件。

model_is_projection (model_instance)

如果您指定的查詢 (model_instance) 是投影查詢 (而非完整實體查詢),則系統會傳回 True

引數

model_instance
您正在檢查是否為投影查詢的查詢。

如果該查詢為投影查詢,便傳回 True。否則會傳回 False

put (models, deadline=60)

將一個或多個模型執行個體寫入 Datastore。

引數

models
這是要儲存的模型實例或模型實例的清單。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如果提供多個模型實例,這些模型實例可能會出現在多個實體群組中。

操作過程中如發生任何錯誤,即便實際上已刪除部分實體,仍會一律傳回例外狀況。如果呼叫傳回時沒有傳回例外狀況,則所有實體均已成功寫入。

如果 models 含有單一模型項目,這個函式會傳回相對應的金鑰物件。如果 models 是清單,傳回的值就會是相對應的金鑰物件清單。

注意事項:如果您在單一作業中寫入多個實體,我們並不保證會一次寫入所有實體,除非該項作業是在交易中執行。即便查詢以高同步一致性執行,其他查詢 Datastore 的程序也可能會得到不一致的結果。

put_async (models, deadline=60)

將一個或多個模型執行個體寫入 Datastore。

這個函式與 put() 幾乎相同,唯一的差異在於這個函式會傳回非同步物件。您可以對傳回值呼叫 get_result(),以便封鎖呼叫並傳回結果。

引數

models
這是要儲存的模型實例或模型實例的清單。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。

如果提供多個模型實例,這些模型實例可能會出現在多個實體群組中。

操作過程中如發生任何錯誤,即便實際上已刪除部分實體,仍會一律傳回例外狀況。如果呼叫傳回時沒有傳回例外狀況,則所有實體均已成功寫入。

這個函式會傳回非同步物件,該物件可用於呼叫 get_result()。傳回的結果與 put() 相同。

注意事項:如果您在單一作業中寫入多個實體,我們並不保證會一次寫入所有實體,除非該項作業是在交易中執行。即便查詢以高同步一致性執行,其他查詢 Datastore 的程序也可能會得到不一致的結果。

query_descendants (model_instance)

傳回針對某個模型實例所有下階進行的查詢。

引數

model_instance
您要尋找的下階所屬的模型實例。
run_in_transaction (function, *args, **kwargs)

在單一交易中執行含有 Datastore 更新的函式。如果任何程式碼在交易期間傳回例外狀況,便會復原交易期間的所有更新。或者,您也可以使用 @db.transactional() 修飾符。

引數

function
要執行的函式。
args
要傳送至函式的位置引數。
kwargs
要傳送至函式的關鍵字引數。

如果函式傳回值,則 run_in_transaction() 會將此值傳回至呼叫者。

如果函式傳回例外狀況,便會復原交易。如果例外狀況是 Rollback,系統就不會重新傳回。如為其他例外狀況,則會重新傳回至呼叫者。

針對交易,Datastore 使用樂觀鎖定和重試。如果無法修訂函式準備的交易,run_in_transaction() 便會再次呼叫函式,重試交易最多 3 次。如要設定不同的重試次數,請使用 run_in_transaction_custom_retries()。單一交易可多次呼叫交易函式,因此該函式示不應有副作用,包括修改引數。

如果無法修訂交易 (例如因為高爭用率),系統會傳回 TransactionFailedError 例外狀況。

from google.appengine.ext import db

class Counter(db.Model):
  name = db.StringProperty()
  count = db.IntegerProperty(default=0)

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:        # Don't let counter go negative
    raise db.Rollback()
  db.put(counter)

q = db.GqlQuery("SELECT * FROM Counter WHERE name = :1", "foo")
counter = q.get()
db.run_in_transaction(decrement, counter.key(), amount=5)
run_in_transaction_custom_retries (retries, function, *args, **kwargs)

在單一交易中執行含有 Datastore 更新的函式,並在爭用發生時依指定次數來重試交易。如果任何程式碼在交易期間傳回例外狀況,便會復原交易期間的所有更新。

除了能夠指定重試次數之外,這個函式的行為與 run_in_transaction() 相同。

引數

retries
實體群組內發生爭用 (亦即多個使用者同時嘗試修改該群組) 時,呼叫函式的次數上限。
function
要執行的函式。
args
要傳送至函式的位置引數。
kwargs
要傳送至函式的關鍵字引數。
run_in_transaction_options (options, function, *args, **kwargs)

使用交易選項物件指定的選項,在單一交易中執行含有 Datastore 更新的函式。如果任何程式碼在交易期間傳回例外狀況,便會復原交易期間的所有 Datastore 更新。

如為跨群組 (XG) 交易,交易選項物件中的 xg 參數必須設為 True

引數

選項
包含此交易所用設定的交易選項物件。若要啟用 XG 交易,其中的 xg 參數應設為 True
function
要執行的函式。
args
要傳送至函式的位置引數。
kwargs
要傳送至函式的關鍵字引數。

如果函式傳回值,則 run_in_transaction_options() 會將此值傳回至呼叫者。

如果函式傳回例外狀況,便會復原交易。如果例外狀況是 Rollback,系統就不會重新傳回。如為其他例外狀況,則會重新傳回至呼叫者。

針對交易,Datastore 使用樂觀鎖定和重試。如果無法修訂函式準備的交易,run_in_transaction_options() 便會再次呼叫函式,重試交易次數會由交易選項物件指定。單一交易可多次呼叫交易函式,因此該函式不應有副作用,包括修改引數。

如果無法修訂交易 (例如因為高爭用率),便會傳回 TransactionFailedError 例外狀況。

以下範例顯示如何使用此函式執行跨群組交易

from google.appengine.ext import db

xg_options = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_options, my_txn)
to_dict (model_instance, dictionary=None)

建立並傳回模型執行個體的字典表示法。

引數

model_instance
要複製的模型執行個體。
dictionary
如果設定此值,應為合併模型資料的字典。模型值覆寫字典中的值;並保留與模型執行個體欄位不對應的字典項目。

修飾符

@db.transactional (propagation=ALLOWED, xg=False, retries=3, deadline=60)

讓函式在 db 交易中執行。因此,您可以呼叫 func(),而非 run_in_transaction(func)

引數

propagation
如果另一個交易呼叫此交易函式,則該如何處理:
允許
如果已在交易中,請繼續使用;如果不在交易中,請開始交易。

附註:如果使用此政策的函式擲回例外狀況,擷取例外狀況並修訂外部交易可能並不安全;該函式可能會讓外部交易呈現不良狀態。

必要
如果交易正在進行,則繼續執行。如果未進行交易,則傳回 BadRequestError 例外狀況。

附註:如果使用此政策的函式擲回例外狀況,擷取例外狀況並修訂外部交易可能並不安全;該函式可能會讓外部交易呈現不良狀態。

獨立
建立新的交易,暫停任何現有交易。

附註:使用此政策的函式不應傳回在新交易中讀取到的任何實體,因為實體在交易方面與外部交易並不一致。

巢狀
(尚不支援) 在既有交易中建立巢狀交易。
xg
如為 True,則允許跨群組 (XG) 交易。如果設為非布林值,則會傳送 BadArgumentError 例外狀況。
retries
交易修訂失敗時的重試次數。
deadline
在因錯誤而取消之前,等待 Datastore 傳回結果的秒數上限,可接受整數或浮點值。不得高於預設值 (60 秒),但可向下調整來確保特定作業快速失敗 (例如更快將回應傳回給使用者、重試作業、嘗試不同作業,或是將作業新增至工作佇列)。
@db.non_transactional (allow_existing=True)

確保函式即便在交易內呼叫,也會在 db 交易外執行。

引數

allow_existing
如為 True,則允許既有交易呼叫函式。如為 False,則傳回 BadRequestError 例外狀況。
本頁內容對您是否有任何幫助?請提供意見:

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

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