注意:强烈建议构建新应用的开发者使用 NDB 客户端库,它与 DB 客户端库相比具有多项优势,例如可通过 Memcache API 进行自动实体缓存。如果您当前使用的是较早的 DB 客户端库,请参阅 DB 到 NDB 的迁移指南
Key 类的实例代表数据存储区实体的唯一键。
Key
由 google.appengine.ext.db
模块提供。
简介
每个模型实例都具有一个标识键,其中包含实例的实体种类以及唯一标识符。标识符可以是创建实例时由应用显式分配的键名字符串,也可以是将实例写入 (put) Datastore 时由 App Engine 自动分配的整数 ID。模型实例的
key()
方法会返回该实例的 Key
对象。如果尚未向实例分配键,调用 key()
会引发
NotSavedError
。
应用可以使用 get() 函数来检索给定 Key 的模型实例。
Key 实例可以是 Datastore 实体属性的值,包括 Expando 动态属性和 ListProperty 成员。ReferenceProperty 模型为 Key 属性值提供自动解引用等功能。
构造函数
- class Key(encoded=None)
-
数据存储区对象的唯一键。
键可以转换为字符串,只需将 Key 对象传递给
str()
即可。 字符串为“urlsafe”,仅使用适合在网址中使用的字符。键的字符串表示形式可以转换回为 Key 对象,只需将其传递给 Key 构造函数(encoded 参数)即可。注意:键的字符串表示形式看起来已加密,但实际未加密!它可以转换为原始键数据,包括种类和标识符。如果您不希望向用户公开此数据(让他们能轻松猜出其他实体的键),请对这些字符串进行加密,或者使用其他内容。
- encoded
- 可以转换回 Key 的 Key 实例的
str
形式。
类方法
Key 类提供以下类方法:
- Key.from_path(*path, *path=None, *path=None)
-
可通过(可选)祖先路径(在现有 Key 对象中)及一个或多个新路径组件构建新的 Key 对象。每个路径组件都由种类名称 (
kind
) 和标识符 (id_or_name
) 组成,此标识符为数字或字符串。路径代表实体的父子关系的层次结构。路径中的每个实体都由实体的种类及其数字 ID 或其键名称表示。完整路径代表路径中最后显示的实体,其祖先(父项)作为前续实体。
例如,以下调用会根据父键
User/Boris
为种类为Address
并且数字 ID 为9876
的实体创建一个 Key:k = Key.from_path('User', 'Boris', 'Address', 9876)
创建相同 Key 的另一种方法如下所示:
p1 = Key.from_path('User', 'Boris') k = Key.from_path('Address', 9876, parent=p1)
如需详细了解路径,请参阅实体、属性和键页面。
参数
- path
- 一个或多个祖先路径组件的列表,其中每个组件由种类和标识符组成:
- 种类 - 实体种类,以字符串或 Unicode 字符串的形式表示。
- 标识符 -
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
。