Node.js v21.7.2 ドキュメント

クラス: `dns.Resolver`#

DNSリクエストのための独立したリゾルバです。

新しいリゾルバの作成には、デフォルトのサーバー設定が使用されます。`resolver.setServers()` を使用してリゾルバで使用されるサーバーを設定しても、他のリゾルバには影響しません。

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

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
}); copy

`node:dns` モジュールの次のメソッドを使用できます。

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

`Resolver([options])`#

新しいリゾルバを作成します。

• `options` <オブジェクト>
  • `timeout` <整数> ミリ秒単位のクエリタイムアウト、またはデフォルトのタイムアウトを使用する場合は `-1`。
  • `tries` <整数> リゾルバが諦める前に各ネームサーバーへの接続を試行する回数。**デフォルト: ** `4`

`resolver.cancel()`#

このリゾルバによって行われた未処理のすべてのDNSクエリをキャンセルします。対応するコールバックは、コード `ECANCELLED` のエラーで呼び出されます。

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

• `ipv4` <文字列> IPv4アドレスの文字列表現。**デフォルト: ** `'0.0.0.0'`
• `ipv6` <文字列> IPv6アドレスの文字列表現。**デフォルト: ** `'::0'`

リゾルバインスタンスは、指定されたIPアドレスからリクエストを送信します。これにより、マルチホームシステムで使用する場合、アウトバウンドインターフェースを指定できます。

v4またはv6アドレスが指定されていない場合、デフォルトに設定され、オペレーティングシステムが自動的にローカルアドレスを選択します。

リゾルバは、IPv4 DNSサーバーへのリクエストを行う際にv4ローカルアドレスを使用し、IPv6 DNSサーバーへのリクエストを行う際にv6ローカルアドレスを使用します。解決リクエストの`rrtype`は、使用されるローカルアドレスに影響しません。

`dns.getServers()`#

• 戻り値: <文字列[]>

RFC 5952に従ってフォーマットされた、現在DNS解決用に構成されているIPアドレス文字列の配列を返します。カスタムポートが使用されている場合、文字列にはポートセクションが含まれます。

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

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

• `hostname` <文字列>
• `options` <整数> | <オブジェクト>
  • `family` <整数> | <文字列> レコードファミリ。`4`、`6`、または`0`である必要があります。後方互換性の理由から、`'IPv4'`および`'IPv6'`はそれぞれ`4`および`6`として解釈されます。値`0`は、IPv4アドレスまたはIPv6アドレスのいずれかが返されることを示します。値`0`を`{all: true}`（下記参照）とともに使用すると、IPv4アドレスとIPv6アドレスの両方が返されます。**デフォルト: ** `0`。
  • `hints` <数値> 1つ以上のサポートされている`getaddrinfo`フラグ。複数のフラグは、ビットごとの`OR`演算を使用して渡すことができます。
  • `all` <ブール値> `true`の場合、コールバックは解決されたすべてのアドレスを配列で返します。それ以外の場合は、単一のアドレスを返します。**デフォルト: ** `false`。
  • `verbatim` <ブール値> `true`の場合、コールバックはDNSリゾルバが返した順序でIPv4アドレスとIPv6アドレスを受け取ります。`false`の場合、IPv4アドレスがIPv6アドレスの前に配置されます。**デフォルト: ** `true`（アドレスは並べ替えられません）。デフォルト値は、`dns.setDefaultResultOrder()`または`--dns-result-order`を使用して構成できます。
• `callback` <関数>
  • `err` <エラー>
  • `address` <文字列> IPv4アドレスまたはIPv6アドレスの文字列表現。
  • `family` <整数> `address`のファミリを示す`4`または`6`、またはアドレスがIPv4アドレスまたはIPv6アドレスでない場合は`0`。`0`は、オペレーティングシステムで使用されている名前解決サービスのバグを示す可能性が高い指標です。

ホスト名（例：`'nodejs.org'`）を最初に検出されたA（IPv4）またはAAAA（IPv6）レコードに解決します。すべての`option`プロパティはオプションです。`options`が整数の場合、`4`または`6`である必要があります。`options`が`0`の場合、または提供されていない場合、見つかった場合はIPv4アドレスとIPv6アドレスの両方が返されます。

