附註:強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫,相較於此用戶端程式庫,NDB 用戶端程式庫有幾項優點,例如能透過 Memcache API 自動快取實體。如果您目前使用的是舊版 DB 用戶端程式庫,請參閱 DB 至 NDB 遷移指南
Key 類別的執行個體代表的是資料儲存庫實體的唯一金鑰。
Key
是由 google.appengine.ext.db
模組提供。
簡介
每個模型執行個體都有識別「金鑰」,提供執行個體的「實體種類」與唯一「ID」的資訊。 ID 可能為「金鑰名稱」的字串,由應用程式在執行個體建立時明確指派,或是整數的「數字 ID」,由 App Engine 在執行個體寫入 (put) 至資料儲存庫時自動指派。模型執行個體的
key()
方法會傳回執行個體的 Key
物件。如果執行個體未有指派金鑰,key()
會發出
NotSavedError
。
應用程式可使用 get() 函式擷取指定 Key 的模型執行個體。
Key 執行個體可能為資料儲存庫實體屬性值,包括 Expando 動態屬性以及 ListProperty 成員。ReferenceProperty 模型可針對 Key 屬性值提供自動反參考之類的相關功能。
建構函式
- class Key(encoded=None)
-
資料儲存庫物件的唯一金鑰。
可透過將 Key 物件傳送至
str()
的方式,將金鑰轉換為字串。該字串具備「安全網址」的特性,僅會採用網址可以使用的有效字元。將代表金鑰的字串傳送至 Key 建構函式 (encoded 引數),即可轉換回 Key 物件。注意:代表金鑰的字串看似為隱密內容,但實際上未經加密!它可轉換回原始的金鑰資料,包含種類與 ID。如果您不想將這些資料暴露給使用者知道 (並讓使用者輕鬆猜到其他實體的金鑰),那麼請為這些字串加密,或是改用其他項目。
- encoded
- 將
str
格式的 Key 執行個體轉換回金鑰。
類別方法
Key 類別提供的類別方法如下:
- Key.from_path(*path, parent=None, namespace=None)
-
這會透過 (選用的) 祖系路徑 (位於現有的 Key 物件) 以及一或多個新路徑元件,建構出新的 Key 物件。每個路徑元件都是由種類名稱 (
kind
) 與 ID (id_or_name
) 組成,為數字或字元的字串。路徑代表實體的父項與子項之間的關係階層。路徑中的所有實體都能夠以實體種類加上其數字 ID 或其金鑰名稱來表示。完整路徑代表出現在路徑最後的實體,而且其祖系 (父項) 為之前的實體。
舉例來說,下列呼叫會在父項金鑰
User/Boris
下方,針對種類為Address
且數字 ID 為9876
的實體建立金鑰。k = Key.from_path('User', 'Boris', 'Address', 9876)
另一個建立相同金鑰的方法如下:
p1 = Key.from_path('User', 'Boris') k = Key.from_path('Address', 9876, parent=p1)
如要進一步瞭解路徑的相關資訊,請參閱實體、屬性和金鑰頁面。
引數
- path
- 一或多個祖系路徑元件的清單,其中每個元件都是由種類和 ID 組成:
- 種類 — 實體種類,以字串或 Unicode 字串表示。
- ID —
id
,以字串或長整數指定。不可為數字 0。
- namespace=None
- 僅供用來設定此 Key 的命名空間。如果在這裡提供命名空間,則會覆寫目前在 namespace_manager 中設定的命名空間。如果為
None
,API 會透過 namespace_manager.get_namespace 使用目前的命名空間。 - parent=None
- 選用的父項金鑰。如未提供,則預設為
None
。
執行個體方法
Key 執行個體的方法如下:
- app()
-
傳回儲存資料實體的應用程式名稱。
- has_id_or_name()
-
如果實體具有名稱或數字 ID,則傳回
True
。 - id()
-
以整數形式傳回資料實體的數字 ID;如果實體沒有數字 ID,則傳回
None
。 - id_or_name()
-
傳回資料實體的名稱或數字 ID;如果實體沒有名稱也沒有數字 ID,則傳回
None
。 - kind()
-
以字串形式傳回資料實體的種類。
- name()
-
傳回資料實體的名稱;如果實體沒有名稱,則傳回
None
。 - namespace()
-
傳回資料實體的命名空間。如果實體目前沒有命名空間,則此方法會傳回目前在 namespace_manager 中設定的命名空間。
- parent()
-
傳回資料實體的父系實體金鑰;如果實體沒有父項,則傳回
None
。