8. 访问资源

传统上，AWX 使用主键来访问单个资源对象。命名 URL 功能允许您通过特定于资源的人类可读标识符访问 AWX 资源。例如，通过 URL 路径 /api/v2/hosts/host_name++inv_name++org_name/ 的命名 URL 允许您在没有辅助查询字符串的情况下访问资源对象。

8.1. 配置设置

在 /api/v2/settings/named-url/ 下提供了两个与命名 URL 相关的配置设置：NAMED_URL_FORMATS 和 NAMED_URL_GRAPH_NODES。

NAMED_URL_FORMATS 是所有可用命名 URL 标识符格式的只读键值对列表。典型的 NAMED_URL_FORMATS 如下所示

"NAMED_URL_FORMATS": {
"organizations": "<name>",
"teams": "<name>++<organization.name>",
"credential_types": "<name>+<kind>",
"credentials": "<name>++<credential_type.name>+<credential_type.kind>++<organization.name>",
"notification_templates": "<name>++<organization.name>",
"job_templates": "<name>++<organization.name>",
"projects": "<name>++<organization.name>",
"inventories": "<name>++<organization.name>",
"hosts": "<name>++<inventory.name>++<organization.name>",
"groups": "<name>++<inventory.name>++<organization.name>",
"inventory_sources": "<name>++<inventory.name>++<organization.name>",
"inventory_scripts": "<name>++<organization.name>",
"instance_groups": "<name>",
"labels": "<name>++<organization.name>",
"workflow_job_templates": "<name>++<organization.name>",
"workflow_job_template_nodes": "<identifier>++<workflow_job_template.name>++<organization.name>",
"applications": "<name>++<organization.name>",
"users": "<username>",
"instances": "<hostname>"
}

对于 NAMED_URL_FORMATS 中的每个项目，键是具有命名 URL 的资源的 API 名称，值是指示如何为该资源形成人类可读的唯一标识符的字符串。 NAMED_URL_FORMATS 独占列出每个可以具有命名 URL 的资源，任何未列出的资源都没有命名 URL。如果资源可以具有命名 URL，则其对象应具有一个名为 named_url 的字段，该字段表示特定于对象的命名 URL。该字段应仅在详细信息视图下可见，而不在列表视图下可见。您可以使用准确生成的命名 URL 访问指定的资源对象。这不仅包括对象本身，还包括其相关 URL。例如，如果 /api/v2/res_name/obj_slug/ 有效，则 /api/v2/res_name/obj_slug/related_res_name/ 也应有效。

NAMED_URL_FORMATS 足以指导构成人类可读的唯一标识符和命名 URL 本身。为了方便使用，每个可以具有命名 URL 的资源对象都将具有一个名为 named_url 的相关字段，该字段显示该对象的命名 URL。您可以复制并粘贴该字段以供您自己的自定义使用。如果资源对象具有命名 URL，还可以参考 API 浏览器 的帮助文本以获取更多指导。

假设您想手动确定 ID 为 5 的标签的命名 URL。使用 NAMED_URL_FORMATS 为此特定资源对象构成命名 URL 的典型过程是首先查找 NAMED_URL_FORMATS 的标签字段以获取标识符格式 <name>++<organization.name>

  • URL 格式的第一部分是 <name>，它指示可以在 /api/v2/labels/5/ 中找到标签资源详细信息，并在返回的 JSON 中查找 name 字段。假设您的 name 字段的值为“Foo”，那么唯一标识符的第一部分就是**Foo**。

  • 格式的第二部分是双加号 ++。它是分隔唯一标识符不同部分的定界符。将它们追加到唯一标识符以获取 **Foo++**

  • 格式的第三部分是 <organization.name>，它指示该字段不在正在调查的当前标签对象中，而是在标签对象指向的组织中。因此，如格式所示，请在当前返回的 JSON 的相关字段中查找组织。该字段可能存在也可能不存在。如果它存在，请按照该字段中给出的 URL（例如 /api/v2/organizations/3/）获取特定组织的详细信息，提取其 name 字段（例如“Default”），并将其追加到我们当前的唯一标识符中。由于 <organizations.name> 是格式的最后部分，因此生成的结果命名 URL 为：/api/v2/labels/Foo++Default/。在组织不存在于标签对象详细信息的相关字段的情况下，请改为追加空字符串，这实际上不会改变当前标识符。因此，Foo++ 成为最终的唯一标识符，生成的结果命名 URL 成为 /api/v2/labels/Foo++/。

