金鑰類別

附註：我們強烈建議建構新應用程式的開發人員使用 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 模型提供關鍵屬性值的功能，例如自動解析。

建構函式

class Key(encoded=None)

資料儲存庫物件的唯一金鑰。

您可以將 Key 物件傳遞至 str()，將金鑰轉換為字串。字串為「urlsafe」，只使用可在網址中使用的字元。您可以將金鑰的字串表示法傳遞至 Key 建構函式 (encoded 引數)，藉此將金鑰轉換回 Key 物件。

注意：代表金鑰的字串看似為隱密內容，但實際上未經加密！它可轉換回原始的金鑰資料，包含種類與 ID。如果您不想將這類資料提供給使用者 (並讓他們輕易猜出其他實體的金鑰)，請對這些字串加密或使用其他內容。

encoded
Key 例項的 str 形式，可轉換回 Key。

類別方法

Key 類別提供的類別方法如下：

Key.from_path(*path, parent=None, namespace=None)

這會透過 (選用的) 祖系路徑 (位於現有的 Key 物件) 以及一或多個新路徑元件，建構出新的 Key 物件。每個路徑元件都包含類型名稱 (kind) 和 ID (id_or_name)，ID 可以是數字或字元字串。

路徑代表實體的父項與子項之間的關係階層。路徑中的所有實體都能夠以實體種類加上其數字 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
僅為此金鑰設定的命名空間。如果您在此提供命名空間，系統會覆寫 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。