被遮蔽的记录

当您向 zone 添加 NS 记录时，您创建了子域名委派：您将该子域名（及其下方的一切）的权威委派给另一组 nameserver。您在该委派点或其下方保留的任何记录都被遮蔽。它仍存储在您的 zone 中，但委派将该名称的权威交给了被委派的 nameserver，因此该记录不属于您的 zone 应提供的权威数据。

遮蔽元数据会告诉您哪些记录被遮蔽、哪些 NS 记录进行了遮蔽，以及每个委派遮蔽了多少条记录。它作为 API 响应上的字段和 Cloudflare 仪表板中的警告公开，除非您显式请求，否则不会返回。

由于委派将子域名的权威转移到其他地方，您在其处或其下方放置的任何记录都不是权威的，即使它仍出现在您的 zone 中。请考虑此示例：

sub.example.com      NS  ns1.example.org.
www.sub.example.com  A   192.0.2.1

sub.example.com 处的 NS 委派将包括 www.sub.example.com 在内的其处或其下方的一切权威委派给外部 nameserver。那些 nameserver（而不是您的 zone）负责应答该名称，因此您在此处添加的 A 记录不是 www.sub.example.com 的权威记录。

问题在两个方向上都成立。添加 NS 委派可能遮蔽您已经依赖的记录，而在现有委派下添加记录会产生您的 zone 不再具有权威性的记录。这两种情况下都不会返回错误，这正是遮蔽元数据有助于发现问题的原因。

被遮蔽的记录恰好以两种方式产生：

• 您在已存在于该名称或其下方的记录之上添加了委派，例如将子域名指向外部提供商但保留原始记录。
• 您在已委派的名称或其下方添加了记录，例如期望它们从父 zone 解析。

Glue 记录是某些委派为正常工作所需的 A 或 AAAA 记录。仅当委派的 nameserver 主机名落在被委派的 zone 本身内时才需要 glue。大多数委派指向不同 zone 中的 nameserver（例如，sub.example.com 的委派指向 ns1.example.org），并且不需要 glue，因为解析器可以独立查找这些 nameserver。在 zone 内的情况下若没有 glue，询问“ns1.sub.example.com 在哪里？”的解析器将跟随 sub.example.com 的委派——而在它已经知道 ns1.sub.example.com 之前无法到达该委派。这是一个循环依赖。

请考虑此示例：

sub.example.com      NS  ns1.sub.example.com.
ns1.sub.example.com  A   192.0.2.1

ns1.sub.example.com 的 A 记录是 glue。它被遮蔽（sub.example.com 委派先生效），但仍会被提供。父 zone 将其包含在引用响应的附加部分中，与 NS 委派一起，以便解析器可以引导子域名查找，而不会陷入循环依赖。

Glue 仅对 A 和 AAAA 记录有意义。与 NS 目标同名的 CNAME 记录不会被视为 glue。

当更浅的委派取得本应由 glue 支持的名称的权威时，glue 记录会变得无法访问。更浅的委派（更接近 zone apex、名称中标签更少的委派）取得其下方一切的权威，因此您的 zone 即使在引用的附加部分中也无法提供该 glue。API 将这些记录报告为 dead_glue: true。

请考虑此示例：

sub.example.com        NS  ns1.sub.example.com.
a.sub.example.com      NS  ns1.a.sub.example.com.
ns1.a.sub.example.com  A   192.0.2.1

ns1.a.sub.example.com 的 A 记录看起来像是 a.sub 委派的 glue。但是，更浅的 sub.example.com 委派取得 sub.example.com 下一切的权威，包括 a.sub.example.com。您的 zone 权威止于该更浅委派，因此 ns1.a.sub.example.com 的 glue 在其之外，永远不会被提供。

无法访问的 glue 不会导致解析失败。它要么是您可以安全移除的残留，要么表明更浅的委派是错误创建的。

适用时，遮蔽元数据字段会返回在每条记录的 meta 对象中。它们在读取时按需计算，从不存储。

类型：字符串数组（记录 ID）

