JSON API برای DNS از طریق HTTPS (DoH)
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
قبلاً، برنامه‌های مبتنی بر وب برای استفاده از ویژگی‌های پیشرفته DNS مانند DANE ، کشف سرویس DNS-SD یا حتی برای حل هر چیزی غیر از آدرس‌های IP - مانند رکوردهای MX، به برنامه‌های افزودنی مرورگر نیاز داشتند. برای استفاده از ویژگی‌های وابسته به DNSSEC مانند رکوردهای SSHFP ، هر یک از این پسوندها باید خودشان DNSSEC را تأیید کنند، زیرا ممکن است مرورگر یا سیستم عامل این کار را انجام ندهند.
از سال 2016، Google Public DNS یک API سازگار با وب برای DoH با اعتبارسنجی DNSSEC ارائه کرده است که نیازی به پیکربندی مرورگر یا سیستم عامل یا برنامه‌های افزودنی ندارد. پارامترهای ساده GET query و پاسخ‌های JSON به مشتریان اجازه می‌دهند تا نتایج را با استفاده از APIهای رایج وب تجزیه کنند و از جزئیات فرمت پیام DNS پیچیده مانند فشرده‌سازی اشاره‌گر برای نام دامنه اجتناب کنند.
برای اطلاعات کلی درباره DoH، مانند سرصفحه‌های HTTP، مدیریت تغییر مسیر، بهترین شیوه‌های حفظ حریم خصوصی، و کدهای وضعیت HTTP، به صفحه اسناد عمومی DoH مراجعه کنید.
صفحه Secure Transports دارای نمونه‌های خط فرمان curl برای DoH و اطلاعات مشترک DoH و DNS از طریق TLS (DoT) است، مانند پشتیبانی TLS و برش DNS.
مشخصات JSON API
همه تماس‌های API درخواست‌های HTTP GET هستند. در مورد پارامترهای تکراری، فقط از مقدار اول استفاده می شود.
پارامترهای پشتیبانی شده
- نام
رشته، مورد نیاز
تنها پارامتر مورد نیاز بک اسلش RFC 4343 پذیرفته می شود.
- طول (پس از جایگزینی بک اسلش) باید بین 1 تا 253 باشد (در صورت وجود یک نقطه انتهایی اختیاری نادیده گرفته شود).
- تمام برچسب ها (بخش هایی از نام بین نقطه ها) باید 1 تا 63 بایت باشند.
- نام‌های نامعتبر مانند
.example.com ، example..com یا رشته خالی 400 Bad Request دریافت می‌کنند. - کاراکترهای غیر ASCII باید کدگذاری شوند (
xn--qxam ، نه ελ ).
- نوع
رشته، پیش فرض: 1
نوع RR می تواند به عنوان یک عدد در [1، 65535] یا یک رشته متعارف (بدون حساس به حروف، مانند A یا aaaa ) نمایش داده شود. شما می‌توانید 255 برای درخواست‌های 'ANY' استفاده کنید، اما توجه داشته باشید که این جایگزینی برای ارسال درخواست‌ها برای هر دو رکورد A و AAAA یا MX نیست . سرورهای نام معتبر نیازی به بازگرداندن تمام رکوردها برای چنین درخواست هایی ندارند. برخی پاسخ نمی دهند و برخی دیگر (مانند cloudflare.com) فقط HINFO را برمی گردانند.
- سی دی
بولی، پیش فرض: false
پرچم CD (Checking Disabled) برای غیرفعال کردن اعتبارسنجی DNSSEC از cd=1 یا cd=true استفاده کنید. برای فعال کردن اعتبارسنجی DNSSEC از پارامترهای cd=0 ، cd=false یا بدون cd استفاده کنید.
- ct
رشته، پیش فرض: خالی
گزینه نوع محتوای مورد نظر از ct=application/dns-message برای دریافت پیام DNS باینری در متن پاسخ HTTP به جای متن JSON استفاده کنید. برای درخواست صریح متن JSON از ct=application/x-javascript استفاده کنید. سایر مقادیر نوع محتوا نادیده گرفته می شوند و محتوای پیش فرض JSON برگردانده می شود.
- انجام دهید
بولی، پیش فرض: false
پرچم DO (DNSSEC OK). برای گنجاندن رکوردهای DNSSEC (RRSIG، NSEC، NSEC3) از do=1 یا do=true استفاده کنید. برای حذف رکوردهای DNSSEC از پارامتر do=0 ، do=false یا no do استفاده کنید.
برنامه‌ها باید همیشه رکوردهای DNSSEC را در پاسخ‌های JSON کنترل کنند (و در صورت لزوم نادیده بگیرند، زیرا سایر پیاده‌سازی‌ها ممکن است همیشه آنها را شامل شوند، و ممکن است رفتار پیش‌فرض پاسخ‌های 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 Public DNS معمولاً اطلاعات شبکه تقریبی را ارسال می کند (معمولاً آخرین قسمت آدرس IPv4 شما را صفر می کند).
- random_padding
رشته، نادیده گرفته شد
مقدار این پارامتر نادیده گرفته می شود. مثال: XmkMw~o_mgP2pf.gpw-Oi5dK .
کلاینت های API که نگران حملات احتمالی حریم خصوصی کانال جانبی با استفاده از اندازه بسته درخواست های HTTPS GET هستند، می توانند از این برای ایجاد همه درخواست ها دقیقاً به اندازه یکسان با اضافه کردن درخواست ها با داده های تصادفی استفاده کنند. برای جلوگیری از تفسیر نادرست URL، کاراکترهای padding را به کاراکترهای URL رزرو نشده محدود کنید: حروف بزرگ و کوچک، اعداد، خط فاصله، نقطه، زیرخط و tilde.
پاسخ DNS در JSON
یک پاسخ موفق (نظرات اضافه شده در اینجا در پاسخ های واقعی وجود ندارد):
{
"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 Client Subnet (edns-client-subnet) یک پارامتر در درخواست GET و یک فیلد سطح بالا در پاسخ JSON است.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
