Trang Tổng quan về phương thức truyền tải an toàn có curl ví dụ về dòng lệnh để sử dụng cả API cũng như thông tin chi tiết về TLS và các tính năng khác phổ biến cho cả DNS qua TLS (DoT) và DoH.
Google Public DNS không hỗ trợ các URL http: không an toàn cho các lệnh gọi API.
Các phương thức HTTP
GET
Phương thức GET có thể giảm độ trễ vì phương thức này được lưu vào bộ nhớ đệm hiệu quả hơn.
Các yêu cầu GET RFC 8484 phải có tham số truy vấn ?dns= với thông báo DNS được mã hoá Base64Url.
Phương thức GET là phương thức duy nhất được hỗ trợ cho API JSON.
POST
Phương thức POST chỉ được hỗ trợ cho API RFC 8484 và sử dụng thông báo DNS nhị phân có chứa ứng dụng Content-Type/thông báo dns- trong nội dung yêu cầu và trong phản hồi HTTP DoH.
HEAD
HEAD hiện không được hỗ trợ và trả về lỗi 400 Bad Request.
Các phương thức khác trả về lỗi 501 Not Implementationed (Chưa triển khai).
Mã trạng thái HTTP
Google Public DNS DoH trả về mã trạng thái HTTP sau đây:
Thành công
200 OK
Phân tích cú pháp và giao tiếp HTTP với trình phân giải DNS đã thành công. Nội dung nội dung phản hồi là một phản hồi DNS ở dạng mã hoá nhị phân hoặc JSON, tuỳ thuộc vào điểm cuối truy vấn, tiêu đề Chấp nhận và tham số GET.
Chuyển hướng
301 Đã di chuyển vĩnh viễn
Ứng dụng nên thử lại tại URL được cung cấp trong tiêu đề Location:. Nếu truy vấn ban đầu là yêu cầu POST, thì ứng dụng chỉ nên thử lại bằng GET nếu URL mới chỉ định đối số tham số GET dns; nếu không thì ứng dụng nên thử lại bằng yêu cầu POST.
Trong tương lai, có thể sử dụng các mã khác như 302 Found, 307 Temporary Redirect hoặc 308 Permanent Redirect và ứng dụng DoH sẽ xử lý cả 4 mã.
Các phản hồi có mã 301 và 308 cố định phải được lưu vào bộ nhớ đệm vô thời hạn và nếu thích hợp, người dùng có thể được nhắc cập nhật cấu hình ban đầu bằng URL mới.
Đối với những yêu cầu POST và nhận được phản hồi 307 hoặc 308, bạn nên thử lại bằng phương thức POST.
Lỗi
Phản hồi lỗi sẽ có phần giải thích về trạng thái HTTP trong phần nội dung, bằng cách sử dụng HTML hoặc văn bản thuần tuý.
400 Yêu cầu không hợp lệ
Sự cố khi phân tích cú pháp các tham số GET hoặc thông báo yêu cầu DNS không hợp lệ.
Đối với các tham số GET không hợp lệ, phần nội dung HTTP sẽ giải thích lỗi. Hầu hết thông báo DNS không hợp lệ đều nhận được giá trị 200 OK với FORMERR; lỗi HTTP được trả về đối với các thông báo bị cắt xén không có phần Câu hỏi, một cờ QR biểu thị câu trả lời hoặc các cách kết hợp cờ vô nghĩa khác mắc lỗi phân tích cú pháp DNS nhị phân.
413 Tải trọng quá lớn
Nội dung yêu cầu POST RFC 8484 vượt quá kích thước thư tối đa 512 byte.
URI 414 quá dài
Tiêu đề truy vấn GET quá lớn hoặc tham số dns có thông báo DNS được mã hoá Base64Url vượt quá kích thước thông báo tối đa 512 byte.
415 Loại nội dung nghe nhìn không được hỗ trợ
Nội dung POST không có tiêu đề Content-Type application/dns-message.
429 Quá nhiều yêu cầu
Khách hàng đã gửi quá nhiều yêu cầu trong một khoảng thời gian nhất định. Ứng dụng sẽ ngừng gửi yêu cầu cho đến thời điểm đã chỉ định trong tiêu đề Retry-After (thời gian tương đối tính bằng giây).
Lỗi máy chủ nội bộ 500
Lỗi DoH nội bộ của DNS Google Public.
501 Chưa được triển khai
Chỉ triển khai phương thức GET và POST, các phương thức khác sẽ gặp lỗi này.
502 Cổng vào không hợp lệ
Dịch vụ DoH không thể liên hệ với trình phân giải DNS của Google Public.
Trong trường hợp phản hồi 502, mặc dù việc thử lại địa chỉ DNS Google Public thay thế có thể hữu ích, nhưng phản hồi dự phòng hiệu quả hơn sẽ là thử một dịch vụ DoH khác hoặc chuyển sang UDP hoặc TCP DNS truyền thống tại 8.8.8.8.
Lợi ích của DoH
Việc sử dụng HTTPS không chỉ mã hoá TLS mang lại một số lợi ích thiết thực:
Các API HTTPS được cung cấp rộng rãi và được hỗ trợ tốt giúp đơn giản hoá quá trình triển khai cho cả DNS Google Public và ứng dụng tiềm năng.
Dịch vụ HTTPS cung cấp cho các ứng dụng web quyền truy cập vào tất cả các loại bản ghi DNS, tránh các hạn chế của API DNS của trình duyệt và hệ điều hành hiện có, thường chỉ hỗ trợ hoạt động tra cứu máy chủ lưu trữ với địa chỉ.
Các ứng dụng triển khai hỗ trợ HTTPS dựa trên UDP theo QUIC có thể tránh được các sự cố như chặn đầu dòng có thể xảy ra khi sử dụng truyền tải TCP.
Các phương pháp hay nhất về quyền riêng tư dành cho DoH
Nhà phát triển ứng dụng DoH nên cân nhắc các phương pháp hay nhất về quyền riêng tư được nêu trong RFC 8484 và mở rộng bên dưới:
Hạn chế sử dụng tiêu đề HTTP
Các tiêu đề HTTP tiết lộ thông tin về việc triển khai DoH của ứng dụng và có thể được dùng để huỷ ẩn danh ứng dụng. Các tiêu đề như Cookie, Tác nhân người dùng và Accept-Language là những mục vi phạm nghiêm trọng nhất, nhưng ngay cả tập hợp tiêu đề đã gửi cũng có thể bị lộ. Để giảm thiểu rủi ro này, hãy chỉ gửi các tiêu đề HTTP cần thiết cho DoH: Host (Lưu trữ), Content-Type (đối với POST) và Accept (Chấp nhận).
Phải đưa tác nhân người dùng vào mọi phiên bản phát triển hoặc thử nghiệm.
Sử dụng các lựa chọn khoảng đệm EDNS
Làm theo hướng dẫn trong RFC 8467 để sử dụng các tuỳ chọn khoảng đệm EDNS nhằm truyền truy vấn DoH theo một vài độ dài phổ biến nhằm ngăn chặn việc phân tích lưu lượng truy cập. Bạn cũng có thể sử dụng khoảng đệm HTTP/2, nhưng không giống như khoảng đệm EDNS, sẽ không tạo ra khoảng đệm trên phản hồi từ máy chủ DoH.
Chỉ sử dụng RFC 8484 POST cho các ứng dụng có nhạy cảm về quyền riêng tư hoặc chế độ trình duyệt
Việc sử dụng POST cho các truy vấn DoH làm giảm khả năng lưu vào bộ nhớ đệm của phản hồi và có thể làm tăng độ trễ của DNS. Vì vậy, bạn không nên thực hiện việc này. Tuy nhiên, việc giảm khả năng lưu vào bộ nhớ đệm có thể là cần thiết đối với các ứng dụng nhạy cảm về quyền riêng tư và có thể giúp chống lại các cuộc tấn công về thời gian của các ứng dụng web cố gắng xác định những miền mà người dùng đã truy cập gần đây.
Vấn đề
Để báo cáo lỗi hoặc yêu cầu tính năng mới, vui lòng mở một vấn đề của DoH.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-25 UTC."],[[["\u003cp\u003eGoogle Public DNS offers two DoH APIs: \u003ccode\u003edns.google/dns-query\u003c/code\u003e (RFC 8484, GET & POST) and \u003ccode\u003edns.google/resolve\u003c/code\u003e (JSON API, GET only).\u003c/p\u003e\n"],["\u003cp\u003eDoH supports both IPv4 and IPv6 using HTTPS for enhanced security and wider accessibility.\u003c/p\u003e\n"],["\u003cp\u003eFor privacy, minimize HTTP headers, utilize EDNS padding, and consider RFC 8484 POST for sensitive applications.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Public DNS returns various HTTP status codes, including 200 OK for success (check DNS response code for errors) and error codes like 400, 413, 414, 415, 429, 500, 501, and 502.\u003c/p\u003e\n"],["\u003cp\u003eDoH benefits include wider API support, access to all DNS record types for web apps, and potential performance improvements with QUIC.\u003c/p\u003e\n"]]],["Google Public DNS offers two DoH APIs: one using RFC 8484 (supporting GET and POST) and a JSON API (GET only). GET requests use Base64Url-encoded DNS messages in the query parameters; POST requests use binary DNS messages. The service returns standard HTTP status codes, including 200 OK for success, and various error codes (400, 413, 414, 415, 429, 500, 501, 502), with 301, 307, and 308 for redirection. Privacy best practices include limiting HTTP headers, using EDNS padding, and employing POST for sensitive applications.\n"],null,["# DNS-over-HTTPS (DoH)\n\nGoogle Public DNS provides two distinct DoH APIs at these endpoints:\n\n- https://dns.google/dns-query -- [RFC 8484](https://tools.ietf.org/html/rfc8484) (GET and POST)\n- https://dns.google/resolve? -- [JSON API](/speed/public-dns/docs/doh/json) (GET)\n\n| **Note:** There is also a human-friendly web interface at \u003chttps://dns.google/\u003e. This web app displays JSON results in a browser but does not implement an API; do not confuse its https://dns.google/query? URLs with the two API URLs.\n\nThe [Secure Transports Overview](/speed/public-dns/docs/secure-transports#doh)\npage has `curl` command line examples for using both APIs as well as details of\nTLS and other features common to both DNS over TLS (DoT) and DoH.\n\nDoH is also supported for the IPv6-only\n[Google Public DNS64 service](/speed/public-dns/docs/dns64#secure).\n\nGoogle Public DNS does not support insecure `http:` URLs for API calls.\n\nHTTP methods\n------------\n\nGET\n: Using the GET method can reduce latency, as it is cached more effectively.\n RFC 8484 GET requests must have a `?dns=` query parameter with a\n Base64Url encoded DNS message.\n The GET method is the only method supported for the JSON API.\n\nPOST\n: The POST method is only supported for the RFC 8484 API and uses a binary DNS\n message with Content-Type application/dns-message in the request body and in\n the DoH HTTP response.\n\nHEAD\n: *HEAD is not currently supported, and returns a 400 Bad Request error*.\n\nOther methods return 501 Not Implemented errors.\n\nHTTP status codes\n-----------------\n\nGoogle Public DNS DoH returns the following HTTP status codes:\n\n### Success\n\n200 OK\n: HTTP parsing and communication with DNS resolver was successful, and the\n response body content is a DNS response in either binary or JSON encoding,\n depending on the query endpoint, Accept header and GET parameters.\n| **Note:** An HTTP success may still be a DNS failure. Check the DNS response code (JSON \"Status\" field) for the DNS errors SERVFAIL, FORMERR, REFUSED, and NOTIMP.\n\n### Redirections\n\n301 Moved Permanently\n: Clients should retry at the URL provided in the `Location:` header. If the\n original query was a POST request, clients should only retry with GET if the\n new URL specifies a `dns` GET parameter argument; otherwise clients should\n retry with POST.\n\nOther codes such as 302 Found, 307 Temporary Redirect or 308 Permanent Redirect\nmay be used in the future, and DoH clients should handle all four codes.\n\nResponses with the permanent 301 and 308 codes should be cached indefinitely,\nand if practical, users may be prompted to update their original configuration\nusing the new URL.\n\nPOST requests that get 307 or 308 responses should always be retried with POST.\n\n### Errors\n\nError responses will have an explanation of the HTTP status in the body,\nusing either HTML or plain text.\n\n400 Bad Request\n: Problems parsing the GET parameters, or an invalid DNS request message.\n For bad GET parameters, the HTTP body should explain the error. Most invalid\n DNS messages get a 200 OK with a FORMERR; the HTTP error is returned for\n garbled messages with no Question section, a QR flag indicating a reply, or\n other nonsensical flag combinations with binary DNS parse errors.\n\n413 Payload Too Large\n: An RFC 8484 POST request body exceeded the 512 byte maximum message size.\n\n414 URI Too Long\n: The GET query header was too large or the `dns` parameter had a Base64Url\n encoded DNS message exceeding the 512 byte maximum message size.\n\n415 Unsupported Media Type\n: The POST body did not have an `application/dns-message` Content-Type header.\n\n429 Too Many Requests\n: The client has sent too many requests in a given amount of time. Clients\n should stop sending requests until the time specified in the Retry-After\n header (a relative time in seconds).\n\n500 Internal Server Error\n: Google Public DNS internal DoH errors.\n\n501 Not Implemented\n: Only GET and POST methods are implemented, other methods get this error.\n\n502 Bad Gateway\n: The DoH service could not contact Google Public DNS resolvers.\n\nIn the case of a 502 response, although retrying on an alternate Google Public\nDNS address might help, a more effective fallback response would be to try\nanother DoH service, or to switch to traditional UDP or TCP DNS at 8.8.8.8.\n\nBenefits of DoH\n---------------\n\nUsing HTTPS, not just TLS encryption, has some practical benefits:\n\n- Widely available and well-supported HTTPS APIs simplify implementation for both Google Public DNS itself and potential clients.\n- An HTTPS service provides web apps with access to all DNS record types, avoiding the limitations of existing browser and OS DNS APIs, which generally support only host-to-address lookups.\n- Clients that implement QUIC UDP-based HTTPS support can avoid problems like head-of-line blocking that can occur when using TCP transport.\n\nPrivacy Best Practices for DoH\n------------------------------\n\nDevelopers of DoH applications should consider the privacy best practices\noutlined in [RFC 8484](https://tools.ietf.org/html/rfc8484#section-8) and\nexpanded below:\n\n- Limit use of HTTP Headers\n\n HTTP headers reveal information about the client's DoH implementation and\n can be used to deanonymize clients. Headers like Cookie, User-Agent, and\n Accept-Language are the worst offenders, but even the set of headers sent\n can be revealing. To minimize this risk, send only the HTTP headers required\n for DoH: Host, Content-Type (for POST), and if necessary, Accept.\n User-Agent should be included in any development or testing versions.\n- Use EDNS padding options\n\n Follow the guidance in [RFC 8467](https://tools.ietf.org/html/rfc8467) for\n use of EDNS padding options to pad DoH queries to a few common lengths to\n protect against traffic analysis. Use of HTTP/2 padding is also possible but\n unlike EDNS padding, will not elicit padding on responses from DoH servers.\n- Use RFC 8484 POST only for privacy sensitive applications or browser modes\n\n Using POST for DoH queries reduces the cacheability of responses and can\n increase DNS latency, so it is not generally recommended. However, reducing\n caching is probably desirable for privacy sensitive applications, and might\n protect against timing attacks from web apps trying to determine what\n domains the user has visited lately.\n\nIssues\n------\n\nTo report a bug or request a new feature, please open an [issue for DoH](https://issuetracker.google.com/issues/new?component=191657&template=1189745)."]]
