8. 访问资源¶

8.1. 配置设置¶

在 /api/v2/settings/named-url/ 下提供两个与命名 URL 相关的 Tower 配置设置

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 字段。假设您有值为 'Foo' 的 name 字段，则唯一标识符的第一部分是 **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 功能的同一个 Tower 集群上的 NAMED_URL_FORMATS。

NAMED_URL_GRAPH_NODES 是另一个只读的键值对列表，它公开 Tower 用于管理命名 URL 的内部图形数据结构。这并非旨在供人类阅读，而应用于以编程方式生成命名 URL。可以使用 NAMED_URL_GRAPH_NODES 提供的信息，在 GitHub 上找到一个示例脚本，用于生成给定任意可以具有命名 URL 的资源对象的（主键）的命名 URL，可在 GitHub 上找到：https://github.com/ansible/awx/blob/devel/tools/scripts/pk_to_named_url.py。

8.2. 标识符格式协议¶

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

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

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

假设 Tower 有资源 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 生成标识符格式时，Tower 为 Foo 生成独立格式 <name>+<choice>，为 Bar 生成独立格式 <fk.name>+<fk.choice>，然后将它们组合在一起形成 <name>+<choice>++<fk.name>+<fk.choice>。

当根据给定的标识符格式生成标识符时，外键可能指向任何地方的情况。在这种情况下，Tower 会用一个空字符串 “” 替换对应于外键应指向的资源的格式部分。例如，如果一个 Foo 对象具有 name =’alice’，choice =’yes’，但 fk 字段 = None，其生成的标识符将为 alice+yes++。