Zone

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.

Constructor

new Zone()

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

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

Members

baseUrl

Default Value:
  • "/changes"

baseUrl

Default Value:
  • "/managedZones"

id

metadata

name

Methods

addRecords(record, callbackopt) → {Promise.<CreateChangeResponse>}

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

Parameters:
Name Type Attributes Description
record Record | Array.<Record>

The Record object(s) to add.
callback CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:

change(id) → {Change}

Create a reference to a Change object in this zone.

Parameters:
Name Type Description
id string

The change id.
Returns:
Type Description
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(metadata, callbackopt) → {Promise.<CreateZoneResponse>}

Create a zone.

Parameters:
Name Type Attributes Description
metadata CreateZoneRequest

Metadata to set for the zone.
callback CreateZoneCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateZoneResponse>
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

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

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

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

createChange(config, callbackopt) → {Promise.<CreateChangeResponse>}

Create a change of resource record sets for the zone.

Parameters:
Name Type Attributes Description
config CreateChangeRequest

The configuration object.
callback CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:
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, (err, change, apiResponse) => {
  if (!err) {
    // The change was created successfully.
  }
});

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

delete(optionsopt, callbackopt) → {Promise.<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.

Parameters:
Name Type Attributes Description
options object <optional>

Configuration object.

Properties
Name Type Attributes Default Description
force boolean <optional>
 false

Empty the zone before deleting.
callback DeleteZoneCallback <optional>

Callback function.
Returns:
Type Description
Promise.<DeleteZoneResponse>
See:
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

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

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

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

deleteRecords(record, callbackopt) → {Promise.<CreateChangeResponse>}

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.

Parameters:
Name Type Attributes Description
record Record | Array.<Record> | 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 CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:
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 = (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((data) => {
  const change = data[0];
  const apiResponse = data[1];
});

empty(callbackopt) → {Promise.<CreateChangeResponse>}

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.

Parameters:
Name Type Attributes Description
callback CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:

exists(callbackopt) → {Promise.<ZoneExistsResponse>}

Check if the zone exists.

Parameters:
Name Type Attributes Description
callback ZoneExistsCallback <optional>

Callback function.
Returns:
Type Description
Promise.<ZoneExistsResponse>
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

zone.exists((err, exists) => {});

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

export(localPath, callbackopt) → {Promise.<ZoneExportResponse>}

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

Parameters:
Name Type Attributes Description
localPath string

The fully qualified path to the zone file.
callback ZoneExportCallback <optional>

Callback function.
Returns:
Type Description
Promise.<ZoneExportResponse>
See:
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, err => {
  if (!err) {
    // The zone file was created successfully.
  }
});

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

get(optionsopt, callbackopt) → {Promise.<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.

Parameters:
Name Type Attributes Description
options options <optional>

Configuration object.

Properties
Name Type Attributes Default Description
autoCreate boolean <optional>
 false

Automatically create the object if it does not exist.
callback GetZoneCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetZoneResponse>
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

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

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

getChanges(queryopt, callbackopt) → {Promise.<GetChangesResponse>}

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

Parameters:
Name Type Attributes Description
query GetChangesRequest <optional>

Query object for listing changes.
callback GetChangesCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetChangesResponse>
See:
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();

const callback = (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((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((data) => {
  const changes = data[0];
});

getChangesStream(queryopt) → {ReadableStream}

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

Parameters:
Name Type Attributes Description
query GetChangesRequest <optional>

Query object for listing changes.
Returns:
Type Description
ReadableStream

A readable stream that emits Change instances.
Example
zone.getChangesStream()
  .on('error', console.error)
  .on('data', change => {
    // change is a Change object.
  })
  .on('end', () => {
    // 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(callbackopt) → {Promise.<GetZoneMetadataResponse>}

Get the metadata for the zone.

Parameters:
Name Type Attributes Description
callback GetZoneMetadataCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetZoneMetadataResponse>
See:
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();
const zone = dns.zone('zone-id');

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

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

getRecords(queryopt, callbackopt) → {Promise.<GetRecordsResponse>}

Get the list of records for this zone.

Parameters:
Name Type Attributes Description
query GetRecordsRequest <optional>

Query object for listing records.
callback GetRecordsCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetRecordsResponse>
See:
Example
const {DNS} = require('@google-cloud/dns');
const dns = new DNS();

const callback = (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', (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'], (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(data => {
  const records = data[0];
});

getRecordsStream(queryopt) → {ReadableStream}

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

Parameters:
Name Type Attributes Description
query GetRecordsRequest <optional>

Query object for listing records.
Returns:
Type Description
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', record => {
    // record is a Record object.
  })
  .on('end', () => {
    // 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(localPath, callbackopt) → {Promise.<CreateChangeResponse>}

Copy the records from a zone file into this zone.

Parameters:
Name Type Attributes Description
localPath string

The fully qualified path to the zone file.
callback CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:
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, (err, change, apiResponse) => {
  if (!err) {
    // The change was created successfully.
  }
});

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

record(type, metadata) → {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.

Parameters:
Name Type Description
type string

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

The metadata of this record.

Properties
Name Type Description
name string

The name of the record, e.g. www.example.com..
data Array.<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:
Type Description
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
}, (err, change, apiResponse) => {});

replaceRecords(recordTypes, newRecords, callbackopt) → {Promise.<CreateChangeResponse>}

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.

Parameters:
Name Type Attributes Description
recordTypes string | Array.<string>

The type(s) of records to replace.
newRecords Record | Array.<Record>

The Record object(s) to add.
callback CreateChangeCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateChangeResponse>
See:
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, (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(data => {
  const change = data[0];
  const apiResponse = data[1];
});