Constructor

Zone

new Zone()

A Zone object is used to interact with your project's managed zone. It will help you add or delete records, delete your zone, and many other convenience methods.

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const zone = dns.zone('zone-id');

Properties

baseUrl

string

Default value
"/changes"

baseUrl

string

Default value
"/managedZones"

id

string

metadata

object

name

string

Methods

addRecords

addRecords(record, callback) returns Promise containing ZoneAddRecordsResponse

Add records to this zone. This is a convenience wrapper around Zone#createChange.

Parameter

record

(Record or Array of Record)

The Record object(s) to add.

callback

Optional

ZoneAddRecordsCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing ZoneAddRecordsResponse 

change

change(id) returns Change

Create a reference to a Change object in this zone.

Parameter

id

string

The change id.

Returns

Change 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');
const change = zone.change('change-id');

create

create(metadata, callback) returns Promise containing CreateZoneResponse

Create a zone.

Parameter

metadata

Optional

CreateZoneRequest

Metadata to set for the zone.

callback

Optional

CreateZoneCallback

Callback function.

Returns

Promise containing CreateZoneResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const config = {
  dnsName: 'example.com.',
  // ...
};

zone.create(config, function(err, zone, apiResponse) {
  if (!err) {
    // The zone was created successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.create(config).then(function(data) {
  const zone = data[0];
  const apiResponse = data[1];
});

createChange

createChange(config, callback) returns Promise containing CreateChangeResponse

Create a change of resource record sets for the zone.

Parameter

config

CreateChangeRequest

The configuration object.

callback

Optional

CreateChangeCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing CreateChangeResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

const oldARecord = zone.record('a', {
  name: 'example.com.',
  data: '1.2.3.4',
  ttl: 86400
});

const newARecord = zone.record('a', {
  name: 'example.com.',
  data: '5.6.7.8',
  ttl: 86400
});

const config = {
  add: newARecord,
  delete: oldARecord
};

zone.createChange(config, function(err, change, apiResponse) {
  if (!err) {
    // The change was created successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.createChange(config).then(function(data) {
  const change = data[0];
  const apiResponse = data[1];
});

delete

delete(options, callback) returns Promise containing DeleteZoneResponse

Delete the zone.

Only empty zones can be deleted. Set options.force to true to call Zone#empty before deleting the zone. Two API calls will then be made (one to empty, another to delete), which means this is not an atomic request.

Parameter

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

force

Optional

boolean

Empty the zone before deleting.

callback

Optional

DeleteZoneCallback

Callback function.

See also

ManagedZones: delete API Documentation

Returns

Promise containing DeleteZoneResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.delete(function(err, apiResponse) {
  if (!err) {
    // The zone is now deleted.
  }
});

//-
// Use `force` to first empty the zone before deleting it.
//-
zone.delete({
  force: true
}, function(err, apiResponse) {
  if (!err) {
    // The zone is now deleted.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.delete().then(function(data) {
  const apiResponse = data[0];
});

deleteRecords

deleteRecords(record, callback) returns Promise containing ZoneDeleteRecordsResponse

Delete records from this zone. This is a convenience wrapper around Zone#createChange.

This method accepts Record objects or string record types in its place. This means that you can delete all A records or NS records, etc. If used this way, two API requests are made (one to get, then another to delete), which means the operation is not atomic and could result in unexpected changes.

Parameter

record

(Record, Array of Record, or string)

If given a string, it is interpreted as a record type. All records that match that type will be retrieved and then deleted. You can also provide a Record object or array of Record objects.

callback

Optional

ZoneDeleteRecordsCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing ZoneDeleteRecordsResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

const oldARecord = zone.record('a', {
  name: 'example.com.',
  data: '1.2.3.4',
  ttl: 86400
});

const callback = function(err, change, apiResponse) {
  if (!err) {
    // Delete change modification was created.
  }
};

zone.deleteRecords(oldARecord, callback);

//-
// Delete multiple records at once.
//-
const oldNs1Record = zone.record('ns', {
  name: 'example.com.',
  data: 'ns-cloud1.googledomains.com.',
  ttl: 86400
});

const oldNs2Record = zone.record('ns', {
  name: 'example.com.',
  data: 'ns-cloud2.googledomains.com.',
  ttl: 86400
});

zone.deleteRecords([
  oldNs1Record,
  oldNs2Record
], callback);

//-
// Possibly a simpler way to perform the above change is deleting records by
// type.
//-
zone.deleteRecords('ns', callback);

//-
// You can also delete records of multiple types.
//-
zone.deleteRecords(['ns', 'a'], callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.deleteRecords(oldARecord).then(function(data) {
  const change = data[0];
  const apiResponse = data[1];
});

empty

empty(callback) returns Promise containing ZoneEmptyResponse

Emptying your zone means leaving only 'NS' and 'SOA' records. This method will first fetch the non-NS and non-SOA records from your zone using Zone#getRecords, then use Zone#createChange to create a deletion change.

Parameter

callback

Optional

ZoneEmptyCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing ZoneEmptyResponse 

exists

exists(callback) returns Promise containing ZoneExistsResponse

Check if the zone exists.

Parameter

callback

Optional

ZoneExistsCallback

Callback function.

Returns

Promise containing ZoneExistsResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.exists(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.exists().then(function(data) {
  const exists = data[0];
});

export

export(localPath, callback) returns Promise containing ZoneExportResponse

Provide a path to a zone file to copy records into the zone.

Parameter

localPath

string

The fully qualified path to the zone file.

callback

Optional

ZoneExportCallback

Callback function.

See also

ResourceRecordSets: list API Documentation

Returns

Promise containing ZoneExportResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

const zoneFilename = '/Users/stephen/zonefile.zone';

zone.export(zoneFilename, function(err) {
  if (!err) {
    // The zone file was created successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.export(zoneFilename).then(function() {});

get

get(options, callback) returns Promise containing GetZoneResponse

Get a zone if it exists.

You may optionally use this to "get or create" an object by providing an object with autoCreate set to true. Any extra configuration that is normally required for the create method must be contained within this object as well.

Parameter

options

Optional

options

Configuration object.

Values in options have the following properties:

Parameter

autoCreate

Optional

boolean

Automatically create the object if it does not exist.

callback

Optional

GetZoneCallback

Callback function.

Returns

Promise containing GetZoneResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.get(function(err, zone, apiResponse) {
  // `zone.metadata` has been populated.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.get().then(function(data) {
  const zone = data[0];
  const apiResponse = data[1];
});

getChanges

getChanges(query, callback) returns Promise containing GetChangesResponse

Get the list of changes associated with this zone. A change is an atomic update to a collection of records.

Parameter

query

Optional

GetChangesRequest

Query object for listing changes.

callback

Optional

GetChangesCallback

Callback function.

See also

Changes: get API Documentation

Returns

Promise containing GetChangesResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const callback = function(err, changes, nextQuery, apiResponse) {
  // The `metadata` property is populated for you with the metadata at the
  // time of fetching.
  changes[0].metadata;

  // However, in cases where you are concerned the metadata could have
  // changed, use the `getMetadata` method.
  changes[0].getMetadata(function(err, metadata) {});
  if (nextQuery) {
    // nextQuery will be non-null if there are more results.
    zone.getChanges(nextQuery, callback);
  }
};

const zone = dns.zone('zone-id');

zone.getChanges(callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.getChanges().then(function(data) {
  const changes = data[0];
});

getChangesStream

getChangesStream(query) returns ReadableStream

Get the list of Change objects associated with this zone as a readable object stream.

Parameter

query

Optional

GetChangesRequest

Query object for listing changes.

Returns

ReadableStream 

A readable stream that emits Change instances.

Example

zone.getChangesStream()
  .on('error', console.error)
  .on('data', function(change) {
    // change is a Change object.
  })
  .on('end', function() {
    // All changes retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
zone.getChangesStream()
  .on('data', function(change) {
    this.end();
  });

getMetadata

getMetadata(callback) returns Promise containing GetZoneMetadataResponse

Get the metadata for the zone.

Parameter

callback

Optional

GetZoneMetadataCallback

Callback function.

See also

ManagedZones: get API Documentation

Returns

Promise containing GetZoneMetadataResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.getMetadata(function(err, metadata, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.getMetadata().then(function(data) {
  const metadata = data[0];
  const apiResponse = data[1];
});

getRecords

getRecords(query, callback) returns Promise containing GetRecordsResponse

Get the list of records for this zone.

Parameter

query

Optional

GetRecordsRequest

Query object for listing records.

callback

Optional

GetRecordsCallback

Callback function.

See also

ResourceRecordSets: list API Documentation

Returns

Promise containing GetRecordsResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const callback = function(err, records, nextQuery, apiResponse) {
  if (!err) {
    // records is an array of Record objects.
  }

  if (nextQuery) {
    zone.getRecords(nextQuery, callback);
  }
};

const zone = dns.zone('zone-id');

zone.getRecords(callback);

//-
// Provide a query for further customization.
//-

// Get the namespace records for example.com.
const query = {
  name: 'example.com.',
  type: 'NS'
};

zone.getRecords(query, callback);

//-
// If you only want records of a specific type or types, provide them in
// place of the query object.
//-
zone.getRecords('ns', function(err, records) {
  if (!err) {
    // records is an array of NS Record objects in your zone.
  }
});

//-
// You can also specify multiple record types.
//-
zone.getRecords(['ns', 'a', 'cname'], function(err, records) {
  if (!err) {
    // records is an array of NS, A, and CNAME records in your zone.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.getRecords(query).then(function(data) {
  const records = data[0];
});

getRecordsStream

getRecordsStream(query) returns ReadableStream

Get the list of {module:dns/record} objects for this zone as a readable object stream.

Parameter

query

Optional

GetRecordsRequest

Query object for listing records.

Returns

ReadableStream 

A readable stream that emits Record instances.

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.getRecordsStream()
  .on('error', console.error)
  .on('data', function(record) {
    // record is a Record object.
  })
  .on('end', function() {
    // All records retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
zone.getRecordsStream()
  .on('data', function(change) {
    this.end();
  });

import

import(localPath, callback) returns Promise containing ZoneImportResponse

Copy the records from a zone file into this zone.

Parameter

localPath

string

The fully qualified path to the zone file.

callback

Optional

ZoneImportCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing ZoneImportResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

const zoneFilename = '/Users/dave/zonefile.zone';

zone.import(zoneFilename, function(err, change, apiResponse) {
  if (!err) {
    // The change was created successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.import(zoneFilename).then(function(data) {
  const change = data[0];
  const apiResponse = data[1];
});

record

record(type, metadata) returns Record

A Record object can be used to construct a record you want to add to your zone, or to refer to an existing one.

Note that using this method will not itself make any API requests. You will use the object returned in other API calls, for example to add a record to your zone or to delete an existing one.

Parameter

type

string

The type of record to construct or the type of record you are referencing.

metadata

object

The metadata of this record.

Values in metadata have the following properties:

Parameter

name

string

The name of the record, e.g. www.example.com..

data

Array of string

Defined in RFC 1035, section 5 and RFC 1034, section 3.6.1.

ttl

number

Seconds that the resource is cached by resolvers.

Returns

Record 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const zone = dns.zone('zone-id');

//-
// Reference an existing record to delete from your zone.
//-
const oldARecord = zone.record('a', {
  name: 'example.com.',
  data: '1.2.3.4',
  ttl: 86400
});

//-
// Construct a record to add to your zone.
//-
const newARecord = zone.record('a', {
  name: 'example.com.',
  data: '5.6.7.8',
  ttl: 86400
});

//-
// Use these records together to create a change.
//-
zone.createChange({
  add: newARecord,
  delete: oldARecord
}, function(err, change, apiResponse) {});

replaceRecords

replaceRecords(recordTypes, newRecords, callback) returns Promise containing ZoneReplaceRecordsResponse

Provide a record type that should be deleted and replaced with other records.

This is not an atomic request. Two API requests are made (one to get records of the type that you've requested, then another to replace them), which means the operation is not atomic and could result in unexpected changes.

Parameter

recordTypes

(string or Array of string)

The type(s) of records to replace.

newRecords

(Record or Array of Record)

The Record object(s) to add.

callback

Optional

ZoneReplaceRecordsCallback

Callback function.

See also

ManagedZones: create API Documentation

Returns

Promise containing ZoneReplaceRecordsResponse 

Example

const DNS = require('@google-cloud/dns');
const dns = new DNS();

const zone = dns.zone('zone-id');

const newNs1Record = zone.record('ns', {
  name: 'example.com.',
  data: 'ns-cloud1.googledomains.com.',
  ttl: 86400
});

const newNs2Record = zone.record('ns', {
  name: 'example.com.',
  data: 'ns-cloud2.googledomains.com.',
  ttl: 86400
});

const newNsRecords = [
  newNs1Record,
  newNs2Record
];

zone.replaceRecords('ns', newNsRecords, function(err, change, apiResponse) {
  if (!err) {
    // The change was created successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
zone.replaceRecords('ns', newNsRecords).then(function(data) {
  const change = data[0];
  const apiResponse = data[1];
});