JSON API for DNS over HTTPS (DoH)
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
في السابق، كانت التطبيقات المستندة إلى الويب تتطلّب إضافات المتصفح لاستخدام الميزات المتقدّمة
ميزات نظام أسماء النطاقات مثل DANE واكتشاف خدمة نظام أسماء النطاقات-SD أو حتى لحل
أي شيء آخر بخلاف عناوين IP، مثل سجلات MX.
لاستخدام الميزات التي تعتمد على ملحقات أمان نظام أسماء النطاقات (DNSSEC)، مثل سجلّات SSHFP، يمكن استخدام أيٍّ من هذه الإضافات.
التحقق من صحة ملحقات أمان نظام أسماء النطاقات (DNSSEC) بنفسها، لأنّ المتصفّح أو نظام التشغيل قد لا يتحقّقان من ذلك.
منذ عام 2016، قدّم نظام أسماء النطاقات العام من Google واجهة برمجة تطبيقات متوافقة مع الويب في DoH تتضمّن ملحقات أمان نظام أسماء النطاقات (DNSSEC).
عمليات تحقق لا تتطلب تهيئة المتصفح أو نظام التشغيل أو الإضافات.
تسمح معلمات طلب بحث GET البسيطة واستجابات JSON للعملاء بتحليل
تستخدم واجهات برمجة تطبيقات الويب الشائعة وتجنب التفاصيل المعقدة لتنسيق رسالة نظام أسماء النطاقات، مثل
ضغط المؤشر لأسماء النطاقات.
يمكنك الاطّلاع على صفحة مستندات وزارة الصحة العامة للحصول على معلومات عن وزارة الصحة.
مثل عناوين HTTP ومعالجة إعادة التوجيه وأفضل ممارسات الخصوصية
رموز حالة HTTP.
تتضمن صفحة عمليات النقل الآمن
أمثلة على curl في سطر الأوامر في DoH، والمعلومات المشتركة في DoH ونظام أسماء النطاقات عبر
TLS (DoT)، مثل دعم TLS واقتطاع نظام أسماء النطاقات
مواصفات واجهة برمجة التطبيقات JSON
جميع طلبات البيانات من واجهة برمجة التطبيقات هي طلبات HTTP GET.
في حالة وجود المعلمات المكررة، يتم استخدام القيمة الأولى فقط.
المَعلمات المتوافقة
- الاسم
سلسلة، مطلوبة
المعلمة المطلوبة الوحيدة. يتم قبول أحرف إلغاء الشرطة المائلة للخلف في RFC 4343.
- يجب أن يكون الطول (بعد استبدال أحرف إلغاء الشرطة المائلة للخلف) بين 1 و
253
(مع تجاهل نقطة الانتهاء الاختيارية إن كانت موجودة).
- يجب أن يتراوح طول جميع التصنيفات (أجزاء من الاسم بين النقاط) 1 إلى 63 بايت.
- يتم الحصول على الأسماء غير الصالحة مثل
.example.com أو example..com أو سلسلة فارغة.
400 طلب سيئ.
- يجب أن تكون الأحرف غير ASCII punycoded (
xn--qxam، وليس ελ).
- كتابة
سلسلة، القيمة التلقائية: 1
يمكن تمثيل نوع RR كرقم في [1، 65535] أو سلسلة أساسية.
(غير حساسة لحالة الأحرف، مثل A أو aaaa).
يمكنك استخدام 255 لـ 'ANY' طلبات البحث، ولكن اعلم أن هذا ليس
بديل لإرسال الاستعلامات لكل من سجلات A وAAAA أو MX.
لا تحتاج خوادم الأسماء الموثوقة إلى عرض جميع السجلات لطلبات البحث هذه.
والبعض الآخر لا يستجيب والبعض الآخر (مثل cloudflare.com) لا يعرض سوى HINFO.
- cd
منطقي، القيمة التلقائية: false
علامة القرص المضغوط (تم تعطيل التحقق).
استخدام الإضافة 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
علامة "ملحق أمان نظام أسماء النطاقات" (DNSSEC)
استخدام do=1 أو do=true لتضمين سجلّات ملحقات أمان نظام أسماء النطاقات (DNSSEC) (RRSIG وNSEC وNSEC3)
استخدام مَعلمة do=0 أو do=false أو لا do لحذف سجلّات ملحقات أمان نظام أسماء النطاقات (DNSSEC)
يجب أن تتعامل التطبيقات دائمًا مع أي من ملحقات أمان نظام أسماء النطاقات (DNSSEC) (وتتجاهلها، إذا لزم الأمر).
السجلات في استجابات JSON حيث قد تتضمنها عمليات تنفيذ أخرى دائمًا،
وقد نغيّر السلوك التلقائي لاستجابات JSON في المستقبل.
(تراعي دائمًا استجابات رسالة نظام أسماء النطاقات الثنائية قيمة علامة DO.)
- edns_client_subnet
سلسلة، تلقائي: فارغ
الخيار edns0-client-subnet. التنسيق هو عنوان IP مع قناع الشبكة الفرعية.
أمثلة: 1.2.3.4/24، 2001:700:300::/48.
إذا كنت تستخدم معالجة نظام أسماء النطاقات عبر بروتوكول HTTPS بسبب مخاوف تتعلق بالخصوصية، ولا تريد
أي جزء من عنوان IP لإرساله إلى خوادم الأسماء الموثوقة
لدقة الموقع الجغرافي، استخدم edns_client_subnet=0.0.0.0/0.
عادةً ما يرسل نظام أسماء النطاقات العام من Google معلومات تقريبية عن الشبكة.
(عادةً ما يتم تفريغ الجزء الأخير من عنوان IPv4).
- random_padding
سلسلة، تم التجاهل
ويتم تجاهل قيمة هذه المَعلمة. مثال: XmkMw~o_mgP2pf.gpw-Oi5dK
شعور عملاء واجهة برمجة التطبيقات بالقلق بشأن هجمات الخصوصية المحتملة من جانب القناة باستخدام
يمكن لأحجام حزم البيانات الخاصة بطلبات HTTPS GET استخدام هذا المعامل لإجراء جميع الطلبات بالضبط
بنفس الحجم من خلال طلبات المساحة المتروكة مع بيانات عشوائية.
لمنع إساءة تفسير عنوان URL، يجب فرض قيود على أحرف المساحة المتروكة.
إلى أحرف عنوان URL غير المحجوزة:
الأحرف الكبيرة والصغيرة والأرقام والواصلة والنقطة والشرطة السفلية والتلدة.
استجابة نظام أسماء النطاقات بتنسيق 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 Client Subnet) للحصول على
تفاصيل حول "طول بادئة النطاق" وكيفية تأثيره في التخزين المؤقت.
خطأ في الاستجابة مع معلومات التشخيص:
{
"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
}
],
}
سلاسل نظام أسماء النطاقات
يتم ترميز جميع سجلّات TXT كسلسلة JSON واحدة بما في ذلك استخدامات سجلّ TXT الأطول
تنسيقات السجل مثل
RFC 4408 (نظام التعرف على هوية المرسل) (SPF) أو
RFC 4871 (DKIM)
نظام أسماء النطاقات (EDNS)
لا تتوفّر آلية إضافة EDNS العامة.
يُعد خيار الشبكة الفرعية لعميل EDNS (edns-client-subnet) معلمة في
طلب GET وحقل مستوى أعلى في استجابة JSON.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
