シャドウされたレコード

ゾーンに NS レコードを追加すると、サブドメイン委任が作られます。そのサブドメイン（とその下すべて）の権限を、別のネームサーバー群に委任します。委任地点およびその下に残したレコードは シャドウ されます。ゾーンには保存されたままですが、委任によりその名前の権限は委任先ネームサーバーに移るため、そのレコードはゾーンが提供すべき権威データには含まれません。

シャドウメタデータは、どのレコードがシャドウされているか、どの NS レコードがシャドウしているか、各委任が何件のレコードをシャドウしているかを示します。API 応答のフィールドと Cloudflare ダッシュボードの警告として公開され、明示的に要求しない限り返されません。

委任はサブドメインの権限を別の場所へ移すため、委任地点またはその下に置いたレコードは権威にはなりません。ゾーン上には表示されたままです。次の例を考えてください。

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

sub.example.com の NS 委任は、www.sub.example.com を含むその地点および下すべてについて、権限を外部ネームサーバーへ委任します。その名前に答える責任は、ゾーンではなくそれらのネームサーバーにあるため、ここで追加した A レコードは www.sub.example.com の権威レコードではありません。

問題は両方向に起きます。NS 委任を追加すると、すでに依存しているレコードがシャドウされることがあります。既存の委任の下にレコードを追加すると、ゾーンがもはや権威でないレコードができます。どちらの場合もエラーは返されないため、問題を見つけるにはシャドウメタデータが役立ちます。

シャドウされたレコードは、次の 2 通りでのみ発生します。

• すでにその名前またはその下にあったレコードの上に委任を追加した場合。たとえば、サブドメインを外部プロバイダーへ向けつつ、元のレコードを残したときです。
• すでに委任されている名前またはその下にレコードを追加した場合。たとえば、親ゾーンから解決されるつもりで追加したときです。

グルーレコードは、一部の委任が動作するために必要な A または AAAA レコードです。グルーが必要なのは、委任のネームサーバーホスト名が、委任されたゾーン自身の中にある場合だけです。ほとんどの委任は別ゾーンのネームサーバーを指します（たとえば sub.example.com の委任に対する ns1.example.org）。その場合、リゾルバーはそれらのネームサーバーを独立して調べられるため、グルーは不要です。ゾーン内の場合にグルーがないと、「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 レコードはグルーです。シャドウされています（sub.example.com の委任が先に効きます）が、それでも配信されます。親ゾーンは、NS 委任とあわせてリファーラル応答の additional セクションにこれを含めます。リゾルバーは循環依存で止まらずに、サブドメインの検索を開始できます。

グルーとして意味があるのは A と AAAA レコードだけです。NS ターゲットと同じ名前の CNAME レコードは、グルーとしては扱いません。

グルーが支えようとしている名前について、より浅い委任が権限を取ると、そのグルーレコードは到達不能になります。より浅い委任（ゾーン apex に近く、名前のラベル数が少ないもの）は、その下すべてについて権限を取るため、ゾーンはリファーラルの additional セクションでもグルーを配信できません。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 委任のグルーに見えます。しかし、より浅い sub.example.com の委任が a.sub.example.com を含む sub.example.com の下すべてについて権限を取ります。ゾーンの権限はその浅い委任で止まるため、ns1.a.sub.example.com のグルーはその外にあり、配信されません。

到達不能なグルーは、解決失敗の原因にはなりません。安全に削除できる残り物か、より浅い委任が誤って作られた合図かのどちらかです。

シャドウメタデータのフィールドは、該当する場合に各レコードの meta オブジェクトで返されます。読み取り時にオンデマンドで計算され、保存はされません。

型: 文字列の配列（レコード ID）

1 つ以上の NS 委任によって隠されているレコードに存在します。配列には、このレコードをシャドウする委任の NS レコードの ID が含まれます。同じ委任名を複数の NS レコードが共有する場合、またはレコードの上に複数の親レベルで委任がある場合に、複数の ID が現れます。

グルーレコードには、定義上シャドウされるため、常に shadowed_by があります。

apex レコード（名前がゾーン名と等しいレコード）はシャドウされず、このフィールドも持ちません。

委任と同じ名前の NS レコードは、その委任によってシャドウされたとはみなしません。それが委任そのものです。より浅い親レベルに委任がある場合にだけ、shadowed_by を持てます。

型: ブール値

名前が、自身をシャドウする NS レコードのいずれかのターゲットと一致する A または AAAA レコードで存在し、true になります。これらのレコードは、委任に必要なグルーです。シャドウされていても配信されます。親ゾーンは、リゾルバーが委任先ネームサーバーに到達できるように、リファーラル応答の additional セクションに含めます。

レコードがグルーでない場合、このフィールドは省略されます。

型: ブール値

より浅い委任が、ゾーンがその名前に答える前に権限を横取りするため、実際には配信されないグルーレコードで存在し、true になります。dead_glue: true のレコードは、is_glue: true も持ちます。

レコードが生きているグルーであるか、そもそもグルーでない場合、このフィールドは省略されます。

型: 整数

委任を形成する、apex 以外の NS レコードに存在します。その委任によってシャドウされるゾーン内のレコード数を報告します（委任名またはその下のレコード。委任自身の NS レコードと hidden レコードは除きます）。

件数の上限は 10,000 です。値が 10,000 のときは「少なくとも 10,000」を意味します。件数がゼロのときはフィールドは省略されます。

次の表は、各レコード種類にどのシャドウメタデータフィールドが適用されるかを示します。

任意の DNS records API リクエストに include_shadow_metadata=true を追加します。

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 件以下のときだけシャドウメタデータを計算します。その上限を超えるリクエストは、シャドウメタデータなしでレコードを返します。

特定の委任によってシャドウされたレコードだけを一覧するには、include_shadow_metadata=true とあわせて shadowed_by_name を渡します。

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"

値はゾーンのサブドメインである必要があります（ゾーン 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"

フィルターは、指定した名前と、ゾーン内の各祖先名にある NS レコードを返します。ゾーン apex は除きます。この例では、API は www.sub.example.com と sub.example.com の NS レコードを検索します。値はゾーンのサブドメインである必要があります（ゾーン apex ではありません）。

shadowed_by_name と異なり、このフィルターに include_shadow_metadata=true は不要です。

次は、次の内容を含むゾーンの 3 件のレコードについて、シャドウメタデータフィールドを示す抜粋です。

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 を持ちます（2 件のレコードがシャドウされます）。グルーの A レコードは shadowed_by と is_glue: true の両方を持ちます。グルーではない A レコードは shadowed_by だけを持ちます。