出现在被一个或多个 NS 委派隐藏的任何记录上。该数组包含其委派遮蔽此记录的 NS 记录的 ID。当多条 NS 记录共享同一委派名称，或在记录上方不止一个父级别存在委派时，会出现多个 ID。

shadowed_by 始终出现在 glue 记录上，因为 glue 记录按定义被遮蔽。

Apex 记录（名称等于 zone 名称的记录）永远不会被遮蔽，也永远不会携带此字段。

与委派同名的 NS 记录不被视为被该委派遮蔽——它就是该委派。仅当更浅的父级别存在委派时，它才可能携带 shadowed_by。

类型：布尔值

出现在名称与遮蔽它们的某条 NS 记录目标匹配的 A 或 AAAA 记录上，并设为 true。这些记录是委派所需的 glue。即使它们被遮蔽，仍会被提供：父 zone 将它们包含在引用响应的附加部分中，以便解析器可以到达被委派的 nameserver。

当记录不是 glue 时，会省略此字段。

类型：布尔值

出现在实际上永远不会被提供的 glue 记录上，并设为 true，因为更浅的委派在 zone 能够应答该名称之前拦截了权威。带有 dead_glue: true 的记录也携带 is_glue: true。

当记录是有效 glue 或根本不是 glue 时，会省略此字段。

类型：整数

出现在形成委派的非 apex NS 记录上。报告该委派遮蔽了 zone 中多少条记录（位于委派名称或其下方的记录，不包括委派自身的 NS 记录和隐藏记录）。

计数上限为 10,000。值为 10,000 表示“至少 10,000”。计数为零时省略该字段。

下表显示每个记录类型适用哪些遮蔽元数据字段：

将 include_shadow_metadata=true 添加到任何 DNS 记录 API 请求：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?include_shadow_metadata=true" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

遮蔽元数据在所有记录 API 响应中可用：单条记录读取、创建和更新响应、列表请求和批量请求。对于列表和批量请求，仅当页面或批次包含 1,000 条或更少记录时才计算遮蔽元数据。超过该限制的请求返回不含遮蔽元数据的记录。

要仅列出被特定委派遮蔽的记录，请将 shadowed_by_name 与 include_shadow_metadata=true 一起传递：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?include_shadow_metadata=true&shadowed_by_name=sub.example.com" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

该值必须是 zone 的子域名（不是 zone apex）。筛选器返回该名称或其下方的所有记录。恰好位于委派名称的 NS 记录被排除（它们形成委派，而不是被遮蔽的集合）。位于委派下方名称的 NS 记录——例如，按 sub.example.com 筛选时位于 a.sub.example.com 的进一步委派——本身被遮蔽并包含在内。

要查找遮蔽特定记录的 NS 委派，请传递 shadowing_name：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?shadowing_name=www.sub.example.com" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

筛选器返回所提供名称及其在 zone 内每个祖先名称处的 NS 记录，不包括 zone apex。在此示例中，API 搜索 www.sub.example.com 和 sub.example.com 处的 NS 记录。该值必须是 zone 的子域名（不是 zone apex）。

与 shadowed_by_name 不同，此筛选器不需要 include_shadow_metadata=true。

以下摘录显示了包含以下内容的 zone 中三条记录上的遮蔽元数据字段：

sub.example.com       NS    ns1.sub.example.com.
ns1.sub.example.com   A     192.0.2.1
www.sub.example.com   A     192.0.2.2

[
  {
    "type": "NS",
    "name": "sub.example.com",
    "content": "ns1.sub.example.com.",
    "meta": {
      "shadowed_records_count": 2
    }
  },
  {
    "type": "A",
    "name": "ns1.sub.example.com",
    "content": "192.0.2.1",
    "meta": {
      "shadowed_by": ["<NS_RECORD_ID>"],
      "is_glue": true
    }
  },
  {
    "type": "A",
    "name": "www.sub.example.com",
    "content": "192.0.2.2",
    "meta": {
      "shadowed_by": ["<NS_RECORD_ID>"]
    }
  }
]

该 NS 记录携带 shadowed_records_count: 2（有两条记录被它遮蔽）。Glue A 记录同时携带 shadowed_by 和 is_glue: true。非 glue A 记录仅携带 shadowed_by。