此页面由 Cloud Translation API 翻译。

组件 ID 索引

术语

范围

本文档介绍了如何定义一个索引，将实例 ID 映射到标识名。对于使用隔离存储功能的组件，此映射至关重要。

概览

组件实例 ID 索引的目标是为组件实例分配稳定的标识符。为此，您需要将实例 ID 映射到标识名。为组件实例分配 ID 后，系统会使用此实例 ID 在磁盘上标识其永久性资源。这样，您就可以更改组件的网址或令牌网域，同时其资源仍归该组件所有（前提是此索引也更新）。

当组件运行时发现实例 ID -> 标识符映射时，它会自动将组件实例的现有存储目录移至其实例 ID 下的键值对下。

只有使用存储功能的组件才必须包含在索引中。索引中不应包含测试组件。

定义新索引

索引文件是采用 JSON5 格式的文件，用于将组件的实例 ID 映射到其标识名。构建树中可能有多个索引文件，但它们会合并为一个索引文件，并且此合并文件将提供给组件运行时。此合并后的索引文件不可变，只能通过其他系统更新进行更新。

以下示例介绍了索引文件的架构：

// Index files are written in JSON5, so you may use comments!
{
  // A list of entries, where each entry maps an instance ID to a moniker.
  instances: [
    // An entry, mapping an instance ID to a moniker.
    {
      // Instance IDs are randomly generated, 256-bits of base-16 encoded
      // strings (in lower case). To generate a new instance ID, set this to
      // an empty string (or other invalid value) and run the build; the build
      // will fail and suggest a new instance ID which you can copy-paste here.
      instance_id: "2bd6cc2bd10243354b873a4ddb8a188b1d29171e26eebac06567bcdc36614af6",
      // The `instance_id` above is associated to the following moniker:
      moniker: "/core/account/credential_manager",
    },

    // More than one entry can be included. However, all entries must be distinct:
    // * Two entries cannot reference the same `instance_id`
    // * Two entries cannot reference the same `moniker`
    {
      instance_id: "7db7e88479772e241229682b47f1794e12ac5d692f8d67421acd9d7ff318a975",
      moniker: "/core/account/password_authenticator",
    }
  ]
}

如需向 build 提供索引文件，请使用 component_id_index() GN 模板：

component_id_index("my_component_id_index") {
  source = "my_component_id_index.json5"
}

向索引添加组件

找到相应的索引文件

如需向索引添加组件，您必须将条目插入相应的索引文件中。目前，fuchsia.git 的组件已列在 core_component_id_index.json5 索引文件中。

向索引添加条目

第一步是确定组件实例的标识名。您可以通过运行 ffx component show 来查找特定产品的 eng build 中组件的别名。

然后，使用组件的标识符将条目附加到 instances 列表。将 instance_id 字段设置为无效值（例如空字符串），以使 build 失败并建议您可以使用的新值。

示例

在此示例中，组件 fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm 会添加到索引中。

如需确定组件实例的标识名，您可以运行 ffx component show fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm：

$ ffx component show fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm
               Moniker:  /core/my_other_component
                   URL:  fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm
                      ...

上述输出显示此实例的标识名为 /core/my_other_component

将此条目附加到 core_component_id_index.json5 的 instances 列表（并使用无效的空 instance_id），将 /core/my_other_component 添加到索引：

  {
    instance_id: "",
    moniker: "/core/my_other_component"
  }

现在运行 build。构建将失败，并建议使用新的实例 ID：

$ fx build
.
.
Product Assembly Failed
    ...
    4.  parsing obj/bundles/assembly/resources/core_component_id_index.json5
    5.  Invalid instance ID: invalid length; must be 64 characters

Here is a valid, randomly generated ID: 4251833a8d2e47b473732a23de84437e0b346a151ec1e7bdfd43b91e02f894a7

复制建议的 instance_id 字段，更新您添加的条目。现在，构建应该会通过。

在系统汇编中添加组件 ID 索引

本部分的目标受众群体是设置系统汇编的产品所有者

本部分介绍了如何在系统汇编中添加组件 ID 索引。

如果系统汇编包含使用独立存储空间的组件，则应包含组件 ID 索引。基于 core 产品构建的任何产品其汇编中都已包含组件 ID 索引，因此可能不需要遵循以下说明。

系统 build 中的所有 component_id_index() 都使用 component_id_index_config() 模板合并在一起。此模板目前在 assembled_system.gni 中使用，如果您在 assembled_system.gni 中定义自己的模板，则会导致汇编失败。

步骤

定义您希望包含在系统中的所有 component_id_index()。
在 assembled_system() 目标中将这些目标添加为 base_packages 的依赖项。