API JSON cho DNS qua HTTPS (DoH)
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Trước đây, các ứng dụng dựa trên web yêu cầu tiện ích của trình duyệt để sử dụng
Các tính năng DNS như DANE, Phát hiện dịch vụ DNS-SD hoặc thậm chí là để phân giải
bất kỳ thông tin nào khác ngoài địa chỉ IP – chẳng hạn như bản ghi MX.
Để sử dụng các tính năng phụ thuộc vào DNSSEC như bản ghi SSHFP, bất kỳ tiện ích nào như vậy
sẽ phải tự xác thực DNSSEC, vì trình duyệt hoặc hệ điều hành có thể không làm được việc này.
Từ năm 2016, Google Public DNS đã cung cấp một API thân thiện với web cho DoH sử dụng DNSSEC
không yêu cầu cấu hình trình duyệt hoặc hệ điều hành hoặc tiện ích.
Tham số truy vấn GET và phản hồi JSON đơn giản cho phép ứng dụng phân tích cú pháp
kết quả bằng cách sử dụng các API web phổ biến và tránh các chi tiết định dạng thông báo DNS phức tạp như
nén con trỏ cho tên miền.
Xem trang tài liệu chung của Bộ Tài chính và Nhà nước để biết thông tin về DoH
chẳng hạn như tiêu đề HTTP, xử lý lệnh chuyển hướng, các phương pháp hay nhất về quyền riêng tư và
Mã trạng thái HTTP.
Trang Vận chuyển an toàn có
Ví dụ về dòng lệnh curl cho DoH và thông tin chung với DoH và DNS qua
TLS (DoT), chẳng hạn như hỗ trợ TLS và cắt bớt DNS.
Thông số kỹ thuật của API JSON
Tất cả lệnh gọi API đều là yêu cầu HTTP GET.
Trong trường hợp tham số trùng lặp, chỉ giá trị đầu tiên được sử dụng.
Các tham số được hỗ trợ
- tên
chuỗi, bắt buộc
Tham số bắt buộc duy nhất. Chấp nhận ký tự thoát dấu gạch chéo ngược RFC 4343.
- Độ dài (sau khi thay thế các ký tự thoát dấu gạch chéo ngược) phải nằm trong khoảng từ 1 đến
253
(bỏ qua dấu chấm kèm theo không bắt buộc nếu có).
- Tất cả các nhãn (một phần của tên giữa các dấu chấm) phải dài từ 1 đến 63 byte.
- Các tên không hợp lệ như
.example.com, example..com hoặc chuỗi trống get
400 Yêu cầu không hợp lệ.
- Các ký tự không phải ASCII phải là punycoded (
xn--qxam, chứ không phải ελ).
- loại
chuỗi, mặc định: 1
Loại RR có thể được biểu thị dưới dạng một số trong [1, 65535] hoặc một chuỗi chuẩn
(không phân biệt chữ hoa chữ thường, chẳng hạn như A hoặc aaaa).
Bạn có thể sử dụng 255 cho "BẤT KỲ" nhưng xin lưu ý rằng đây không phải là một
thay thế để gửi truy vấn cho cả bản ghi A và AAAA hoặc MX.
Các máy chủ định danh có thẩm quyền không cần trả về tất cả bản ghi cho những truy vấn như vậy;
một số không phản hồi và một số khác (chẳng hạn như Cloudflare.com) chỉ trả về HINFO.
- cd
boolean, mặc định: false
Cờ CD (Checking Disabled (Kiểm tra đã tắt)).
Dùng cd=1 hoặc cd=true để tắt tính năng xác thực DNSSEC;
sử dụng cd=0, cd=false hoặc không dùng tham số cd để bật tính năng xác thực DNSSEC.
- đơn vị
chuỗi, mặc định: trống
Lựa chọn loại nội dung mong muốn.
Sử dụng ct=application/dns-message để nhận thông báo DNS nhị phân trong
phản hồi nội dung HTTP thay vì văn bản JSON.
Sử dụng ct=application/x-javascript để yêu cầu văn bản JSON một cách rõ ràng.
Các giá trị loại nội dung khác sẽ bị bỏ qua và nội dung JSON mặc định sẽ được trả về.
- làm
boolean, mặc định: false
Cờ DO (DNSSEC OK).
Sử dụng do=1 hoặc do=true để thêm các bản ghi DNSSEC (RRSIG, NSEC, NSEC3);
sử dụng do=0, do=false hoặc không dùng tham số do để bỏ qua các bản ghi DNSSEC.
Ứng dụng phải luôn xử lý (và bỏ qua, nếu cần) mọi DNSSEC
các bản ghi trong phản hồi JSON vì những cách triển khai khác luôn có thể bao gồm các bản ghi này,
và chúng tôi có thể thay đổi hành vi mặc định đối với phản hồi JSON trong tương lai.
(Phản hồi của thông báo DNS nhị phân luôn tuân theo giá trị của cờ DO.)
- edns_client_subnet
chuỗi, mặc định: trống
Tuỳ chọn edns0-client-subnet. Định dạng là địa chỉ IP có mặt nạ mạng con.
Ví dụ: 1.2.3.4/24, 2001:700:300::/48.
Nếu bạn đang sử dụng giao thức DNS-over-HTTPS do lo ngại về quyền riêng tư và không muốn
bất kỳ phần địa chỉ IP nào được gửi đến các máy chủ định danh có thẩm quyền
để biết độ chính xác của vị trí địa lý, hãy sử dụng edns_client_subnet=0.0.0.0/0.
DNS Google Public thường gửi thông tin mạng gần đúng
(thường bỏ trống phần cuối cùng của địa chỉ IPv4).
- random_padding
chuỗi, bị bỏ qua
Giá trị của thông số này sẽ bị bỏ qua. Ví dụ: XmkMw~o_mgP2pf.gpw-Oi5dK
Những ứng dụng API lo ngại về những cuộc tấn công quyền riêng tư kênh bên có thể có bằng cách sử dụng
kích thước gói của các yêu cầu GET HTTPS có thể dùng tính năng này để thực hiện chính xác tất cả các yêu cầu
có cùng kích thước theo các yêu cầu khoảng đệm với dữ liệu ngẫu nhiên.
Để tránh bị hiểu sai URL, hãy hạn chế các ký tự khoảng đệm
vào các ký tự URL không được dành riêng:
chữ hoa và chữ thường, chữ số, dấu gạch nối, dấu chấm, dấu gạch dưới và dấu ngã.
Phản hồi DNS trong JSON
Phản hồi thành công (những bình luận được thêm ở đây không có trong câu trả lời thực tế):
{
"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
}
Hãy xem bài viết RFC 7871 (Mạng con máy khách EDNS) để
thông tin chi tiết về "độ dài tiền tố phạm vi" và cách nó ảnh hưởng đến việc lưu vào bộ nhớ đệm.
Phản hồi lỗi kèm theo thông tin chẩn đoán:
{
"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/."
}
Các bản ghi SPF và TXT có dấu ngoặc kép được nhúng và thuộc tính máy chủ định danh:
{
"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
}
],
}
Chuỗi DNS
Tất cả bản ghi TXT đều được mã hoá dưới dạng một chuỗi JSON duy nhất, bao gồm cả việc sử dụng TXT dài hơn
ghi lại các định dạng như
RFC 4408 (SPF) hoặc
RFC 4871 (DKIM).
EDNS
Cơ chế mở rộng EDNS chung không được hỗ trợ.
Tuỳ chọn Mạng con máy khách EDNS (edns-client-subnet) là một thông số trong
Yêu cầu GET và trường cấp cao nhất trong phản hồi JSON.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-25 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-25 UTC."],[[["\u003cp\u003eGoogle Public DNS offers a web-friendly API for DNS-over-HTTPS (DoH) with DNSSEC validation, eliminating the need for browser extensions.\u003c/p\u003e\n"],["\u003cp\u003eThis API uses simple GET requests with parameters like \u003ccode\u003ename\u003c/code\u003e, \u003ccode\u003etype\u003c/code\u003e, \u003ccode\u003ecd\u003c/code\u003e, \u003ccode\u003ect\u003c/code\u003e, \u003ccode\u003edo\u003c/code\u003e, and \u003ccode\u003eedns_client_subnet\u003c/code\u003e to specify the DNS query.\u003c/p\u003e\n"],["\u003cp\u003eResponses are provided in JSON format, containing details like DNS status, answer records, and optional DNSSEC information.\u003c/p\u003e\n"],["\u003cp\u003eThe API supports various DNS record types and features such as EDNS Client Subnet for location-aware queries and DNSSEC validation for enhanced security.\u003c/p\u003e\n"],["\u003cp\u003eFor detailed information on DoH, secure transports, and privacy practices, refer to the provided documentation links.\u003c/p\u003e\n"]]],["Google Public DNS offers a web-friendly API for DNS-over-HTTPS (DoH) using simple HTTP GET requests and JSON responses. Key parameters include `name` (required domain), `type` (record type), `cd` (disable DNSSEC), `do` (include DNSSEC records), `ct` (content type), and `edns_client_subnet` (client IP). Responses include status, data, and DNSSEC validation information. The API allows clients to avoid complex DNS formatting and supports DNSSEC validation without browser extensions.\n"],null,["# JSON API for DNS over HTTPS (DoH)\n\nPreviously, web-based applications required browser extensions to use advanced\nDNS features such as [DANE](https://en.wikipedia.org/wiki/DANE), [DNS-SD service discovery](http://www.infoq.com/articles/rest-discovery-dns), or even to resolve\nanything other than IP addresses -- like MX records.\nTo use DNSSEC-dependent features like [SSHFP records](https://cloud.google.com/dns/docs/dnssec-advanced#sshfp), any such extensions\nwould have to validate DNSSEC themselves, as the browser or OS might not do so.\n\nSince 2016, Google Public DNS has offered a web-friendly API for DoH with DNSSEC\nvalidation that does not require browser or OS configuration or extensions.\nSimple GET query parameters and JSON responses allow clients to parse the\nresults using common web APIs and avoid complex DNS message format details like\n[pointer compression for domain names](https://www.kb.cert.org/vuls/id/23495/).\n\nSee the general [DoH documentation page](/speed/public-dns/docs/doh) for information about DoH\ngenerally, such as HTTP headers, redirect handling, privacy best practices, and\nHTTP status codes.\n\nThe [Secure Transports](/speed/public-dns/docs/secure-transports#doh) page has\n`curl` command line examples for DoH, and information common to DoH and DNS over\nTLS (DoT), such as TLS support and DNS truncation.\n\nJSON API Specification\n----------------------\n\nAll API calls are HTTP GET requests.\nIn the case of duplicate parameters, only the first value is used.\n\n### Supported parameters\n\nname\n\n: string, required\n\n The only required parameter. RFC 4343 backslash escapes are accepted.\n\n - The length (after replacing backslash escapes) must be between 1 and [253](https://stackoverflow.com/a/28918017/18829) (ignoring an optional trailing dot if present).\n - All labels (parts of the name betweendots) must be 1 to 63 bytes long.\n - Invalid names like `.example.com`, `example..com` or empty string get 400 Bad Request.\n - Non-ASCII characters should be [punycoded](https://en.wikipedia.org/wiki/Punycode) (`xn--qxam`, not `ελ`).\n\ntype\n\n: string, default: `1`\n\n RR type can be represented as a number in \\[1, 65535\\] or a canonical string\n (case-insensitive, such as `A` or `aaaa`).\n You can use `255` for 'ANY' queries but be aware that this is *not* a\n replacement for sending queries for both A and AAAA or MX records.\n Authoritative name servers need not return all records for such queries;\n some do not respond, and others (such as cloudflare.com) return only HINFO.\n\ncd\n\n: boolean, default: `false`\n\n \u003cbr /\u003e\n\n The CD (Checking Disabled) flag.\n Use `cd=1`, or `cd=true` to disable DNSSEC validation;\n use `cd=0`, `cd=false`, or no `cd` parameter to enable DNSSEC validation.\n\nct\n\n: string, default: empty\n\n Desired content type option.\n\n Use `ct=application/dns-message` to receive a binary DNS message in the\n response HTTP body instead of JSON text.\n Use `ct=application/x-javascript` to explicitly request JSON text.\n Other content type values are ignored and default JSON content is returned.\n\ndo\n\n: boolean, default: `false`\n\n \u003cbr /\u003e\n\n The DO (DNSSEC OK) flag.\n Use `do=1`, or `do=true` to include DNSSEC records (RRSIG, NSEC, NSEC3);\n use `do=0`, `do=false`, or no `do` parameter to omit DNSSEC records.\n\n Applications should always handle (and ignore, if necessary) any DNSSEC\n records in JSON responses as other implementations may always include them,\n and we may change the default behavior for JSON responses in the future.\n (Binary DNS message responses always respect the value of the DO flag.)\n\n \u003cbr /\u003e\n\nedns_client_subnet\n\n: string, default: empty\n\n The edns0-client-subnet option. Format is an IP address with a subnet mask.\n Examples: `1.2.3.4/24`, `2001:700:300::/48`.\n\n If you are using DNS-over-HTTPS because of privacy concerns, and do not want\n *any* part of your IP address to be sent to authoritative name servers\n for geographic location accuracy, use `edns_client_subnet=0.0.0.0/0`.\n Google Public DNS normally sends approximate network information\n (usually zeroing out the last part of your IPv4 address).\n\nrandom_padding\n\n: string, ignored\n\n The value of this parameter is ignored. Example: `XmkMw~o_mgP2pf.gpw-Oi5dK`.\n\n API clients concerned about possible side-channel privacy attacks using the\n packet sizes of HTTPS GET requests can use this to make all requests exactly\n the same size by padding requests with random data.\n To prevent misinterpretation of the URL, restrict the padding characters\n to the [unreserved URL characters](http://stackoverflow.com/a/695469/18829):\n upper- and lower-case letters, digits, hyphen, period, underscore and tilde.\n\n### DNS response in JSON\n\nA successful response (comments added here are not present in actual responses): \n\n {\n \"Status\": 0, // NOERROR - Standard DNS response code (32 bit integer).\n \"TC\": false, // Whether the response is truncated\n \"RD\": true, // Always true for Google Public DNS\n \"RA\": true, // Always true for Google Public DNS\n \"AD\": false, // Whether all response data was validated with DNSSEC\n \"CD\": false, // Whether the client asked to disable DNSSEC\n \"Question\":\n [\n {\n \"name\": \"apple.com.\", // FQDN with trailing dot\n \"type\": 1 // A - Standard DNS RR type\n }\n ],\n \"Answer\":\n [\n {\n \"name\": \"apple.com.\", // Always matches name in the Question section\n \"type\": 1, // A - Standard DNS RR type\n \"TTL\": 3599, // Record's time-to-live in seconds\n \"data\": \"17.178.96.59\" // Data for A - IP address as text\n },\n {\n \"name\": \"apple.com.\",\n \"type\": 1,\n \"TTL\": 3599,\n \"data\": \"17.172.224.47\"\n },\n {\n \"name\": \"apple.com.\",\n \"type\": 1,\n \"TTL\": 3599,\n \"data\": \"17.142.160.59\"\n }\n ],\n \"edns_client_subnet\": \"12.34.56.78/0\" // IP address / scope prefix-length\n }\n\nSee [RFC 7871 (EDNS Client Subnet)](https://tools.ietf.org/html/rfc7871) for\ndetails about \"scope prefix-length\" and how it affects caching.\n\nA failure response with diagnostic information: \n\n {\n \"Status\": 2, // SERVFAIL - Standard DNS response code (32 bit integer).\n \"TC\": false, // Whether the response is truncated\n \"RD\": true, // Always true for Google Public DNS\n \"RA\": true, // Always true for Google Public DNS\n \"AD\": false, // Whether all response data was validated with DNSSEC\n \"CD\": false, // Whether the client asked to disable DNSSEC\n \"Question\":\n [\n {\n \"name\": \"dnssec-failed.org.\", // FQDN with trailing dot\n \"type\": 1 // A - Standard DNS RR type\n }\n ],\n \"Comment\": \"DNSSEC validation failure. Please check http://dnsviz.net/d/dnssec-failed.org/dnssec/.\"\n }\n\nSPF and TXT records with embedded quotes and name server attribution: \n\n {\n \"Status\": 0, // NOERROR - Standard DNS response code (32 bit integer).\n \"TC\": false, // Whether the response is truncated\n \"RD\": true, // Always true for Google Public DNS\n \"RA\": true, // Always true for Google Public DNS\n \"AD\": false, // Whether all response data was validated with DNSSEC\n \"CD\": false, // Whether the client asked to disable DNSSEC\n \"Question\": [\n {\n \"name\": \"*.dns-example.info.\", // FQDN with trailing dot\n \"type\": 99 // SPF - Standard DNS RR type\n }\n ],\n \"Answer\": [\n {\n \"name\": \"*.dns-example.info.\", // Always matches name in Question\n \"type\": 99, // SPF - Standard DNS RR type\n \"TTL\": 21599, // Record's time-to-live in seconds\n \"data\": \"\\\"v=spf1 -all\\\"\" // Data for SPF - quoted string\n }\n ],\n \"Comment\": \"Response from 216.239.38.110\"\n // Uncached responses are attributed to the authoritative name server\n }\n\n {\n \"Status\": 0, // NOERROR - Standard DNS response code (32 bit integer).\n \"TC\": false, // Whether the response is truncated\n \"RD\": true, // Always true for Google Public DNS\n \"RA\": true, // Always true for Google Public DNS\n \"AD\": false, // Whether all response data was validated with DNSSEC\n \"CD\": false, // Whether the client asked to disable DNSSEC\n \"Question\": [\n {\n \"name\": \"s1024._domainkey.yahoo.com.\", // FQDN with trailing dot\n \"type\": 16 // TXT - Standard DNS RR type\n }\n ],\n \"Answer\": [\n {\n \"name\": \"s1024._domainkey.yahoo.com.\", // Always matches Question name\n \"type\": 16, // TXT - Standard DNS RR type\n \"data\": \"\\\"k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDrEee0Ri4Juz+QfiWYui/E9UGSXau/2P8LjnTD8V4Unn+2FAZVGE3kL23bzeoULYv4PeleB3gfm\\\"\\\"JiDJOKU3Ns5L4KJAUUHjFwDebt0NP+sBK0VKeTATL2Yr/S3bT/xhy+1xtj4RkdV7fVxTn56Lb4udUnwuxK4V5b5PdOKj/+XcwIDAQAB; n=A 1024 bit key;\\\"\"\n // Data for TXT - multiple quoted strings\n }\n ],\n }\n\n### DNS strings\n\nAll TXT records are encoded as a single JSON string including uses of longer TXT\nrecord formats such as\n[RFC 4408 (SPF)](https://tools.ietf.org/html/rfc4408#section-3.1.3) or\n[RFC 4871 (DKIM)](https://tools.ietf.org/html/rfc4871#section-3.6.2.2).\n\n### EDNS\n\nThe general [EDNS extension mechanism](https://en.wikipedia.org/wiki/Extension_mechanisms_for_DNS) is not supported.\nThe EDNS Client Subnet option (edns-client-subnet) is a parameter in the\nGET request and a top level field in the JSON response."]]
