DNS

[مستقر: 2 - مستقر]

رمز المصدر: lib/dns.js

تُمكن وحدة node:dns من حل الأسماء. على سبيل المثال، استخدمها للبحث عن عناوين IP لأسماء المضيفين.

على الرغم من تسميتها باسم نظام أسماء النطاق (DNS)، إلا أنها لا تستخدم دائمًا بروتوكول DNS للبحث. تستخدم dns.lookup() مرافق نظام التشغيل لأداء حل الأسماء. قد لا تحتاج إلى إجراء أي اتصال بشبكة. لأداء حل الأسماء بالطريقة التي تستخدمها التطبيقات الأخرى على نفس النظام، استخدم dns.lookup().

ESMCJS

import dns from 'node:dns'

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family)
})
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

const dns = require('node:dns')

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family)
})
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

جميع الوظائف الأخرى في وحدة node:dns تتصل بخادم DNS الفعلي لأداء حل الأسماء. ستستخدم دائمًا الشبكة لأداء استعلامات DNS. لا تستخدم هذه الوظائف نفس مجموعة ملفات التكوين التي يستخدمها dns.lookup() (مثل /etc/hosts). استخدم هذه الوظائف لأداء استعلامات DNS دائمًا، متجاوزًا مرافق حل الأسماء الأخرى.

ESMCJS

import dns from 'node:dns'

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err

  console.log(`addresses: ${JSON.stringify(addresses)}`)

  addresses.forEach(a => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`)
    })
  })
})

const dns = require('node:dns')

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err

  console.log(`addresses: ${JSON.stringify(addresses)}`)

  addresses.forEach(a => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`)
    })
  })
})

راجع قسم اعتبارات التنفيذ لمزيد من المعلومات.

الصنف: `dns.Resolver`

مضاف في: v8.3.0

حلّال مستقل لطلبات DNS.

يُنشئ حلّال جديد باستخدام إعدادات الخادم الافتراضية. لا يؤثر ضبط الخوادم المستخدمة لحلّال باستخدام resolver.setServers() على الحلّالات الأخرى:

ESMCJS

import { Resolver } from 'node:dns'
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])

// سيستخدم هذا الطلب الخادم في 4.4.4.4، بصرف النظر عن الإعدادات العالمية.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
})

const { Resolver } = require('node:dns')
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])

// سيستخدم هذا الطلب الخادم في 4.4.4.4، بصرف النظر عن الإعدادات العالمية.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
})

الطرق التالية من وحدة node:dns متاحة:

`Resolver([options])`

[History]

الإصدار	التغييرات
v16.7.0, v14.18.0	الآن يقبل كائن `options` خيار `tries`.
v12.18.3	الآن يقبل المُنشئ كائن `options`. الخيار الوحيد المدعوم هو `timeout`.
v8.3.0	مضاف في: v8.3.0

إنشاء حلّال جديد.

options <Object>
- timeout <integer> مهلة الاستعلام بالمللي ثانية، أو -1 لاستخدام مهلة افتراضية.
- tries <integer> عدد المحاولات التي سيحاول بها المُحلل الاتصال بكل خادم أسماء قبل الاستسلام. الافتراضي: 4

`resolver.cancel()`

مضاف في: v8.3.0

إلغاء جميع استعلامات DNS المعلقة التي قام بها هذا المُحلل. سيتم استدعاء وظائف الاستجابة المقابلة بخطأ برمز ECANCELLED.

`resolver.setLocalAddress([ipv4][, ipv6])`

مضاف في: v15.1.0، v14.17.0

ipv4 <string> تمثيل سلسلة لعنوان IPv4. الافتراضي: '0.0.0.0'
ipv6 <string> تمثيل سلسلة لعنوان IPv6. الافتراضي: '::0'

سيقوم مثيل المُحلل بإرسال طلباته من عنوان IP المحدد. يسمح هذا للبرامج بتحديد واجهات صادرة عند استخدامها في أنظمة متعددة المنازل.

إذا لم يتم تحديد عنوان v4 أو v6، فسيتم تعيينه إلى القيمة الافتراضية وسيختار نظام التشغيل عنوانًا محليًا تلقائيًا.

سيستخدم المُحلل عنوانًا محليًا v4 عند إجراء طلبات إلى خوادم DNS من نوع IPv4، وعنوانًا محليًا v6 عند إجراء طلبات إلى خوادم DNS من نوع IPv6. لا يؤثر نوع rrtype من طلبات الحل على العنوان المحلي المستخدم.

`dns.getServers()`

مضاف في: v0.11.3

المُخرجات: <string[]>

يرجع مصفوفة من سلاسل عناوين IP، مُنسّقة وفقًا لـ RFC 5952، وهي مُهيّأة حاليًا لحل DNS. ستتضمن السلسلة قسمًا للمنفذ إذا تم استخدام منفذ مخصص.

