第 8 章 访问资源

/api/v2/settings/named-url/: NAMED_URL_FORMATS 和 NAMED_URL_GRAPH_NODES 下有两个与 named-URL 相关的配置设置。

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 的资源的每个对象都有 名为_url 的 相关字段，显示该对象的命名 URL。您可以复制并粘贴该字段，供您自己的自定义使用。如需更多信息，请参阅如果资源对象具有命名 URL，请参阅 API 浏览器的帮助文本。

您可以手动决定命名 URL 标签，例如使用 ID 5。要使用 NAMED_URL_FORMATS 来为这个特定资源对象编写命名 URL，请首先查找 NAMED_URL_FORMATS 的 labels 字段以获取标识符格式 <name> ++<organization.name > :

为命名 URL 生成唯一标识符的一个重要方面必须使用保留字符。因为标识符是 URL 的一部分，按 URL 标准对以下保留字符进行编码： ;/?:@=&[]。例如，如果机构命名为 ;/?:@=&[]，其唯一标识符应该是 %3B%2F%3F%3F%3A%40%3D%26%5B%5D。另一个特殊的保留字符是 +，它不由 URL 标准保留，而是使用命名 URL 来链接标识符的不同部分。它由 [+] 编码。例如，如果机构命名为 [+]，其唯一标识符为 %5B[+]%5D，其中原始 [ 和 ] 是编码的，则 + 转换为 [+]。

虽然您无法手动更改 NAMED_URL_FORMATS，但修改操作会随时间自动进行并扩展，以反映底层的资源修改和扩展。请参考您要使用命名 URL 功能的同一集群中的 NAMED_URL_FORMATS。

NAMED_URL_GRAPH_NODES 是另一个只读键值对列表，它公开用于管理命名 URL 的内部图形数据结构。这不是人类可读的，但必须用于以编程方式生成命名 URL。生成命名 URL 的示例脚本给出了任意资源对象的主键，其可以具有命名 URL，其使用 NAMED_URL_GRAPH_NODES 提供的信息，可在 GitHub 中找到。