创建和使用实体键

Datastore 中的每个实体都有一个唯一标识它的键。键由以下部分组成：

  • 实体的命名空间，可实现多租户
  • 实体所属的种类，用于对实体进行分类以执行 Datastore 查询
  • （可选）祖先路径，用于在 Datastore 层次结构中确定实体的位置。

  • 具体实体的标识符，可以是下面任意一种

    • 键名字符串
    • 整数数字 ID

标识符是实体键的一部分，因此与实体永久关联且不可更改。您可以通过下述两种方式分配标识符：

  • 为实体指定自己的“键名”字符串。
  • 让 Datastore 自动为实体分配一个整数数字 ID。

指定实体的键名

如需为实体分配键名，请将一个非空 stringID 参数提供给 datastore.NewKey：

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

如需让 Datastore 自动分配数字 ID，请使用空的 stringID 参数：

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

分配标识符

您可以通过两项不同的自动 ID 政策配置 Datastore，使其生成自动 ID：

  • default 政策会生成大致均匀分布的未使用 ID 的随机序列。每个 ID 最多可包含 16 位十进制数字。
  • legacy 政策会创建一系列不连续的较小整数 ID。

如果希望向用户显示实体 ID 和/或按照顺序显示实体 ID，最好是使用手动分配。

使用祖先实体路径

Cloud Datastore 中的实体形成一个与文件系统目录结构类似的层级结构空间。创建实体时，您可选择指定另一实体作为其父实体；新实体是父实体的子实体（请注意，与文件系统不同，无需实际存在父实体）。没有父实体的实体是根实体。实体与其父实体之间的关联是永久的，实体创建后就无法更改。Cloud Datastore 绝不向父实体相同的两个实体分配同一数字 ID，也不分配给两个根实体（即没有父实体的实体）。

实体的父实体、父实体的父实体和以此类推得出的实体都是该实体的祖先实体；而实体的子实体和子实体的子实体等都是它的后代实体。根实体及其所有后代实体都属于同一个实体组。实体序列从根实体开始，接着从父实体到子实体，再指向给定的实体，这就构成了实体的祖先路径。识别实体的完整键由一系列种类/标识符对构成，它们指定实体的祖先路径并以实体自身的种类/标识符对终止。

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

对于根实体，祖先路径为空，且键仅由实体自身的种类和标识符组成：

[Person:GreatGrandpa]

此概念如下图所示：

显示实体组中的根实体与子实体的关系

如需指定实体的父实体，请将 parent 参数用于 datastore.NewKey。该参数的值应是父实体的键。以下示例将创建种类为 Address 的实体，并将 Employee 实体指定为其父实体：

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)