Using the API

Authorization / Configuration

- Use :class:`Client <gcloud.dns.client.Client>` objects to configure

your applications.

- :class:`Client <gcloud.dns.client.Client>` objects hold both a ``project``

and an authenticated connection to the PubSub service.

- The authentication credentials can be implicitly determined from the

environment or directly via

:meth:`from_service_account_json <gcloud.dns.client.Client.from_service_account_json>`

and

:meth:`from_service_account_p12 <gcloud.dns.client.Client.from_service_account_p12>`.

- After setting ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``

environment variables, create an instance of

:class:`Client <gcloud.dns.client.Client>`.

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client()

- Override the credentials inferred from the environment by passing explicit

``credentials`` to one of the alternative ``classmethod`` factories,

`:meth:gcloud.dns.client.Client.from_service_account_json`:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client.from_service_account_json('/path/to/creds.json')

or `:meth:gcloud.dns.client.Client.from_service_account_p12`:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client.from_service_account_p12('/path/to/creds.p12', 'jrandom@example.com')

Projects

A project is the top-level container in the ``DNS`` API: it is tied

closely to billing, and can provide default access control across all its

datasets. If no ``project`` is passed to the client container, the library

attempts to infer a project using the environment (including explicit

environment variables, GAE, and GCE).

To override the project inferred from the environment, pass an explicit

``project`` to the constructor, or to either of the alternative

``classmethod`` factories:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

Project Quotas

Query the quotas for a given project:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> quotas = client.quotas() # API request

>>> for key, value in sorted(quotas.items()):

... print('%s: %s' % (key, value))

managedZones: 10000

resourceRecordsPerRrset: 100

rrsetsPerManagedZone: 10000

rrsetAdditionsPerChange: 100

rrsetDeletionsPerChange: 100

totalRrdataSizePerChange: 10000

.. note::

See https://github.com/GoogleCloudPlatform/gcloud-python/issues/1136

for whether to expose quotas.

Project ACLs

Each project has an access control list granting reader / writer / owner

permission to one or more entities. This list cannot be queried or set

via the API: it must be managed using the Google Developer Console.

Managed Zones

A "managed zone" is the container for DNS records for the same DNS name

suffix and has a set of name servers that accept and responds to queries:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> zone = client.zone('acme-co', description='Acme Company zone',

... dns_name='example.com')

>>> zone.exists() # API request

False

>>> zone.create() # API request

>>> zone.exists() # API request

True

List the zones for a given project:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> zones = client.list_zones() # API request

>>> [zone.name for zone in zones]

['acme-co'>]

Resource Record Sets

Each managed zone exposes a read-only set of resource records:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> zone = client.zone('acme-co')

>>> records, page_token = zone.list_resources() # API request

>>> [(record.name, record.type, record.ttl, record.rrdatas) for record in records]

[('example.com.', 'SOA', 21600, ['ns-cloud1.googlecomains.com dns-admin.google.com 1 21600 3600 1209600 300')]

.. note::

The ``page_token`` returned from ``zone.list_resources()`` will be

an opaque string if there are more resources than can be returned in a

single request. To enumerate them all, repeat calling

``zone.list_resources()``, passing the ``page_token``, until the token

is None.

Change requests

Update the resource record set for a zone by creating a change request

bundling additions to or deletions from the set.

.. doctest::

>>> import time

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> zone = client.zone('acme-co')

>>> record = dns.ResourceRecord(name='www.example.com', type='CNAME')

>>> change = zone.change_request(additions=[record])

>>> change.begin() # API request

>>> while change.status != 'done':

... print('Waiting for change to complete')

... time.sleep(60)

... change.reload() # API request

List changes made to the resource record set for a given zone:

.. doctest::

>>> from gcloud import dns

>>> client = dns.Client(project='PROJECT_ID')

>>> zone = client.zone('acme-co')

>>> changes = []

>>> changes, page_token = zone.list_changes() # API request

.. note::

The ``page_token`` returned from ``zone.list_changes()`` will be

an opaque string if there are more hcanges than can be returned in a

single request. To enumerate them all, repeat calling

``zone.list_hcanges()``, passing the ``page_token``, until the token

is None.