本頁面由 Cloud Translation API 翻譯而成。

透過 HTTPS (DoH) 使用 DNS 適用的 JSON API

過去，網頁應用程式需要瀏覽器擴充功能才能使用進階 DNS 功能，例如 DANE、DNS-SD 服務探索，甚至是解析 IP 位址以外的任何內容，例如 MX 記錄。如要使用 DNSSEC 依附功能 (例如 SSHFP 記錄)，這類擴充功能都必須自行驗證 DNSSEC，因為瀏覽器或 OS 可能無法執行。

自 2016 年起，Google 公用 DNS 便提供適用於 DoH 且具備 DNSSEC 驗證的 DoH 網路，且不需要瀏覽器或作業系統設定或擴充功能。簡單的 GET 查詢參數和 JSON 回應可讓用戶端使用常見的網路 API 剖析結果，並避免使用網域名稱指標壓縮等複雜的 DNS 訊息格式詳細資料。

請參閱一般 DoH 說明文件頁面，瞭解 DoH 的一般資訊，例如 HTTP 標頭、重新導向處理、隱私權最佳做法以及 HTTP 狀態碼。

「安全傳輸」頁面提供 DoH 的 curl 指令列範例，以及 DoH 和 DNS over TLS (DoT) 通用的資訊，例如 TLS 支援和 DNS 截斷。

JSON API 規格

所有 API 呼叫都是 HTTP GET 要求。如果有重複的參數，系統只會使用第一個值。

支援的參數

名稱

字串，必要

唯一的必要參數。系統接受 RFC 4343 反斜線逸出。

長度 (取代反斜線逸出後) 必須介於 1 到 253 之間 (如有選用的結尾點，系統會忽略這個結尾點)。
所有標籤 (點之間的名稱部分) 長度必須介於 1 到 63 位元組之間。
.example.com、example..com 等無效名稱，或是空字串 get 400 Bad Request。
非 ASCII 字元應採用 Puny 編碼 (xn--qxam，而非 ελ)。

類型

字串，預設值：1

RR 類型可以使用 [1, 65535] 的數字，或標準字串 (不區分大小寫，例如 A 或 aaaa) 表示。您可以在「ANY」查詢中使用 255，但請注意，這「不是」取代 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 主體中接收二進位 DNS 訊息，而非 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 記錄。

應用程式應一律處理 (並在必要時忽略) JSON 回應中的任何 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)。

EDNS

系統不支援一般的 EDNS 擴充功能機制。EDNS 用戶端子網路選項 (edns-client-subnet) 是 GET 要求中的參數，以及 JSON 回應中的頂層欄位。