建立、擷取、更新及刪除實體

Datastore 中的資料物件又稱為「實體」。為方便查詢，每個實體會分門別類到特定的「種類」中。舉例來說，人力資源應用程式可以用 Employee 種類的實體來代表每位員工。請注意，實體資料值採屬性形式。如要進一步瞭解實體，請參閱祖系路徑和交易的說明文件。

建立實體及設定屬性

您可以透過呼叫實體模型類別的建構函式方法來建立及設定實體。如要進一步瞭解如何建立實體模型類別，請參閱建立及使用實體模型類別。

以下範例說明如何使用關鍵字引數叫用模型類別的建構函式：

sandy = Account(
    username='Sandy', userid=123, email='[email protected]')

此程式碼會在程式的主記憶體中建立一個物件。不過請注意，實體會在程序結束時消失，因此您還必須呼叫 put()，將實體儲存在 Datastore 中，如下所示：

sandy_key = sandy.put()

請注意，這會傳回一個金鑰，您稍後可以使用這個金鑰從 Datastore 擷取實體。

使用下列選項來設定屬性：

  • 使用關鍵字引數將實體屬性指定至建構函式： 
    sandy = Account(
    username='Sandy', userid=123, email='[email protected]')
  • 在實體建立後手動設定屬性： 
    sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = '[email protected]'
  • 使用 populate() 便利方法在一次操作中設定多個屬性：
    sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='[email protected]')

無論您選擇如何設定實體的屬性，屬性類型 (在本例中為 StringProperty 和 IntegerProperty) 都會強制執行類型檢查。

例如：

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
... 
sandy.username = 42  # raises an exception

從金鑰擷取實體

如果您有實體的索引鍵，就可以從 Datastore 擷取該實體：

sandy = sandy_key.get()

索引鍵方法 kind() 和 id() 會從索引鍵復原實體的種類和 ID：

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

您還可以使用實體金鑰來取得適合嵌入網址的編碼字串：

url_string = sandy_key.urlsafe()

這會產生 agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM 等結果，日後可用於重建金鑰並擷取原始實體：

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

請注意，安全網址字串雖然看似為隱密內容，但實際上未經加密！它很容易被解碼，並還原原始的實體種類和 ID：

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

您可以使用這類安全網址金鑰，但請勿使用任何機密資料 (例如電子郵件地址) 作為實體 ID。可能的解決方案是使用機密資料的雜湊做為 ID。這樣一來，可查看加密金鑰的第三方就無法利用這些金鑰收集電子郵件地址，但這不會阻止他們自行產生已知電子郵件地址的雜湊，並用於檢查該地址是否存在於 Datastore 中。

更新實體

如要更新現有實體，請從 Datastore 擷取實體、修改其屬性，然後再次儲存：

sandy = key.get()
sandy.email = '[email protected]'
sandy.put()

在這種情況下，您可以忽略 put() 傳回的值，因為實體鍵在更新時不會變更。

刪除實體

不再需要實體時，您可以使用鍵的 delete() 方法，將實體從 Datastore 中移除：

sandy.key.delete()

請注意，這是針對金鑰執行的作業，而非針對實體本身。它一律會傳回 None。

刪除大量實體

如果需要刪除大量的實體，建議您使用 Dataflow 大量刪除實體。

使用批次作業

您可以用單次呼叫處理一系列的實體或金鑰，而不用逐一執行呼叫 (例如運用迴圈重複執行呼叫)。這將會產生批次作業的遠端程序呼叫 (RPC)，而非個別實體的單獨遠端程序呼叫。

以下程式碼示範操作方式：

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

在上方的程式碼中，您將一個金鑰物件清單傳送至 ndb.get_multi，以便擷取批次中的多個實體；ndb.get_multi 會傳回一個實體物件清單，而在 Datastore 中沒有對應實體的金鑰則會傳回 None 值。以這種方式取得實體，可減少對整個批次的 Datastore 呼叫次數。(每批次的呼叫次數取決於批次的大小設定)。