为命名 URL 生成唯一标识符的一个重要方面与保留字符有关。因为标识符是 URL 的一部分，所以 URL 标准保留的以下字符由百分比符号编码：;/?:@=&[]。例如，如果组织的名称为 ;/?:@=&[]，则其唯一标识符应为 %3B%2F%3F%3A%40%3D%26%5B%5D。另一个特殊的保留字符是 +，它不受 URL 标准保留，但由命名 URL 用于链接标识符的不同部分。它由 [+] 编码。例如，如果组织的名称为 [+]，则其唯一标识符为 %5B[+]%5D，其中原始的 [ 和 ] 是百分比编码，而 + 转换为 [+]。

虽然 NAMED_URL_FORMATS 无法手动修改，但修改会自动发生并在一段时间内扩展，反映底层资源的修改和扩展。请咨询您要使用命名 URL 功能的同一集群上的 NAMED_URL_FORMATS。

NAMED_URL_GRAPH_NODES 是另一个只读的键值对列表，它公开用于管理命名 URL 的内部图数据结构。它不打算让人类可读，而应用于以编程方式生成命名 URL。使用 NAMED_URL_GRAPH_NODES 提供的信息，在给定任意资源对象的主键的情况下生成命名 URL 的示例脚本可以在 GitHub 上找到，地址为：https://github.com/ansible/awx/blob/devel/tools/scripts/pk_to_named_url.py.

8.2. 标识符格式协议

资源可以通过其唯一键来识别，这些键基本上是资源字段的元组。每个资源都保证只有一个主键号码作为唯一键，但可能存在多个其他唯一键。因此，如果资源包含至少一个满足以下规则的唯一键，则资源可以生成标识符格式，从而具有命名 URL

  1. 该键必须仅包含 name 字段或具有有限数量的可能选择（如凭据类型资源的 kind 字段）的文本字段。

  2. 唯一允许的例外字段是违反规则 #1 的多对一相关字段，该字段与自身以外的资源相关，也允许具有 slug。

假设存在资源 Foo 和 Bar，Foo 和 Bar 都包含一个 name 字段和一个 choice 字段，该字段只能具有值“yes”或“no”。此外，资源 Foo 包含一个与 Bar 相关的多对一字段（外键），例如 fk。 Foo 具有一个唯一键元组 (name, choice, fk)，而 Bar 具有一个唯一键元组 (name, choice)。 Bar 可以具有命名 URL，因为它满足上面的规则 #1。 Foo 也可以具有命名 URL，即使它违反了规则 #1，违反规则 #1 的额外字段是 fk 字段，它与 Bar 相关且 Bar 可以具有命名 URL。

对于满足上述规则 #1 的资源，它们的人类可读唯一标识符是由外键字段组合而成，以 + 分隔。具体来说，上面示例中的资源 Bar 将具有 <name>+<choice> 的 slug 格式。请注意，slug 格式中的字段顺序很重要：name 字段始终位于首位（如果存在），之后是所有其他字段，按照字段名称的字典顺序排列。例如，如果 Bar 还有一个满足规则 #1 的 a_choice 字段，并且唯一键变为 (name, choice, a_choice)，则其 slug 格式变为 <name>+<a_choice>+<choice>。

对于满足上述规则 #2 的资源，如果通过额外的外键字段追溯回去，结果将是一棵资源树，它们共同标识了该资源的对象。为了生成标识符格式，回溯树中的每个资源都使用前面描述的方式生成其自身的独立格式部分，使用所有字段，除了外键。最后，所有部分按以下顺序用 ++ 组合在一起

  • 将独立格式作为第一个标识符组件。

  • 递归地为每个资源生成唯一标识符。基础资源使用外键指向（回溯树节点的子节点）。

  • 将生成的唯一标识符视为标识符组件的其余部分。按照对应外键的字典顺序对它们进行排序。

  • 使用 ++ 将所有组件组合在一起以生成最终的标识符格式。

参考上面的示例，当为资源 Foo 生成标识符格式时，AWX 生成独立格式，<name>+<choice> 用于 Foo，<fk.name>+<fk.choice> 用于 Bar，然后将它们组合在一起得到 <name>+<choice>++<fk.name>+<fk.choice>。

当根据给定的标识符格式生成标识符时，有些情况下外键可能指向无处。在这种情况下，AWX 将外键应该指向的资源的格式部分替换为空字符串 ‘'。例如，如果一个 Foo 对象的名称 = 'alice'，选择 = 'yes'，但 fk 字段 = None，则其生成的标识符将为 alice+yes++。