`all`オプションが`true`に設定されている場合、`callback`の引数は`（err、addresses）`に変更され、`addresses`は`address`と`family`のプロパティを持つオブジェクトの配列になります。

エラーが発生した場合、err は Error オブジェクトになり、err.code にはエラーコードが設定されます。 err.code はホスト名が存在しない場合だけでなく、ファイル記述子が使用できないなど、他の理由でルックアップに失敗した場合にも 'ENOTFOUND' に設定されることに注意してください。

dns.lookup() は必ずしもDNSプロトコルに関連しているわけではありません。実装では、名前とアドレスを相互に関連付けることができるオペレーティングシステムの機能を使用しています。この実装は、任意のNode.jsプログラムの動作に微妙だが重要な影響を与える可能性があります。dns.lookup() を使用する前に、実装上の考慮事項のセクション を参照してください。

使用例

const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.com', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] copy

このメソッドが util.promisify() でPromise化されたバージョンとして呼び出され、all が true に設定されていない場合、address と family プロパティを持つObjectに対するPromiseを返します。

サポートされているgetaddrinfoフラグ#

以下のフラグをヒントとして dns.lookup() に渡すことができます。

• dns.ADDRCONFIG: 返されるアドレスの種類を、システム上で設定されている非ループバックアドレスの種類に制限します。たとえば、現在のシステムに少なくとも1つのIPv4アドレスが設定されている場合にのみ、IPv4アドレスが返されます。
• dns.V4MAPPED: IPv6ファミリが指定されたが、IPv6アドレスが見つからない場合、IPv4マッピングされたIPv6アドレスを返します。一部のオペレーティングシステム（例：FreeBSD 10.1）ではサポートされていません。
• dns.ALL: dns.V4MAPPED が指定されている場合、解決されたIPv6アドレスとIPv4マッピングされたIPv6アドレスの両方を返します。

dns.lookupService(address, port, callback)#

• address <文字列>
• port <数値>
• `callback` <関数>
  • `err` <エラー>
  • hostname <文字列> 例：example.com
  • service <文字列> 例：http

オペレーティングシステムの基盤となるgetnameinfo実装を使用して、指定されたaddressとportをホスト名とサービスに解決します。

addressが有効なIPアドレスでない場合、TypeErrorがスローされます。portは数値に変換されます。有効なポートでない場合、TypeErrorがスローされます。

エラーが発生した場合、err は Error オブジェクトになり、err.code にはエラーコードが設定されます。

const dns = require('node:dns');
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
}); copy

このメソッドが util.promisify() でPromise化されたバージョンとして呼び出された場合、hostnameとserviceプロパティを持つObjectに対するPromiseを返します。

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

• hostname <文字列> 解決するホスト名。
• rrtype <文字列> リソースレコードの種類。**デフォルト:** 'A'。
• `callback` <関数>
  • `err` <エラー>
  • records <文字列[]> | <オブジェクト[]> | <オブジェクト>

DNSプロトコルを使用して、ホスト名（例：'nodejs.org'）をリソースレコードの配列に解決します。callback関数の引数は(err, records)です。成功すると、recordsはリソースレコードの配列になります。個々の結果の型と構造は、rrtypeによって異なります。

エラーが発生した場合、err は Error オブジェクトになり、err.code には DNSエラーコード のいずれかが設定されます。

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

• hostname <文字列> 解決するホスト名。
• `options` <オブジェクト>
  • ttl <真偽値> 各レコードの存続可能時間（TTL）を取得します。trueの場合、コールバックは文字列の配列ではなく、{ address: '1.2.3.4', ttl: 60 }オブジェクトの配列を受け取ります。TTLは秒単位で表されます。
• `callback` <関数>
  • `err` <エラー>
  • addresses <文字列[]> | <オブジェクト[]>

DNSプロトコルを使用して、hostnameのIPv4アドレス（Aレコード）を解決します。callback関数に渡されるaddresses引数には、IPv4アドレスの配列が含まれます（例：['74.125.79.104', '74.125.79.105', '74.125.79.106']）。

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