;['8.8.8.8', '2001:4860:4860::8888', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053']

`dns.lookup(hostname[, options], callback)`

[السجل]

الإصدار	التغييرات
v22.1.0، v20.13.0	خيار `verbatim` مُعطّل الآن لصالح خيار `order` الجديد.
v18.4.0	للتوافق مع `node:net`، عند تمرير كائن خيارات، يمكن أن يكون خيار `family` السلسلة `'IPv4'` أو السلسلة `'IPv6'`.
v18.0.0	تمرير وظيفة استجابة غير صالحة إلى وسيطة `callback` يُلقي الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v17.0.0	خيارات `verbatim` الافتراضية هي `true` الآن.
v8.5.0	خيار `verbatim` مدعوم الآن.
v1.2.0	خيار `all` مدعوم الآن.
v0.1.90	مضاف في: v0.1.90

hostname <string>
options <integer> | <Object>
- family <integer> | <string> عائلة السجل. يجب أن تكون 4، 6، أو 0. لأسباب التوافق مع الإصدارات السابقة، يتم تفسير 'IPv4' و 'IPv6' على أنهما 4 و 6 على التوالي. تشير القيمة 0 إلى إرجاع عنوان IPv4 أو IPv6 أو كليهما. إذا تم استخدام القيمة 0 مع { all: true } (انظر أدناه)، فسيتم إرجاع عنوان IPv4 أو IPv6 أو كليهما، اعتمادًا على مُحلل DNS الخاص بالنظام. الافتراضي: 0.
- hints <number> علم أو أكثر من أعلام getaddrinfo المدعومة. يمكن تمرير عدة أعلام عن طريق OR المنطقي لقيمها.
- all <boolean> عندما تكون true، تُرجع وظيفة الاستجابة جميع العناوين المُحلّلة في مصفوفة. خلاف ذلك، يُرجع عنوانًا واحدًا. الافتراضي: false.
- order <string> عندما يكون verbatim، يتم إرجاع العناوين المُحلّلة غير مُرتّبة. عندما يكون ipv4first، يتم فرز العناوين المُحلّلة عن طريق وضع عناوين IPv4 قبل عناوين IPv6. عندما يكون ipv6first، يتم فرز العناوين المُحلّلة عن طريق وضع عناوين IPv6 قبل عناوين IPv4. الافتراضي: verbatim (لا يتم إعادة ترتيب العناوين). القيمة الافتراضية قابلة للتكوين باستخدام dns.setDefaultResultOrder() أو --dns-result-order.
- verbatim <boolean> عندما تكون true، تتلقى وظيفة الاستجابة عناوين IPv4 و IPv6 بالترتيب الذي أعاد مُحلل DNS إرجاعها. عندما تكون false، يتم وضع عناوين IPv4 قبل عناوين IPv6. سيتم إهمال هذا الخيار لصالح order. عندما يتم تحديد كليهما، يكون لـ order أولوية أعلى. يجب أن يستخدم الكود الجديد فقط order. الافتراضي: true (لا يتم إعادة ترتيب العناوين). القيمة الافتراضية قابلة للتكوين باستخدام dns.setDefaultResultOrder() أو --dns-result-order.
callback <Function>
- err <Error>
- address <string> تمثيل سلسلة لعنوان IPv4 أو IPv6.
- family <integer> 4 أو 6، للدلالة على عائلة address، أو 0 إذا لم يكن العنوان عنوان IPv4 أو IPv6. 0 هو مؤشر محتمل على وجود خطأ في خدمة حل الأسماء التي يستخدمها نظام التشغيل.

يُحل اسم مضيف (مثل 'nodejs.org') إلى أول سجل A (IPv4) أو AAAA (IPv6) تم العثور عليه. جميع خصائص option اختيارية. إذا كان options عددًا صحيحًا، فيجب أن يكون 4 أو 6 - إذا لم يتم توفير options، فسيتم إرجاع عناوين IPv4 أو IPv6 أو كليهما إذا تم العثور عليها.

مع خيار all المُعيّن على true، تتغير وسيطات callback إلى (err, addresses)، مع كون addresses مصفوفة من الكائنات ذات خصائص address و family.

في حالة حدوث خطأ، يكون err كائنًا من نوع Error، حيث أن err.code هو رمز الخطأ. ضع في اعتبارك أن err.code سيتم تعيينه على 'ENOTFOUND' ليس فقط عندما لا يوجد اسم المضيف، ولكن أيضًا عندما يفشل البحث بطرق أخرى مثل عدم وجود مُوصِفات ملفات متاحة.

dns.lookup() ليس بالضرورة له أي علاقة ببروتوكول DNS. يستخدم التنفيذ مرفقًا لنظام التشغيل يمكنه ربط الأسماء بالعناوين والعكس صحيح. يمكن أن يكون لهذا التنفيذ عواقب دقيقة ولكنها مهمة على سلوك أي برنامج Node.js. يرجى أخذ بعض الوقت للرجوع إلى قسم اعتبارات التنفيذ قبل استخدام dns.lookup().

مثال على الاستخدام:

ESMCJS

import dns from 'node:dns'
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
dns.lookup('example.org', options, (err, address, family) => console.log('address: %j family: IPv%s', address, family))
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// عندما يكون options.all صحيحًا، ستكون النتيجة مصفوفة.
options.all = true
dns.lookup('example.org', options, (err, addresses) => console.log('addresses: %j', addresses))
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

const dns = require('node:dns')
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
dns.lookup('example.org', options, (err, address, family) => console.log('address: %j family: IPv%s', address, family))
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// عندما يكون options.all صحيحًا، ستكون النتيجة مصفوفة.
options.all = true
dns.lookup('example.org', options, (err, addresses) => console.log('addresses: %j', addresses))
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

إذا تم استدعاء هذه الطريقة كنسختها المُعدّة بواسطة util.promisify()، ولم يتم تعيين all على true، فإنها تُرجع Promise لكائن مع خصائص address و family.

علامات getaddrinfo المدعومة

[السجل]

الإصدار	التغييرات
v13.13.0، v12.17.0	تمت إضافة دعم لعلامة `dns.ALL`.

يمكن تمرير العلامات التالية كإشارات إلى dns.lookup().

dns.ADDRCONFIG: يحد من أنواع العناوين المُرجعة إلى أنواع العناوين غير المُعادلة المُهيئة على النظام. على سبيل المثال، لا تُرجع عناوين IPv4 إلا إذا كان النظام الحالي يحتوي على عنوان IPv4 واحد على الأقل مُهيأ.
dns.V4MAPPED: إذا تم تحديد عائلة IPv6، ولكن لم يتم العثور على عناوين IPv6، فقم بإرجاع عناوين IPv4 المُحسّنة لعناوين IPv6. هذا غير مدعوم على بعض أنظمة التشغيل (مثل FreeBSD 10.1).
dns.ALL: إذا تم تحديد dns.V4MAPPED، فارجع عناوين IPv6 المُحلّلة بالإضافة إلى عناوين IPv4 المُحسّنة لعناوين IPv6.

`dns.lookupService(address, port, callback)`

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُستدعي غير صالح إلى وسيطة `callback` الآن إلى طرح `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.11.14	تمت الإضافة في: v0.11.14

address <سلسلة>
port <رقم>
callback <دالة>
- err <خطأ>
- hostname <سلسلة> مثال: example.com
- service <سلسلة> مثال: http

يحلّ address و port المُعطيين في اسم مضيف وخدمة باستخدام تنفيذ getnameinfo الأساسي لنظام التشغيل.

إذا لم يكن address عنوان IP صالحًا، فسيتم طرح TypeError. سيتم إجبار port على رقم. إذا لم يكن منفذًا قانونيًا، فسيتم طرح TypeError.

في حالة حدوث خطأ، يكون err كائنًا من نوع Error، حيث يكون err.code هو رمز الخطأ.

ESMCJS

import dns from 'node:dns'
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service)
  // يطبع: localhost ssh
})

const dns = require('node:dns')
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service)
  // يطبع: localhost ssh
})

إذا تم استدعاء هذه الطريقة كنسختها المُعدّة بواسطة util.promisify()، فإنها تُرجع Promise لكائن يحتوي على خصائص hostname و service.

`dns.resolve(hostname[, rrtype], callback)`

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن إلى طرح `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.27	تمت الإضافة في: v0.1.27

hostname <string> اسم المضيف المراد حله.
rrtype <string> نوع سجل المورد. الافتراضي: 'A'.
callback <Function>
- err <Error>
- records <string[]> | <Object[]> | <Object>

يستخدم بروتوكول DNS لحل اسم مضيف (مثل 'nodejs.org') إلى مصفوفة من سجلات الموارد. تحتوي دالة callback على الوسيطتين (err, records). عند النجاح، ستكون records مصفوفة من سجلات الموارد. يختلف نوع وهيكل النتائج الفردية بناءً على rrtype:

`rrtype`	`records` يحتوي على	نوع النتيجة	طريقة مختصرة
`'A'`	عناوين IPv4 (افتراضي)	<string>	`dns.resolve4()`
`'AAAA'`	عناوين IPv6	<string>	`dns.resolve6()`
`'ANY'`	أي سجلات	<Object>	`dns.resolveAny()`
`'CAA'`	سجلات تفويض CA	<Object>	`dns.resolveCaa()`
`'CNAME'`	سجلات الاسم الكنسي	<string>	`dns.resolveCname()`
`'MX'`	سجلات تبادل البريد	<Object>	`dns.resolveMx()`
`'NAPTR'`	سجلات مؤشر سلطة الاسم	<Object>	`dns.resolveNaptr()`
`'NS'`	سجلات خادم الاسم	<string>	`dns.resolveNs()`
`'PTR'`	سجلات المؤشر	<string>	`dns.resolvePtr()`
`'SOA'`	سجلات بداية السلطة	<Object>	`dns.resolveSoa()`
`'SRV'`	سجلات الخدمة	<Object>	`dns.resolveSrv()`
`'TXT'`	سجلات النص	<string[]>	`dns.resolveTxt()`

في حالة حدوث خطأ، يكون err كائنًا من نوع Error، حيث يكون err.code أحد رموز خطأ DNS.

`dns.resolve4(hostname[, options], callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن إلى إرسال `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v7.2.0	تدعم هذه الطريقة الآن تمرير `options`، وتحديداً `options.ttl`.
v0.1.16	تمت الإضافة في: v0.1.16

hostname <string> اسم المضيف المراد حله.
options <Object>
- ttl <boolean> يسترد قيمة وقت الحياة (TTL) لكل سجل. عندما تكون true، يتلقى مُعامل الاستدعاء مصفوفة من كائنات { address: '1.2.3.4', ttl: 60 } بدلاً من مصفوفة من السلاسل، مع التعبير عن TTL بالثواني.
callback <Function>
- err <Error>
- addresses <string[]> | <Object[]>

يستخدم بروتوكول DNS لحل عناوين IPv4 (A records) لـ hostname. ستحتوي وسيطة addresses الممررة إلى دالة callback على مصفوفة من عناوين IPv4 (مثل ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

`dns.resolve6(hostname[, options], callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن إلى إرسال `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v7.2.0	تدعم هذه الطريقة الآن تمرير `options`، وتحديداً `options.ttl`.
v0.1.16	تمت الإضافة في: v0.1.16

hostname <string> اسم المضيف المراد حله.
options <Object>
- ttl <boolean> يسترد قيمة وقت الحياة (TTL) لكل سجل. عندما تكون true، يتلقى مُعامل الاستدعاء مصفوفة من كائنات { address: '0:1:2:3:4:5:6:7', ttl: 60 } بدلاً من مصفوفة من السلاسل، مع التعبير عن TTL بالثواني.
callback <Function>
- err <Error>
- addresses <string[]> | <Object[]>

يستخدم بروتوكول DNS لحل عناوين IPv6 (AAAA records) لـ hostname. ستحتوي وسيطة addresses الممررة إلى دالة callback على مصفوفة من عناوين IPv6.

`dns.resolveAny(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` يلقي الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.

hostname <string>
callback <Function>
- err <Error>
- ret <Object[]>

يستخدم بروتوكول DNS لحل جميع السجلات (المعروف أيضًا باسم استعلام ANY أو *). ستكون وسيطة ret الممررة إلى دالة callback عبارة عن مصفوفة تحتوي على أنواع مختلفة من السجلات. يحتوي كل كائن على خاصية type تشير إلى نوع السجل الحالي. واعتمادًا على type، ستكون هناك خصائص إضافية موجودة في الكائن:

النوع	الخصائص
`'A'`	`address` / `ttl`
`'AAAA'`	`address` / `ttl`
`'CNAME'`	`value`
`'MX'`	راجع `dns.resolveMx()`
`'NAPTR'`	راجع `dns.resolveNaptr()`
`'NS'`	`value`
`'PTR'`	`value`
`'SOA'`	راجع `dns.resolveSoa()`
`'SRV'`	راجع `dns.resolveSrv()`
`'TXT'`	يحتوي هذا النوع من السجلات على خاصية مصفوفة تسمى `entries` تشير إلى `dns.resolveTxt()` ، على سبيل المثال `{ entries: ['...'], type: 'TXT' }`

فيما يلي مثال على كائن ret الممرر إلى دالة الاستدعاء:

;[
  { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: ['v=spf1 include:_spf.example.com ~all'] },
  {
    type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60,
  },
]

قد يختار مشغلو خوادم DNS عدم الاستجابة لاستعلامات ANY. قد يكون من الأفضل استدعاء طرق فردية مثل dns.resolve4(), dns.resolveMx()، وما إلى ذلك. لمزيد من التفاصيل، راجع RFC 8482.

`dns.resolveCname(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.3.2	تمت الإضافة في: v0.3.2

hostname <string>
callback <Function>
- err <Error>
- addresses <string[]>

يستخدم بروتوكول DNS لحل سجلات CNAME لاسم المضيف hostname. ستحتوي وسيطة addresses الممررة إلى دالة callback على مصفوفة من سجلات الاسم الكنسي المتاحة لاسم المضيف hostname (مثل ['bar.example.com']).

`dns.resolveCaa(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v15.0.0, v14.17.0	تمت الإضافة في: v15.0.0, v14.17.0

hostname <string>
callback <Function>
- err <Error>
- records <Object[]>

يستخدم بروتوكول DNS لحل سجلات CAA لاسم المضيف hostname. ستحتوي وسيطة addresses الممررة إلى دالة callback على مصفوفة من سجلات إذن هيئة إصدار الشهادات المتاحة لاسم المضيف hostname (مثل [{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]).

`dns.resolveMx(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعًى غير صالح إلى وسيطة `callback` الآن إلى إرسال `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.27	تمت الإضافة في: v0.1.27

hostname <string>
callback <Function>
- err <Error>
- addresses <Object[]>

يستخدم بروتوكول DNS لحل سجلات تبادل البريد (MX records) لـ hostname. ستحتوي وسيطة addresses المُمررة إلى دالة callback على مصفوفة من الكائنات التي تحتوي على كل من خاصية priority و exchange (مثل [{priority: 10, exchange: 'mx.example.com'}, ...]).

`dns.resolveNaptr(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعًى غير صالح إلى وسيطة `callback` الآن إلى إرسال `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.9.12	تمت الإضافة في: v0.9.12

hostname <string>
callback <Function>
- err <Error>
- addresses <Object[]>

يستخدم بروتوكول DNS لحل السجلات القائمة على التعبيرات النمطية (NAPTR records) لـ hostname. ستحتوي وسيطة addresses المُمررة إلى دالة callback على مصفوفة من الكائنات ذات الخصائص التالية:

flags
service
regexp
replacement
order
preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

`dns.resolveNs(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى خاطئ إلى وسيطة `callback` الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.90	تمت الإضافة في: v0.1.90

hostname <string>
callback <Function>
- err <Error>
- addresses <string[]>

يستخدم بروتوكول DNS لحل سجلات خادم الأسماء (NS records) لـ hostname. ستحتوي وسيطة addresses الممررة إلى دالة callback على مصفوفة من سجلات خادم الأسماء المتاحة لـ hostname (مثل ['ns1.example.com', 'ns2.example.com']).

`dns.resolvePtr(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى خاطئ إلى وسيطة `callback` الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v6.0.0	تمت الإضافة في: v6.0.0

hostname <string>
callback <Function>
- err <Error>
- addresses <string[]>

يستخدم بروتوكول DNS لحل سجلات المؤشر (PTR records) لـ hostname. ستكون وسيطة addresses الممررة إلى دالة callback عبارة عن مصفوفة من السلاسل التي تحتوي على سجلات الرد.

`dns.resolveSoa(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُدعًى خاطئ إلى وسيطة `callback` الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.11.10	تمت الإضافة في: v0.11.10

hostname <string>
callback <Function>
- err <Error>
- address <Object>

يستخدم بروتوكول DNS لحل سجل بداية السلطة (SOA record) لـ hostname. ستكون وسيطة address الممررة إلى دالة callback عبارة عن كائن ذي الخصائص التالية:

nsname
hostmaster
serial
refresh
retry
expire
minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

`dns.resolveSrv(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُنادٍ غير صالح إلى وسيطة `callback` الآن إلى طرح `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.27	تمت الإضافة في: v0.1.27

hostname <string>
callback <Function>
- err <Error>
- addresses <Object[]>

يستخدم بروتوكول DNS لحل سجلات الخدمة (SRV records) لـ hostname. ستكون وسيطة addresses المُمرّرة إلى دالة callback عبارة عن مصفوفة من الكائنات ذات الخصائص التالية:

priority
weight
port
name

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

`dns.resolveTxt(hostname, callback)`

[History]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُنادٍ غير صالح إلى وسيطة `callback` الآن إلى طرح `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.27	تمت الإضافة في: v0.1.27

hostname <string>
callback <Function>
- err <Error>
- records <string[][]>

يستخدم بروتوكول DNS لحل استعلامات النص (TXT records) لـ hostname. وسيطة records المُمرّرة إلى دالة callback هي مصفوفة ثنائية الأبعاد لسجلات النصوص المتاحة لـ hostname (مثل [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). تحتوي كل مصفوفة فرعية على أجزاء TXT لسجل واحد. بناءً على حالة الاستخدام، يمكن دمجها معًا أو معالجتها بشكل منفصل.

`dns.reverse(ip, callback)`

مضاف في: v0.1.16

ip <string>
callback <Function>
- err <Error>
- hostnames <string[]>

يقوم بعمل استعلام DNS عكسي يحول عنوان IPv4 أو IPv6 إلى مصفوفة من أسماء المضيفين.

في حالة حدوث خطأ، يكون err كائنًا من نوع Error ، حيث يكون err.code أحد أكواد خطأ DNS.

`dns.setDefaultResultOrder(order)`

[السجل]

الإصدار	التغييرات
v22.1.0, v20.13.0	يتم دعم قيمة `ipv6first` الآن.
v17.0.0	تم تغيير القيمة الافتراضية إلى `verbatim`.
v16.4.0, v14.18.0	مضاف في: v16.4.0, v14.18.0

يجب أن يكون order <string> 'ipv4first' أو 'ipv6first' أو 'verbatim'.

قم بتعيين القيمة الافتراضية لـ order في dns.lookup() و dnsPromises.lookup(). يمكن أن تكون القيمة:

ipv4first: يضع order الافتراضي على ipv4first.
ipv6first: يضع order الافتراضي على ipv6first.
verbatim: يضع order الافتراضي على verbatim.

القيمة الافتراضية هي verbatim و dns.setDefaultResultOrder() لها أولوية أعلى من --dns-result-order. عند استخدام خيوط العامل، فإن dns.setDefaultResultOrder() من الخيط الرئيسي لن يؤثر على أوامر dns الافتراضية في العمال.

`dns.getDefaultResultOrder()`

[السجل]

الإصدار	التغييرات
v22.1.0, v20.13.0	يتم دعم قيمة `ipv6first` الآن.
v20.1.0, v18.17.0	مضاف في: v20.1.0, v18.17.0

احصل على القيمة الافتراضية لـ order في dns.lookup() و dnsPromises.lookup(). يمكن أن تكون القيمة:

ipv4first: لـ order الافتراضي إلى ipv4first.
ipv6first: لـ order الافتراضي إلى ipv6first.
verbatim: لـ order الافتراضي إلى verbatim.

`dns.setServers(servers)`

مضاف في: v0.11.3

servers <string[]> مصفوفة من عناوين مُنسّقة وفقًا لـ RFC 5952

يُعيّن عنوان IP ومنفذ الخوادم التي سيتم استخدامها عند إجراء حل DNS. وُحجّة servers هي مصفوفة من عناوين مُنسّقة وفقًا لـ RFC 5952. إذا كان المنفذ هو منفذ DNS الافتراضي لـ IANA (53)، فيمكن حذفه.

dns.setServers(['8.8.8.8', '[2001:4860:4860::8888]', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053'])

سيتم إطلاق خطأ إذا تم توفير عنوان غير صالح.

يجب عدم استدعاء أسلوب dns.setServers() أثناء وجود استعلام DNS قيد التقدم.

يؤثر أسلوب dns.setServers() فقط على dns.resolve()، وdns.resolve*()، وdns.reverse() (وبالتحديد ليس dns.lookup()).

يعمل هذا الأسلوب بشكل مشابه لـ resolve.conf. وهذا يعني أنه إذا كانت محاولة الحل باستخدام الخادم الأول المُقدّم تُؤدّي إلى خطأ NOTFOUND، فلن تُحاول طريقة resolve() الحل باستخدام الخوادم اللاحقة المُقدّمة. لن يتم استخدام خوادم DNS الاحتياطية إلا إذا انتهت صلاحية الخوادم السابقة أو نتج عنها خطأ آخر.

واجهة برمجة تطبيقات وعود DNS

[السجل]

الإصدار	التغييرات
v15.0.0	مُعرّف كـ `require('dns/promises')`.
v11.14.0, v10.17.0	لم تعد هذه الواجهة البرمجية تجريبية.
v10.6.0	مُضاف في: v10.6.0

توفر واجهة برمجة تطبيقات dns.promises مجموعة بديلة من أساليب DNS غير المتزامنة التي تُعيد كائنات Promise بدلاً من استخدام المُدعيات. يمكن الوصول إلى واجهة برمجة التطبيقات عبر require('node:dns').promises أو require('node:dns/promises').

الصنف: `dnsPromises.Resolver`

مضاف في: v10.6.0

محلّل مستقل لطلبات DNS.

إنشاء محلّل جديد يستخدم إعدادات الخادم الافتراضية. إن تعيين الخوادم المستخدمة للمحلّل باستخدام resolver.setServers() لا يؤثر على المحللات الأخرى:

ESMCJS

import { Resolver } from 'node:dns/promises'
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])

// سيستخدم هذا الطلب الخادم على 4.4.4.4، بصرف النظر عن الإعدادات العالمية.
const addresses = await resolver.resolve4('example.org')

const { Resolver } = require('node:dns').promises
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])

// سيستخدم هذا الطلب الخادم على 4.4.4.4، بصرف النظر عن الإعدادات العالمية.
resolver.resolve4('example.org').then(addresses => {
  // ...
})

// بدلاً من ذلك، يمكن كتابة نفس الكود باستخدام أسلوب async-await.
;(async function () {
  const addresses = await resolver.resolve4('example.org')
})()

تتوفر أساليب التالية من واجهة برمجة تطبيقات dnsPromises:

`resolver.cancel()`

مضاف في: v15.3.0، v14.17.0

إلغاء جميع استعلامات DNS المعلقة التي قام بها هذا المُحلل. سيتم رفض الوعود المقابلة بخطأ برمز ECANCELLED.

`dnsPromises.getServers()`

مضاف في: v10.6.0

الإرجاع: <string[]>

يرجع مصفوفة من سلاسل عناوين IP، مُنسقة وفقًا لـ RFC 5952، وهي مُهيأة حاليًا لحل DNS. ستتضمن السلسلة قسمًا للمنفذ إذا تم استخدام منفذ مخصص.

;['8.8.8.8', '2001:4860:4860::8888', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053']

`dnsPromises.lookup(hostname[, options])`

[السجل]

الإصدار	التغييرات
v22.1.0، v20.13.0	أصبح خيار `verbatim` مُهملاً الآن لصالح خيار `order` الجديد.
v10.6.0	مضاف في: v10.6.0

hostname <string>
options <integer> | <Object>
- family <integer> عائلة السجل. يجب أن تكون 4 أو 6 أو 0. تشير القيمة 0 إلى إرجاع عنوان IPv4 أو IPv6. إذا تم استخدام القيمة 0 مع { all: true } (انظر أدناه)، فسيتم إرجاع عنوان IPv4 أو IPv6 أو كليهما، اعتمادًا على مُحلل DNS الخاص بالنظام. الافتراضي: 0.
- hints <number> علم واحد أو أكثر من أعلام getaddrinfo المدعومة. يمكن تمرير علامات متعددة عن طريق OR بتها.
- all <boolean> عندما تكون true، يتم حل Promise مع جميع العناوين في مصفوفة. خلاف ذلك، يتم إرجاع عنوان واحد. الافتراضي: false.
- order <string> عندما يكون verbatim، يتم حل Promise بعناوين IPv4 و IPv6 بالترتيب الذي أعاده مُحلل DNS. عندما يكون ipv4first، يتم وضع عناوين IPv4 قبل عناوين IPv6. عندما يكون ipv6first، يتم وضع عناوين IPv6 قبل عناوين IPv4. الافتراضي: verbatim (لا يتم إعادة ترتيب العناوين). القيمة الافتراضية قابلة للتكوين باستخدام dns.setDefaultResultOrder() أو --dns-result-order. يجب أن تستخدم الكود الجديد { order: 'verbatim' }.
- verbatim <boolean> عندما تكون true، يتم حل Promise بعناوين IPv4 و IPv6 بالترتيب الذي أعاده مُحلل DNS. عندما تكون false، يتم وضع عناوين IPv4 قبل عناوين IPv6. سيتم إهمال هذا الخيار لصالح order. عندما يتم تحديد كليهما، يكون لـ order أولوية أعلى. يجب أن يستخدم الكود الجديد فقط order. الافتراضي: حاليًا false (يتم إعادة ترتيب العناوين) ولكن من المتوقع أن يتغير هذا في المستقبل غير البعيد. القيمة الافتراضية قابلة للتكوين باستخدام dns.setDefaultResultOrder() أو --dns-result-order.

يحل اسم المضيف (مثل 'nodejs.org') في أول سجل A (IPv4) أو AAAA (IPv6) تم العثور عليه. جميع خصائص option اختيارية. إذا كانت options عددًا صحيحًا، فيجب أن تكون 4 أو 6 - إذا لم يتم توفير options، فسيتم إرجاع عناوين IPv4 أو IPv6 أو كليهما إذا تم العثور عليها.

مع تعيين خيار all إلى true، يتم حل Promise مع كون addresses مصفوفة من الكائنات ذات خصائص address و family.

في حالة حدوث خطأ، يتم رفض Promise باستخدام كائن Error، حيث يكون err.code هو رمز الخطأ. ضع في اعتبارك أن err.code سيتم تعيينه إلى 'ENOTFOUND' ليس فقط عندما لا يوجد اسم المضيف، ولكن أيضًا عندما يفشل البحث بطرق أخرى مثل عدم وجود مُوصِّفات ملفات متاحة.

dnsPromises.lookup() ليس بالضرورة له أي علاقة ببروتوكول DNS. يستخدم التنفيذ مرفقًا لنظام التشغيل يمكنه ربط الأسماء بالعنوان والعكس صحيح. يمكن أن يكون لهذا التنفيذ عواقب دقيقة ولكنها مهمة على سلوك أي برنامج Node.js. يُرجى أخذ بعض الوقت للرجوع إلى قسم اعتبارات التنفيذ قبل استخدام dnsPromises.lookup().

مثال على الاستخدام:

ESMCJS

import dns from 'node:dns'
const dnsPromises = dns.promises
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
}

await dnsPromises.lookup('example.org', options).then(result => {
  console.log('address: %j family: IPv%s', result.address, result.family)
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
})

// عندما يكون options.all صحيحًا، ستكون النتيجة مصفوفة.
options.all = true
await dnsPromises.lookup('example.org', options).then(result => {
  console.log('addresses: %j', result)
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
})

const dns = require('node:dns')
const dnsPromises = dns.promises
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
}

dnsPromises.lookup('example.org', options).then(result => {
  console.log('address: %j family: IPv%s', result.address, result.family)
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
})

// عندما يكون options.all صحيحًا، ستكون النتيجة مصفوفة.
options.all = true
dnsPromises.lookup('example.org', options).then(result => {
  console.log('addresses: %j', result)
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
})

`dnsPromises.lookupService(address, port)`

تم الإضافة في: v10.6.0

address <string>
port <number>

يحل محل address و port المعطيين إلى اسم مضيف وخدمة باستخدام تنفيذ getnameinfo الأساسي لنظام التشغيل.

في حالة حدوث خطأ، يتم رفض Promise باستخدام كائن Error، حيث يكون err.code هو رمز الخطأ.

ESMCJS

import dnsPromises from 'node:dns/promises'
const result = await dnsPromises.lookupService('127.0.0.1', 22)

console.log(result.hostname, result.service) // يطبع: localhost ssh

const dnsPromises = require('node:dns').promises
dnsPromises.lookupService('127.0.0.1', 22).then(result => {
  console.log(result.hostname, result.service)
  // يطبع: localhost ssh
})

`dnsPromises.resolve(hostname[, rrtype])`

تم الإضافة في: v10.6.0

hostname <string> اسم المضيف المراد حله.
rrtype <string> نوع سجل المورد. افتراضي: 'A'.

يستخدم بروتوكول DNS لحل اسم المضيف (مثل 'nodejs.org') إلى مجموعة من سجلات الموارد. عند النجاح، يتم حل Promise باستخدام مجموعة من سجلات الموارد. يختلف نوع وهيكل النتائج الفردية بناءً على rrtype:

`rrtype`	`records` يحتوي على	نوع النتيجة	طريقة مختصرة
`'A'`	عناوين IPv4 (افتراضي)	<string>	`dnsPromises.resolve4()`
`'AAAA'`	عناوين IPv6	<string>	`dnsPromises.resolve6()`
`'ANY'`	أي سجلات	<Object>	`dnsPromises.resolveAny()`
`'CAA'`	سجلات تفويض CA	<Object>	`dnsPromises.resolveCaa()`
`'CNAME'`	سجلات الاسم الكنسي	<string>	`dnsPromises.resolveCname()`
`'MX'`	سجلات تبادل البريد	<Object>	`dnsPromises.resolveMx()`
`'NAPTR'`	سجلات مؤشر سلطة الاسم	<Object>	`dnsPromises.resolveNaptr()`
`'NS'`	سجلات خادم الاسم	<string>	`dnsPromises.resolveNs()`
`'PTR'`	سجلات المؤشر	<string>	`dnsPromises.resolvePtr()`
`'SOA'`	سجلات بدء السلطة	<Object>	`dnsPromises.resolveSoa()`
`'SRV'`	سجلات الخدمة	<Object>	`dnsPromises.resolveSrv()`
`'TXT'`	سجلات النص	<string[]>	`dnsPromises.resolveTxt()`

في حالة حدوث خطأ، يتم رفض Promise باستخدام كائن Error، حيث يكون err.code أحد رموز خطأ DNS.

`dnsPromises.resolve4(hostname[, options])`

مُضاف في: v10.6.0

hostname <string> اسم المضيف المراد حله.
options <Object>
- ttl <boolean> استرجاع قيمة وقت الحياة (TTL) لكل سجل. عندما تكون true، يتم حل Promise مع مصفوفة من كائنات { address: '1.2.3.4', ttl: 60 } بدلاً من مصفوفة من السلاسل، مع التعبير عن TTL بالثواني.

يستخدم بروتوكول DNS لحل عناوين IPv4 (A records) لاسم المضيف. في حالة النجاح، يتم حل Promise مع مصفوفة من عناوين IPv4 (مثل ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

`dnsPromises.resolve6(hostname[, options])`

مُضاف في: v10.6.0

hostname <string> اسم المضيف المراد حله.
options <Object>
- ttl <boolean> استرجاع قيمة وقت الحياة (TTL) لكل سجل. عندما تكون true، يتم حل Promise مع مصفوفة من كائنات { address: '0:1:2:3:4:5:6:7', ttl: 60 } بدلاً من مصفوفة من السلاسل، مع التعبير عن TTL بالثواني.

يستخدم بروتوكول DNS لحل عناوين IPv6 (AAAA records) لاسم المضيف. في حالة النجاح، يتم حل Promise مع مصفوفة من عناوين IPv6.

`dnsPromises.resolveAny(hostname)`

مُضاف في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل جميع السجلات (المعروف أيضًا باسم استعلام ANY أو *). في حالة النجاح، يتم حل Promise مع مصفوفة تحتوي على أنواع مختلفة من السجلات. يحتوي كل كائن على خاصية type تشير إلى نوع السجل الحالي. واعتمادًا على type، ستكون هناك خصائص إضافية موجودة في الكائن:

النوع	الخصائص
`'A'`	`address` / `ttl`
`'AAAA'`	`address` / `ttl`
`'CNAME'`	`value`
`'MX'`	يُرجى الرجوع إلى `dnsPromises.resolveMx()`
`'NAPTR'`	يُرجى الرجوع إلى `dnsPromises.resolveNaptr()`
`'NS'`	`value`
`'PTR'`	`value`
`'SOA'`	يُرجى الرجوع إلى `dnsPromises.resolveSoa()`
`'SRV'`	يُرجى الرجوع إلى `dnsPromises.resolveSrv()`
`'TXT'`	يحتوي هذا النوع من السجل على خاصية مصفوفة تسمى `entries` تشير إلى `dnsPromises.resolveTxt()` ، مثل `{ entries: ['...'], type: 'TXT' }`

فيما يلي مثال لكائن النتيجة:

;[
  { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: ['v=spf1 include:_spf.example.com ~all'] },
  {
    type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60,
  },
]

`dnsPromises.resolveCaa(hostname)`

مضاف في: v15.0.0، v14.17.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات CAA لاسم المضيف hostname. عند النجاح، يتم حل Promise مع مصفوفة من الكائنات التي تحتوي على سجلات ترخيص سلطة الإصدار المتاحة لاسم المضيف hostname (مثل [{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]).

`dnsPromises.resolveCname(hostname)`

مضاف في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات CNAME لاسم المضيف hostname. عند النجاح، يتم حل Promise مع مصفوفة من سجلات الأسماء الكنسية المتاحة لاسم المضيف hostname (مثل ['bar.example.com']).

`dnsPromises.resolveMx(hostname)`

مضاف في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات تبادل البريد (MX records) لاسم المضيف hostname. عند النجاح، يتم حل Promise مع مصفوفة من الكائنات التي تحتوي على كل من خاصية priority و exchange (مثل [{priority: 10, exchange: 'mx.example.com'}, ...]).

`dnsPromises.resolveNaptr(hostname)`

مضاف في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل السجلات القائمة على التعابير النمطية (NAPTR records) لاسم المضيف hostname. عند النجاح، يتم حل Promise مع مصفوفة من الكائنات ذات الخصائص التالية:

flags
service
regexp
replacement
order
preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

`dnsPromises.resolveNs(hostname)`

مضاف في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات خادم الأسماء (NS records) لاسم المضيف hostname. عند النجاح، يتم حل Promise مع مصفوفة من سجلات خادم الأسماء المتاحة لاسم المضيف hostname (مثل ['ns1.example.com', 'ns2.example.com']).

`dnsPromises.resolvePtr(hostname)`

تم الإضافة في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات المؤشر (PTR records) لـ hostname. عند النجاح، يتم حل الـ Promise بمصفوفة من السلاسل التي تحتوي على سجلات الرد.

`dnsPromises.resolveSoa(hostname)`

تم الإضافة في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجل بدء السلطة (SOA record) لـ hostname. عند النجاح، يتم حل الـ Promise بكائن يحتوي على الخصائص التالية:

nsname
hostmaster
serial
refresh
retry
expire
minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

`dnsPromises.resolveSrv(hostname)`

تم الإضافة في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل سجلات الخدمة (SRV records) لـ hostname. عند النجاح، يتم حل الـ Promise بمصفوفة من الكائنات التي تحتوي على الخصائص التالية:

priority
weight
port
name

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

`dnsPromises.resolveTxt(hostname)`

تم الإضافة في: v10.6.0

hostname <string>

يستخدم بروتوكول DNS لحل استعلامات النص (TXT records) لـ hostname. عند النجاح، يتم حل الـ Promise بمصفوفة ثنائية الأبعاد لسجلات النص المتاحة لـ hostname (مثل [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). تحتوي كل مصفوفة فرعية على أجزاء TXT لسجل واحد. اعتمادًا على حالة الاستخدام، يمكن دمجها معًا أو معالجتها بشكل منفصل.

`dnsPromises.reverse(ip)`

مضاف في: v10.6.0

ip <string>

يقوم بعمل استعلام DNS عكسي يحل عنوان IPv4 أو IPv6 إلى مصفوفة من أسماء المضيفين.

في حالة حدوث خطأ، يتم رفض Promise باستخدام كائن Error، حيث يكون err.code أحد رموز خطأ DNS.

`dnsPromises.setDefaultResultOrder(order)`

[السجل]

الإصدار	التغييرات
v22.1.0، v20.13.0	القيمة `ipv6first` مدعومة الآن.
v17.0.0	تم تغيير القيمة الافتراضية إلى `verbatim`.
v16.4.0، v14.18.0	مضاف في: v16.4.0، v14.18.0

يجب أن يكون order <string> 'ipv4first' أو 'ipv6first' أو 'verbatim'.

قم بتعيين القيمة الافتراضية لـ order في dns.lookup() و dnsPromises.lookup(). يمكن أن تكون القيمة:

ipv4first: يُعيّن order الافتراضي إلى ipv4first.
ipv6first: يُعيّن order الافتراضي إلى ipv6first.
verbatim: يُعيّن order الافتراضي إلى verbatim.

القيمة الافتراضية هي verbatim و dnsPromises.setDefaultResultOrder() لها أولوية أعلى من --dns-result-order. عند استخدام خيوط العامل، فإن dnsPromises.setDefaultResultOrder() من الخيط الرئيسي لن يؤثر على أوامر dns الافتراضية في العمال.

`dnsPromises.getDefaultResultOrder()`

مضاف في: v20.1.0، v18.17.0

احصل على قيمة dnsOrder.

`dnsPromises.setServers(servers)`

مضاف في: v10.6.0

servers <string[]> مصفوفة من العناوين المُنسّقة وفقًا لـ RFC 5952

يُعيّن عنوان IP ومنفذ الخوادم التي سيتم استخدامها عند إجراء حل DNS. حجة servers هي مصفوفة من العناوين المُنسّقة وفقًا لـ RFC 5952. إذا كان المنفذ هو منفذ DNS الافتراضي لـ IANA (53)، فيمكن حذفها.

dnsPromises.setServers(['8.8.8.8', '[2001:4860:4860::8888]', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053'])

سيتم إطلاق خطأ إذا تم توفير عنوان غير صالح.

يجب عدم استدعاء أسلوب dnsPromises.setServers() أثناء جاري تنفيذ استعلام DNS.

يعمل هذا الأسلوب بشكل مشابه لـ resolve.conf. وهذا يعني، إذا كانت محاولة الحل باستخدام الخادم الأول المُقدّم تؤدي إلى خطأ NOTFOUND، فإن أسلوب resolve() لن يحاول الحل باستخدام الخوادم اللاحقة المُقدّمة. لن يتم استخدام خوادم DNS الاحتياطية إلا إذا انتهت مهلة الخوادم السابقة أو نتج عنها خطأ آخر.

أكواد الخطأ

يمكن لكل استعلام DNS أن يُرجع أحد أكواد الخطأ التالية:

dns.NODATA: قام خادم DNS بإرجاع إجابة بدون بيانات.
dns.FORMERR: يدعي خادم DNS أن الاستعلام تم تنسيقه بشكل خاطئ.
dns.SERVFAIL: قام خادم DNS بإرجاع فشل عام.
dns.NOTFOUND: لم يتم العثور على اسم المجال.
dns.NOTIMP: لا يقوم خادم DNS بتنفيذ العملية المطلوبة.
dns.REFUSED: رفض خادم DNS الاستعلام.
dns.BADQUERY: استعلام DNS بتنسيق خاطئ.
dns.BADNAME: اسم مضيف بتنسيق خاطئ.
dns.BADFAMILY: عائلة عنوان غير مدعومة.
dns.BADRESP: رد DNS بتنسيق خاطئ.
dns.CONNREFUSED: تعذر الاتصال بخوادم DNS.
dns.TIMEOUT: انقضاء مهلة الاتصال بخوادم DNS.
dns.EOF: نهاية الملف.
dns.FILE: خطأ في قراءة الملف.
dns.NOMEM: نفاد الذاكرة.
dns.DESTRUCTION: يتم تدمير القناة.
dns.BADSTR: سلسلة بتنسيق خاطئ.
dns.BADFLAGS: تم تحديد علامات غير قانونية.
dns.NONAME: اسم المضيف المعطى ليس رقميًا.
dns.BADHINTS: تم تحديد علامات تلميحات غير قانونية.
dns.NOTINITIALIZED: لم يتم بعد إجراء تهيئة مكتبة c-ares.
dns.LOADIPHLPAPI: خطأ في تحميل iphlpapi.dll.
dns.ADDRGETNETWORKPARAMS: تعذر العثور على دالة GetNetworkParams.
dns.CANCELLED: تم إلغاء استعلام DNS.

يقوم واجهة برمجة التطبيقات dnsPromises أيضًا بتصدير أكواد الخطأ المذكورة أعلاه، مثل dnsPromises.NODATA.

اعتبارات التنفيذ

على الرغم من أن وظيفتي dns.lookup() ووظائف dns.resolve*()/dns.reverse() المختلفة لها نفس الهدف المتمثل في ربط اسم الشبكة بعنوان الشبكة (أو العكس)، إلا أن سلوكها مختلف تمامًا. هذه الاختلافات يمكن أن يكون لها عواقب دقيقة ولكنها كبيرة على سلوك برامج Node.js.

`dns.lookup()`

تستخدم dns.lookup() تحت الغطاء نفس مرافق نظام التشغيل مثل معظم البرامج الأخرى. على سبيل المثال، ستقوم dns.lookup() في جميع الأحوال تقريبًا بحل اسم معين بنفس طريقة الأمر ping. على معظم أنظمة التشغيل الشبيهة بـ POSIX، يمكن تعديل سلوك دالة dns.lookup() عن طريق تغيير الإعدادات في nsswitch.conf(5) و/أو resolv.conf(5)، ولكن تغيير هذه الملفات سيغير سلوك جميع البرامج الأخرى التي تعمل على نفس نظام التشغيل.

على الرغم من أن المكالمة إلى dns.lookup() ستكون غير متزامنة من منظور JavaScript، إلا أنها مُنفذة كمكالمة متزامنة إلى getaddrinfo(3) التي تعمل على مجموعة مؤشرات الترابط الخاصة بـ libuv. هذا يمكن أن يكون له آثار سلبية مفاجئة على الأداء لبعض التطبيقات، راجع وثائق UV_THREADPOOL_SIZE لمزيد من المعلومات.

ستقوم واجهات برمجة تطبيقات الشبكات المختلفة بالاتصال بـ dns.lookup() داخليًا لحل أسماء المضيفين. إذا كانت هذه مشكلة، فكر في حل اسم المضيف إلى عنوان باستخدام dns.resolve() واستخدام العنوان بدلاً من اسم المضيف. أيضًا، تسمح بعض واجهات برمجة تطبيقات الشبكات (مثل socket.connect() و dgram.createSocket()) باستبدال مُحلل القيم الافتراضي، dns.lookup().

`dns.resolve()`, `dns.resolve*()`, و `dns.reverse()`

تم تنفيذ هذه الوظائف بشكل مختلف تمامًا عن dns.lookup(). إنها لا تستخدم getaddrinfo(3) وهي دائمًا تقوم باستعلام DNS على الشبكة. يتم إجراء هذا الاتصال بالشبكة دائمًا بشكل غير متزامن ولا يستخدم تجمع مؤشرات الترابط libuv.

نتيجة لذلك، لا يمكن أن يكون لهذه الوظائف نفس التأثير السلبي على المعالجة الأخرى التي تحدث في تجمع مؤشرات الترابط libuv والتي يمكن أن يكون لها dns.lookup().

إنها لا تستخدم نفس مجموعة ملفات التكوين التي يستخدمها dns.lookup(). على سبيل المثال، إنها لا تستخدم التكوين من /etc/hosts.

DNS ​

الصنف: dns.Resolver ​

Resolver([options]) ​

resolver.cancel() ​

resolver.setLocalAddress([ipv4][, ipv6]) ​

dns.getServers() ​

dns.lookup(hostname[, options], callback) ​

علامات getaddrinfo المدعومة ​

dns.lookupService(address, port, callback) ​

dns.resolve(hostname[, rrtype], callback) ​

dns.resolve4(hostname[, options], callback) ​

dns.resolve6(hostname[, options], callback) ​

dns.resolveAny(hostname, callback) ​

dns.resolveCname(hostname, callback) ​

dns.resolveCaa(hostname, callback) ​

dns.resolveMx(hostname, callback) ​

dns.resolveNaptr(hostname, callback) ​

dns.resolveNs(hostname, callback) ​

dns.resolvePtr(hostname, callback) ​

dns.resolveSoa(hostname, callback) ​

dns.resolveSrv(hostname, callback) ​

dns.resolveTxt(hostname, callback) ​

dns.reverse(ip, callback) ​

dns.setDefaultResultOrder(order) ​

dns.getDefaultResultOrder() ​

dns.setServers(servers) ​

واجهة برمجة تطبيقات وعود DNS ​

الصنف: dnsPromises.Resolver ​

resolver.cancel() ​

dnsPromises.getServers() ​

dnsPromises.lookup(hostname[, options]) ​

dnsPromises.lookupService(address, port) ​

dnsPromises.resolve(hostname[, rrtype]) ​

dnsPromises.resolve4(hostname[, options]) ​

dnsPromises.resolve6(hostname[, options]) ​

dnsPromises.resolveAny(hostname) ​

dnsPromises.resolveCaa(hostname) ​

dnsPromises.resolveCname(hostname) ​

dnsPromises.resolveMx(hostname) ​

dnsPromises.resolveNaptr(hostname) ​

dnsPromises.resolveNs(hostname) ​

dnsPromises.resolvePtr(hostname) ​

dnsPromises.resolveSoa(hostname) ​

dnsPromises.resolveSrv(hostname) ​

dnsPromises.resolveTxt(hostname) ​

dnsPromises.reverse(ip) ​

dnsPromises.setDefaultResultOrder(order) ​

dnsPromises.getDefaultResultOrder() ​

dnsPromises.setServers(servers) ​

أكواد الخطأ ​

اعتبارات التنفيذ ​

dns.lookup() ​

dns.resolve(), dns.resolve*(), و dns.reverse() ​

DNS

الصنف: `dns.Resolver`

`Resolver([options])`

`resolver.cancel()`

`resolver.setLocalAddress([ipv4][, ipv6])`

`dns.getServers()`

`dns.lookup(hostname[, options], callback)`

علامات getaddrinfo المدعومة

`dns.lookupService(address, port, callback)`

`dns.resolve(hostname[, rrtype], callback)`

`dns.resolve4(hostname[, options], callback)`

`dns.resolve6(hostname[, options], callback)`

`dns.resolveAny(hostname, callback)`

`dns.resolveCname(hostname, callback)`

`dns.resolveCaa(hostname, callback)`

`dns.resolveMx(hostname, callback)`

`dns.resolveNaptr(hostname, callback)`

`dns.resolveNs(hostname, callback)`

`dns.resolvePtr(hostname, callback)`

`dns.resolveSoa(hostname, callback)`

`dns.resolveSrv(hostname, callback)`

`dns.resolveTxt(hostname, callback)`

`dns.reverse(ip, callback)`

`dns.setDefaultResultOrder(order)`

`dns.getDefaultResultOrder()`

`dns.setServers(servers)`

واجهة برمجة تطبيقات وعود DNS

الصنف: `dnsPromises.Resolver`

`resolver.cancel()`

`dnsPromises.getServers()`

`dnsPromises.lookup(hostname[, options])`

`dnsPromises.lookupService(address, port)`

`dnsPromises.resolve(hostname[, rrtype])`

`dnsPromises.resolve4(hostname[, options])`

`dnsPromises.resolve6(hostname[, options])`

`dnsPromises.resolveAny(hostname)`

`dnsPromises.resolveCaa(hostname)`

`dnsPromises.resolveCname(hostname)`

`dnsPromises.resolveMx(hostname)`

`dnsPromises.resolveNaptr(hostname)`

`dnsPromises.resolveNs(hostname)`

`dnsPromises.resolvePtr(hostname)`

`dnsPromises.resolveSoa(hostname)`

`dnsPromises.resolveSrv(hostname)`

`dnsPromises.resolveTxt(hostname)`

`dnsPromises.reverse(ip)`

`dnsPromises.setDefaultResultOrder(order)`

`dnsPromises.getDefaultResultOrder()`

`dnsPromises.setServers(servers)`

أكواد الخطأ

اعتبارات التنفيذ

`dns.lookup()`

`dns.resolve()`, `dns.resolve*()`, و `dns.reverse()`