Key 类

注意：强烈建议构建新应用的开发者使用 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, parent=None, namespace=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。