• hostname <文字列> 解決するホスト名。
• `options` <オブジェクト>
  • ttl <真偽値> 各レコードの存続可能時間（TTL）を取得します。trueの場合、コールバックは文字列の配列ではなく、{ address: '0:1:2:3:4:5:6:7', ttl: 60 }オブジェクトの配列を受け取ります。TTLは秒単位で表されます。
• `callback` <関数>
  • `err` <エラー>
  • addresses <文字列[]> | <オブジェクト[]>

DNSプロトコルを使用して、hostnameのIPv6アドレス（AAAAレコード）を解決します。callback関数に渡されるaddresses引数には、IPv6アドレスの配列が含まれます。

dns.resolveAny(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • ret <オブジェクト[]>

DNSプロトコルを使用して、すべてのレコード（ANYまたは*クエリとも呼ばれる）を解決します。callback関数に渡されるret引数は、さまざまな種類のレコードを含む配列になります。各オブジェクトには、現在のレコードの種類を示すtypeプロパティがあります。そして、typeに応じて、オブジェクトに追加のプロパティが存在します。

コールバックに渡される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 } ] copy

DNSサーバーオペレーターは、ANYクエリに応答しないように選択できます。dns.resolve4()、dns.resolveMx()など、個々のメソッドを呼び出した方が良い場合があります。詳細については、RFC 8482を参照してください。

