Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: remove samples in library docs #17

Merged
merged 1 commit into from Jun 26, 2020
Merged

docs: remove samples in library docs #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
179 changes: 0 additions & 179 deletions docs/index.rst
View file
Open in desktop
@@ -1,184 +1,5 @@
.. include:: README.rst

Using the Library
-----------------

Client
~~~~~~

:class:`Client <google.cloud.dns.client.Client>` objects provide a means to
configure your DNS applications. Each instance holds both a ``project``
and an authenticated connection to the DNS service.

For an overview of authentication in ``google-cloud-python``, see `Authentication <https://googleapis.dev/python/google-api-core/latest/auth.html#authentication>`_..

Assuming your environment is set up as described in that document,
create an instance of :class:`Client <google.cloud.dns.client.Client>`.

.. code-block:: python

>>> from google.cloud import dns
>>> client = dns.Client()

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, or GCE).

To override the project inferred from the environment, pass an explicit
``project`` to the constructor, or to either of the alternative
``classmethod`` factories:

.. code-block:: python

>>> from google.cloud import dns
>>> client = dns.Client(project='PROJECT_ID')

Project Quotas
~~~~~~~~~~~~~~

Query the quotas for a given project:

.. code-block:: python

>>> from google.cloud 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


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:

.. code-block:: python

>>> from google.cloud import dns
>>> client = dns.Client(project='PROJECT_ID')
>>> zone = client.zone('acme-co',
... "example.com.", # DNS names require a trailing dot
... description='Acme Company zone')

>>> zone.exists() # API request
False
>>> zone.create() # API request
>>> zone.exists() # API request
True

List the zones for a given project:

.. code-block:: python

>>> from google.cloud 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:

.. code-block:: python

>>> from google.cloud import dns
>>> client = dns.Client(project='PROJECT_ID')
>>> zone = client.zone('acme-co', 'example.com.')
>>> records, page_token = zone.list_resource_record_sets() # API request
>>> [(record.name, record.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_resource_record_sets()`` 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_resource_record_sets()``, passing the ``page_token``, until
the token is ``None``. E.g.

.. code-block:: python

>>> records, page_token = zone.list_resource_record_sets() # API request
>>> while page_token is not None:
... next_batch, page_token = zone.list_resource_record_sets(
... page_token=page_token) # API request
... records.extend(next_batch)


Change requests
~~~~~~~~~~~~~~~

Update the resource record set for a zone by creating a change request
bundling additions to or deletions from the set.

.. code-block:: python

>>> import time
>>> from google.cloud import dns
>>> client = dns.Client(project='PROJECT_ID')
>>> zone = client.zone('acme-co', 'example.com.')
>>> TWO_HOURS = 2 * 60 * 60 # seconds
>>> record_set = zone.resource_record_set(
... 'www.example.com.', 'CNAME', TWO_HOURS, ['www1.example.com.',])
>>> changes = zone.changes()
>>> changes.add_record_set(record_set)
>>> changes.create() # API request
>>> while changes.status != 'done':
... print('Waiting for changes to complete')
... time.sleep(60) # or whatever interval is appropriate
... changes.reload() # API request


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

.. code-block:: python

>>> from google.cloud import dns
>>> client = dns.Client(project='PROJECT_ID')
>>> zone = client.zone('acme-co', 'example.com.')
>>> 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 changes than can be returned in a
single request. To enumerate them all, repeat calling
``zone.list_changes()``, passing the ``page_token``, until the token
is ``None``. E.g.:

.. code-block:: python

>>> changes, page_token = zone.list_changes() # API request
>>> while page_token is not None:
... next_batch, page_token = zone.list_changes(
... page_token=page_token) # API request
... changes.extend(next_batch)


API Reference
-------------
Expand Down