此页面由 Cloud Translation API 翻译。

用于 DNS over HTTPS (DoH) 的 JSON API

以前，基于网络的应用需要浏览器扩展程序才能使用高级 DNS 功能（例如 DANE、DNS-SD 服务发现），甚至可以解析以及除 IP 地址之外的任何其他信息，例如 MX 记录如需使用依赖于 DNSSEC 的功能（如 SSHFP 记录），任何此类扩展程序必须自行验证 DNSSEC，因为浏览器或操作系统可能不会这样做。

自 2016 年以来，Google 公共 DNS 为 DoH 提供了适用于 DNSSEC 的 Web 版 API 验证不需要浏览器、操作系统配置或扩展程序。通过简单的 GET 查询参数和 JSON 响应，客户端可以解析使用通用 Web API 生成多份结果，并避免复杂的 DNS 消息格式详情，例如针对域名的指针压缩。

如需了解 DoH，请参阅常规 DoH 文档页面通常包括 HTTP 标头、重定向处理、隐私保护最佳实践和 HTTP 状态代码。

安全传输页面 curl 命令行示例 DoH，以及 DoH 和 DNS TLS (DoT)，例如 TLS 支持和 DNS 截断。

JSON API 规范

所有 API 调用都是 HTTP GET 请求。如果参数重复，则仅使用第一个值。

支持的参数

name

字符串，必需

唯一的必需参数。接受 RFC 4343 反斜杠转义。

长度（替换反斜杠转义后）必须介于 1 到 253 个（如果存在可选的尾随点，则忽略）。
所有标签（点之间的名称部分）的长度必须为 1 到 63 个字节。
无效名称（如 .example.com、example..com）或空字符串 get 400 Bad Request。
非 ASCII 字符应采用 Punycoding 编码（xn--qxam，而不是 ελ）。

类型

字符串，默认值：1

RR 类型可以表示为 [1, 65535] 中的一个数字或规范的字符串（不区分大小写，例如 A 或 aaaa）。您可以将 255 表示为“ANY”但要注意，这不是用于替代发送 A 记录和 AAAA 或 MX 记录的查询。权威域名服务器不需要返回此类查询的所有记录；一些代码不响应，而另一些代码（如 cloudflare.com）仅返回 HINFO。

cd

布尔值，默认值：false

CD（正在检查已停用）标志。使用 cd=1 或 cd=true 停用 DNSSEC 验证；使用 cd=0、cd=false 或不使用 cd 参数来启用 DNSSEC 验证。

个

字符串，默认：空

所需的内容类型选项。使用 ct=application/dns-message 在响应 HTTP 正文，而不是 JSON 文本。使用 ct=application/x-javascript 明确请求 JSON 文本。系统会忽略其他内容类型值，并返回默认 JSON 内容。

do

布尔值，默认值：false

DO (DNSSEC OK) 标志。使用 do=1 或 do=true 来包含 DNSSEC 记录（RRSIG、NSEC、NSEC3）；使用 do=0、do=false 或不使用 do 参数来省略 DNSSEC 记录。

应用应始终处理（必要时忽略）任何 DNSSEC 记录，因为其他实现可能始终包含这些记录，并且将来我们可能会更改 JSON 响应的默认行为。（二进制 DNS 消息响应始终遵循 DO 标志的值。）

edns_client_subnet

字符串，默认：空

edns0-client-subnet 选项。格式为带有子网掩码的 IP 地址。示例：1.2.3.4/24、2001:700:300::/48。

如果您出于隐私方面的考虑而使用 DNS-over-HTTPS，并且不希望要发送到权威域名服务器的 IP 地址的任意部分对于地理位置精确度，请使用 edns_client_subnet=0.0.0.0/0。 Google 公共 DNS 通常会发送大致的网络信息（通常将 IPv4 地址的最后一部分清零）。

random_padding

字符串，已忽略

系统会忽略此参数的值。示例：XmkMw~o_mgP2pf.gpw-Oi5dK。

API 客户端担心可能存在使用 HTTPS GET 请求的数据包大小可以据此使所有请求相同的大小。为避免对网址的错误解读，请限制内边距字符非预留的网址字符：大小写字母、数字、连字符、句点、下划线和波浪号。

JSON 格式的 DNS 响应

成功的响应（此处添加的注释不会在实际响应中出现）：