dns.resolveCname(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <文字列[]>

DNSプロトコルを使用して、hostnameのCNAMEレコードを解決します。callback関数に渡されるaddresses引数には、hostnameで使用可能な正規名レコードの配列が含まれます（例：['bar.example.com']）。

dns.resolveCaa(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • records <オブジェクト[]>

DNSプロトコルを使用して、hostnameのCAAレコードを解決します。callback関数に渡されるaddresses引数には、hostnameで使用可能な認証局認証レコードの配列が含まれます（例：[{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]）。

dns.resolveMx(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <オブジェクト[]>

ホスト名 (hostname) のメール交換レコード (MX レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される addresses 引数には、priority プロパティと exchange プロパティを持つオブジェクトの配列が含まれます (例: [{priority: 10, exchange: 'mx.example.com'}, ...])。

dns.resolveMx(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <オブジェクト[]>

ホスト名 (hostname) の正規表現ベースのレコード (NAPTR レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される addresses 引数には、以下のプロパティを持つオブジェクトの配列が含まれます。

• flags
• service
• regexp
• replacement
• order
• preference

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

dns.resolveNaptr(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <文字列[]>

ホスト名 (hostname) の名前サーバレコード (NS レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される addresses 引数には、hostname に使用可能な名前サーバレコードの配列が含まれます (例: ['ns1.example.com', 'ns2.example.com'])。

dns.resolveNs(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <文字列[]>

ホスト名 (hostname) のポインタレコード (PTR レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される addresses 引数には、応答レコードを含む文字列の配列が含まれます。

dns.resolvePtr(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • address <Object>

ホスト名 (hostname) の権限開始レコード (SOA レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される address 引数には、以下のプロパティを持つオブジェクトが含まれます。

• 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
} copy

dns.resolveSoa(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • addresses <オブジェクト[]>

ホスト名 (hostname) のサービスレコード (SRV レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される addresses 引数には、以下のプロパティを持つオブジェクトの配列が含まれます。

• priority
• weight
• port
• name

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

dns.resolveSrv(hostname, callback)#

• `hostname` <文字列>
• `callback` <関数>
  • `err` <エラー>
  • records <string[][]>

ホスト名 (hostname) のテキストクエリ (TXT レコード) をDNSプロトコルを使用して解決します。callback 関数に渡される records 引数には、hostname に使用可能なテキストレコードの二次元配列が含まれます (例: [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ])。各サブ配列には、1つのレコードのTXTチャンクが含まれています。ユースケースによっては、これらを結合するか、個別に扱うことができます。

dns.reverse(ip, callback)#

• ip <string>
• `callback` <関数>
  • `err` <エラー>
  • hostnames <string[]>

IPv4またはIPv6アドレスをホスト名の配列に解決する逆DNSクエリを実行します。

エラーが発生した場合、err は Error オブジェクトになり、err.code には DNSエラーコード のいずれかが設定されます。

dns.setDefaultResultOrder(order)#

• order <string> は 'ipv4first' または 'verbatim' でなければなりません。

dns.lookup() と dnsPromises.lookup() のデフォルト値 verbatim を設定します。値は次のとおりです。

• ipv4first: デフォルトの verbatim を false に設定します。
• verbatim: デフォルトの verbatim を true に設定します。

デフォルトは verbatim であり、dns.setDefaultResultOrder() は --dns-result-order よりも優先されます。 ワーカー スレッド を使用する場合、メインスレッドからの dns.setDefaultResultOrder() は、ワーカーのデフォルトのDNS順序に影響しません。

dns.getDefaultResultOrder()#

dns.lookup() と dnsPromises.lookup() の verbatim のデフォルト値を取得します。値は次のとおりです。

• ipv4first: verbatim のデフォルトを false にします。
• verbatim: verbatim のデフォルトを true にします。

dns.setServers(servers)#

• servers <string[]> RFC 5952 形式のアドレスの配列

DNS解決を実行する際に使用するサーバのIPアドレスとポートを設定します。servers 引数は、RFC 5952 形式のアドレスの配列です。ポートがIANAのデフォルトのDNSポート(53)の場合は、省略できます。

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

無効なアドレスが指定された場合は、エラーが発生します。

DNSクエリの実行中は、dns.setServers() メソッドを呼び出すことはできません。

dns.setServers() メソッドは、dns.resolve()、dns.resolve*()、および dns.reverse() にのみ影響します（特に dns.lookup() には影響しません）。

このメソッドは、resolve.conf と非常によく似ています。つまり、最初に指定されたサーバーで解決を試みた結果、NOTFOUND エラーが発生した場合、resolve() メソッドは、その後続のサーバーで解決を試みません。フォールバックDNSサーバーは、前のサーバーがタイムアウトした場合、またはその他のエラーが発生した場合にのみ使用されます。

DNS promises API#

dns.promises APIは、コールバックを使用する代わりにPromiseオブジェクトを返す非同期DNSメソッドの代替セットを提供します。このAPIは、require('node:dns').promisesまたはrequire('node:dns/promises')を介してアクセスできます。

クラス: dnsPromises.Resolver#

DNSリクエストのための独立したリゾルバです。

新しいレゾルバーの作成には、デフォルトのサーバー設定が使用されます。resolver.setServers() を使用してレゾルバーで使用されるサーバーを設定しても、他のレゾルバーには影響しません。

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

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org').then((addresses) => {
  // ...
});

// Alternatively, the same code can be written using async-await style.
(async function() {
  const addresses = await resolver.resolve4('example.org');
})(); copy

dnsPromises APIの以下のメソッドを使用できます。

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

resolver.cancel()#

このレゾルバーによって行われた未処理のすべてのDNSクエリをキャンセルします。対応するPromiseは、コードECANCELLEDのエラーで拒否されます。

dnsPromises.getServers()#

• 戻り値: <文字列[]>

RFC 5952に従ってフォーマットされた、現在DNS解決用に構成されているIPアドレス文字列の配列を返します。カスタムポートが使用されている場合、文字列にはポートセクションが含まれます。

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

dnsPromises.lookup(hostname[, options])#

• `hostname` <文字列>
• `options` <整数> | <オブジェクト>
  • family <integer> レコードファミリ。4、6、または0でなければなりません。値0は、IPv4またはIPv6アドレスのいずれかが返されることを示します。値0を{ all: true }（下記参照）と共に使用すると、IPv4とIPv6の両方のアドレスが返されます。**デフォルト:** 0。
  • `hints` <数値> 1つ以上のサポートされている`getaddrinfo`フラグ。複数のフラグは、ビットごとの`OR`演算を使用して渡すことができます。
  • all <boolean> trueの場合、Promiseは配列内のすべてのアドレスで解決されます。それ以外の場合は、単一のアドレスを返します。**デフォルト:** false。
  • verbatim <boolean> trueの場合、PromiseはDNSレゾルバーが返した順序でIPv4とIPv6アドレスで解決されます。falseの場合、IPv4アドレスがIPv6アドレスの前に配置されます。**デフォルト:** 現在false（アドレスは並べ替えられます）ですが、近い将来変更される予定です。デフォルト値は、dns.setDefaultResultOrder()または--dns-result-orderを使用して設定できます。新しいコードでは、{ verbatim: true }を使用する必要があります。

ホスト名（例：'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()を使用してください。

使用例

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

dnsPromises.lookup('example.com', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.com', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
}); copy

dnsPromises.lookupService(address, port)#

• address <文字列>
• port <数値>

オペレーティングシステムの基盤となるgetnameinfo実装を使用して、指定されたaddressとportをホスト名とサービスに解決します。

addressが有効なIPアドレスでない場合、TypeErrorがスローされます。portは数値に変換されます。有効なポートでない場合、TypeErrorがスローされます。

エラーが発生した場合、PromiseはErrorオブジェクトで拒否されます。ここで、err.codeはエラーコードです。

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

dnsPromises.resolve(hostname[, rrtype])#

• hostname <文字列> 解決するホスト名。
• rrtype <文字列> リソースレコードの種類。**デフォルト:** 'A'。

ホスト名（例：'nodejs.org'）をリソースレコードの配列に解決するためにDNSプロトコルを使用します。正常に完了した場合、Promiseはリソースレコードの配列で解決されます。個々の結果のタイプと構造は、rrtypeに基づいて異なります。

エラーが発生した場合、PromiseはErrorオブジェクトで拒否され、err.codeにはDNSエラーコードのいずれかが設定されます。

dnsPromises.resolve4(hostname[, options])#

• hostname <文字列> 解決するホスト名。
• `options` <オブジェクト>
  • ttl <boolean> 各レコードの存続可能時間値（TTL）を取得します。trueの場合、Promiseは文字列の配列ではなく、{ address: '1.2.3.4', ttl: 60 }オブジェクトの配列で解決され、TTLは秒単位で表されます。

ホスト名に対して、DNSプロトコルを用いてIPv4アドレス（Aレコード）を解決します。成功した場合、PromiseはIPv4アドレスの配列（例：['74.125.79.104', '74.125.79.105', '74.125.79.106']）を解決値として返します。

dnsPromises.resolve6(hostname[, options])#

• hostname <文字列> 解決するホスト名。
• `options` <オブジェクト>
  • ttl <boolean> 各レコードのTime-To-Live値（TTL）を取得します。trueの場合、Promiseは文字列の配列ではなく、TTLを秒単位で表した{ address: '0:1:2:3:4:5:6:7', ttl: 60 }オブジェクトの配列を解決値として返します。

ホスト名に対して、DNSプロトコルを用いてIPv6アドレス（AAAAレコード）を解決します。成功した場合、PromiseはIPv6アドレスの配列を解決値として返します。

dnsPromises.resolveAny(hostname)#

• `hostname` <文字列>

DNSプロトコルを用いて、すべてのレコード（ANYまたは*クエリとも呼ばれる）を解決します。成功した場合、Promiseは様々な種類のレコードを含む配列を解決値として返します。各オブジェクトには、現在のレコードの種類を示すtypeプロパティがあります。そして、typeに応じて、オブジェクトに追加のプロパティが存在します。

結果オブジェクトの例を以下に示します。

[ { 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 } ] copy

dnsPromises.resolveCaa(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてCAAレコードを解決します。成功した場合、Promiseはホスト名で使用可能な認証局認証レコードを含むオブジェクトの配列を解決値として返します（例：[{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]）。

dnsPromises.resolveCname(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてCNAMEレコードを解決します。成功した場合、Promiseはホスト名で使用可能な正規名レコードの配列を解決値として返します（例：['bar.example.com']）。

dnsPromises.resolveMx(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてメール交換レコード（MXレコード）を解決します。成功した場合、Promiseはpriorityプロパティとexchangeプロパティを含むオブジェクトの配列を解決値として返します（例：[{priority: 10, exchange: 'mx.example.com'}, ...]）。

dnsPromises.resolveNaptr(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いて正規表現ベースのレコード（NAPTRレコード）を解決します。成功した場合、Promiseは次のプロパティを持つオブジェクトの配列を解決値として返します。

• flags
• service
• regexp
• replacement
• order
• preference

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

dnsPromises.resolveNs(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてネームサーバーレコード（NSレコード）を解決します。成功した場合、Promiseはホスト名で使用可能なネームサーバーレコードの配列を解決値として返します（例：['ns1.example.com', 'ns2.example.com']）。

dnsPromises.resolvePtr(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてポインターレコード（PTRレコード）を解決します。成功した場合、Promiseは応答レコードを含む文字列の配列を解決値として返します。

dnsPromises.resolveSoa(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いて権限開始レコード（SOAレコード）を解決します。成功した場合、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
} copy

dnsPromises.resolveSrv(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてサービスレコード（SRVレコード）を解決します。成功した場合、Promiseは次のプロパティを持つオブジェクトの配列を解決値として返します。

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)#

• `hostname` <文字列>

ホスト名に対して、DNSプロトコルを用いてテキストクエリ（TXTレコード）を解決します。成功した場合、Promiseはホスト名で使用可能なテキストレコードの二次元配列を解決値として返します（例：[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]）。各サブ配列は1つのレコードのTXTチャンクを含みます。ユースケースによっては、これらを連結するか、個別に処理するかを選択できます。

dnsPromises.reverse(ip)#

• ip <string>

IPv4またはIPv6アドレスをホスト名の配列に解決する逆DNSクエリを実行します。

エラーが発生した場合、PromiseはErrorオブジェクトで拒否され、err.codeにはDNSエラーコードのいずれかが設定されます。

dnsPromises.setDefaultResultOrder(order)#

• order <string> は 'ipv4first' または 'verbatim' でなければなりません。

dns.lookup() と dnsPromises.lookup() のデフォルト値 verbatim を設定します。値は次のとおりです。

• ipv4first: デフォルトの verbatim を false に設定します。
• verbatim: デフォルトの verbatim を true に設定します。

デフォルトはverbatimであり、dnsPromises.setDefaultResultOrder()は--dns-result-orderよりも優先順位が高くなります。ワーカースレッドを使用する場合、メインスレッドからのdnsPromises.setDefaultResultOrder()は、ワーカーのデフォルトのDNS順序に影響しません。

dnsPromises.getDefaultResultOrder()#

dnsOrderの値を取得します。

dnsPromises.setServers(servers)#

• servers <string[]> RFC 5952 形式のアドレスの配列

DNS解決を実行する際に使用するサーバのIPアドレスとポートを設定します。servers 引数は、RFC 5952 形式のアドレスの配列です。ポートがIANAのデフォルトのDNSポート(53)の場合は、省略できます。

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

無効なアドレスが指定された場合は、エラーが発生します。

DNSクエリが実行中の間は、dnsPromises.setServers()メソッドを呼び出さないでください。

このメソッドは、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 APIは、上記のエラーコード（例：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の観点からは非同期ですが、libuvのスレッドプール上で実行されるgetaddrinfo(3)への同期呼び出しとして実装されています。これは、一部のアプリケーションで驚くべき負の性能影響を与える可能性があります。詳細については、UV_THREADPOOL_SIZEのドキュメントを参照してください。

様々なネットワークAPIは、内部的にホスト名を解決するためにdns.lookup()を呼び出します。それが問題となる場合は、dns.resolve()を使用してホスト名をアドレスに解決し、ホスト名ではなくアドレスを使用することを検討してください。また、一部のネットワークAPI（socket.connect()やdgram.createSocket()など）では、デフォルトのレゾルバーdns.lookup()を置き換えることができます。

dns.resolve()、dns.resolve*()、およびdns.reverse()#

これらの関数は、dns.lookup()とはかなり異なる方法で実装されています。getaddrinfo(3)を使用せず、常にネットワーク上でDNSクエリを実行します。このネットワーク通信は常に非同期で行われ、libuvのスレッドプールを使用しません。

その結果、これらの関数は、dns.lookup()が持つ可能性のある、libuvのスレッドプールで行われる他の処理に対する同じような負の影響を与えることはありません。

これらの関数は、dns.lookup()が使用するのと同じ設定ファイルのセットを使用しません。たとえば、/etc/hostsの設定は使用しません。