{
  "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
  "TC": false,  // Whether the response is truncated
  "RD": true,   // Always true for Google Public DNS
  "RA": true,   // Always true for Google Public DNS
  "AD": false,  // Whether all response data was validated with DNSSEC
  "CD": false,  // Whether the client asked to disable DNSSEC
  "Question":
  [
    {
      "name": "apple.com.",  // FQDN with trailing dot
      "type": 1              // A - Standard DNS RR type
    }
  ],
  "Answer":
  [
    {
      "name": "apple.com.",   // Always matches name in the Question section
      "type": 1,              // A - Standard DNS RR type
      "TTL": 3599,            // Record's time-to-live in seconds
      "data": "17.178.96.59"  // Data for A - IP address as text
    },
    {
      "name": "apple.com.",
      "type": 1,
      "TTL": 3599,
      "data": "17.172.224.47"
    },
    {
      "name": "apple.com.",
      "type": 1,
      "TTL": 3599,
      "data": "17.142.160.59"
    }
  ],
  "edns_client_subnet": "12.34.56.78/0"  // IP address / scope prefix-length
}

如需了解更多详情，请参阅 RFC 7871（EDNS 客户端子网）详细了解“作用域前缀长度”及其对缓存的影响

包含诊断信息的失败响应：

{
  "Status": 2,  // SERVFAIL - Standard DNS response code (32 bit integer).
  "TC": false,  // Whether the response is truncated
  "RD": true,   // Always true for Google Public DNS
  "RA": true,   // Always true for Google Public DNS
  "AD": false,  // Whether all response data was validated with DNSSEC
  "CD": false,  // Whether the client asked to disable DNSSEC
  "Question":
  [
    {
      "name": "dnssec-failed.org.",  // FQDN with trailing dot
      "type": 1                      // A - Standard DNS RR type
    }
  ],
  "Comment": "DNSSEC validation failure. Please check http://dnsviz.net/d/dnssec-failed.org/dnssec/."
}

带有嵌入式引号和域名服务器归因的 SPF 和 TXT 记录：

{
  "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
  "TC": false,  // Whether the response is truncated
  "RD": true,   // Always true for Google Public DNS
  "RA": true,   // Always true for Google Public DNS
  "AD": false,  // Whether all response data was validated with DNSSEC
  "CD": false,  // Whether the client asked to disable DNSSEC
  "Question": [
    {
      "name": "*.dns-example.info.",  // FQDN with trailing dot
      "type": 99                      // SPF - Standard DNS RR type
    }
  ],
  "Answer": [
    {
      "name": "*.dns-example.info.",   // Always matches name in Question
      "type": 99,                      // SPF - Standard DNS RR type
      "TTL": 21599,                    // Record's time-to-live in seconds
      "data": "\"v=spf1 -all\""        // Data for SPF - quoted string
    }
  ],
  "Comment": "Response from 216.239.38.110"
  // Uncached responses are attributed to the authoritative name server
}

{
  "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
  "TC": false,  // Whether the response is truncated
  "RD": true,   // Always true for Google Public DNS
  "RA": true,   // Always true for Google Public DNS
  "AD": false,  // Whether all response data was validated with DNSSEC
  "CD": false,  // Whether the client asked to disable DNSSEC
  "Question": [
    {
      "name": "s1024._domainkey.yahoo.com.", // FQDN with trailing dot
      "type": 16                             // TXT - Standard DNS RR type
    }
  ],
  "Answer": [
    {
      "name": "s1024._domainkey.yahoo.com.", // Always matches Question name
      "type": 16,                            // TXT - Standard DNS RR type
      "data": "\"k=rsa;  p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDrEee0Ri4Juz+QfiWYui/E9UGSXau/2P8LjnTD8V4Unn+2FAZVGE3kL23bzeoULYv4PeleB3gfm\"\"JiDJOKU3Ns5L4KJAUUHjFwDebt0NP+sBK0VKeTATL2Yr/S3bT/xhy+1xtj4RkdV7fVxTn56Lb4udUnwuxK4V5b5PdOKj/+XcwIDAQAB; n=A 1024 bit key;\""
      // Data for TXT - multiple quoted strings
    }
  ],
}

DNS 字符串

所有 TXT 记录均编码为单个 JSON 字符串，包括使用更长的 TXT 记录录制格式，例如 RFC 4408 (SPF) 或 RFC 4871 (DKIM)。

电子 DNS

常规的 EDNS 扩展机制不受支持。 EDNS 客户端子网选项 (edns-client-subnet) 是 GET 请求和 JSON 响应中的顶级字段。