gcloud 0.3.1 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MzczYWVlN2JlNmY4YzI0MTBiNGM4ZjY5YjZlMjkzMDVmZjQ3MGQwNg==
+    Nzc3MzUzZjk2YTg0MTg0NDc5ZTUyOGQwZTUxNmQ4YmRhNmRjY2QwMQ==
   data.tar.gz: !binary |-
-    YmNkZGUyNzljMjY1YjlhMWQyZjliMGNhZGY2OTdhYjJiOTBiZTNhNw==
+    YmQ0N2Q3ZWFlZmY2ZGJlZmE5ZWQzYzc2MWM0NzM5ZTEzNTVkNzRhMA==
 SHA512:
   metadata.gz: !binary |-
-    MzE5YjkzYmJmNmNmODY4NThhMjdlOTM2YmUxOTZmYWE4MDZjYjBhZDVmN2U1
-    NDMxMjY4NjlkZmZiNGJkNmYyNzczM2RhZWY3YmI4ODY5MmU0N2FiNjI5ZDNi
-    NzBhZGJmNDc4NDU2MWNkMmNkMTA5MzE3MjU0N2Y2N2ZiY2YzYmE=
+    ZWRjNGM0MzNmZmM4NjQ5YmE0OTY3ZTUxNzRlZjIxYzIyZmJhZTcyZDhmMGFk
+    N2Q2OWI2YzcyMGM1NDM5YjRiMzM0N2ZlZTNkY2VkNTI1N2Y3YjUzMDUzNGMw
+    NWI1YTMzNzA5NGVkZTU4ZjAwNGNmZjNhNjRkM2NjOTZmNDk2OWQ=
   data.tar.gz: !binary |-
-    OGU0MTQzYzRiOGU0NzJlZDllOGFmZWMzYTcwZDc3NTgwMTMxZTIxMjAxOTc4
-    MDQ0M2I2YWQyZGIyZmYyMzQ0MThmMTQ2ZjQ2NzJlNTAzMDI1Y2I2MWY3Y2U2
-    NjdjMjJjZGNlN2EyZmFmNDg3MTcwY2JiZmVkYzExYzZiNTZmZTY=
+    YzJkY2FiNDEzZWRlOGViMGU1ZmZiZmM2NGM2YWMyZmRiN2NiNjUyY2JkNGRi
+    YzAwMTM3NzdmNjNjNzY4MGY3ZmU3MDVmN2MxNzhlODk3YjY1MmRiODliZmRi
+    NjQxMzBmZmEyNWVjZDUwYjc2MmU5NjFmZmYzMTdiZWRkNjY4MWQ=

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 0.4.0 / 2015-10-12
+
+#### Major changes
+
+* Add DNS Service
+
+#### Minor changes
+
+* Improved BigQuery table recognition from a string (vitaliel)
+* Add missing options from BigQuery `Table#load` (gramos74)
+* Add missing options from BigQuery `Table#extract`
+
 ### 0.3.1 / 2015-09-08
 
 #### Changes

data/OVERVIEW.md

@@ -67,6 +67,34 @@ query = Gcloud::Datastore::Query.new.kind("Task").
 completed_tasks = dataset.run query
 ```
 
+# DNS
+
+[Google Cloud DNS](https://cloud.google.com/dns/) ([docs](https://cloud.google.com/dns/docs)) is a high-performance, resilient, global DNS service that provides a cost-effective way to make your applications and services available to your users. This programmable, authoritative DNS service can be used to easily publish and manage DNS records using the same infrastructure relied upon by Google. To learn more, read [What is Google Cloud DNS?](https://cloud.google.com/dns/what-is-cloud-dns).
+
+See the [gcloud-ruby DNS API documentation](rdoc-ref:Gcloud::Dns) to learn how to connect to Cloud DNS using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+dns = gcloud.dns
+
+# Retrieve a zone
+zone = dns.zone "example-com"
+
+# Update records in the zone
+change = zone.update do |tx|
+  tx.add     "www", "A",  86400, "1.2.3.4"
+  tx.remove  "example.com.", "TXT"
+  tx.replace "example.com.", "MX", 86400, ["10 mail1.example.com.",
+                                           "20 mail2.example.com."]
+  tx.modify "www.example.com.", "CNAME" do |r|
+    r.ttl = 86400 # only change the TTL
+  end
+end
+
+```
+
 # Pub/Sub
 
 [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) ([docs](https://cloud.google.com/pubsub/reference/rest/)) is designed to provide reliable, many-to-many, asynchronous messaging between applications. Publisher applications can send messages to a “topic” and other applications can subscribe to that topic to receive the messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows developers to communicate between independently written applications.

data/lib/gcloud.rb

@@ -253,4 +253,50 @@ module Gcloud
     require "gcloud/bigquery"
     Gcloud.bigquery @project, @keyfile, options
   end
+
+  ##
+  # Creates a new object for connecting to the DNS service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +options+::
+  #   An optional Hash for controlling additional behavior. (+Hash+)
+  # <code>options[:scope]</code>::
+  #   The OAuth 2.0 scopes controlling the set of resources and operations that
+  #   the connection can access. See {Using OAuth 2.0 to Access Google
+  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
+  #   or +Array+)
+  #
+  #   The default scope is:
+  #
+  #   * +https://www.googleapis.com/auth/ndev.clouddns.readwrite+
+  #
+  # === Returns
+  #
+  # Gcloud::Dns::Project
+  #
+  # === Examples
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-zone"
+  #   zone.records.each do |record|
+  #     puts record.name
+  #   end
+  #
+  # The default scope can be overridden with the +scope+ option:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   readonly_scope = "https://www.googleapis.com/auth/ndev.clouddns.readonly"
+  #   dns = gcloud.dns scope: readonly_scope
+  #
+  def dns options = {}
+    require "gcloud/dns"
+    Gcloud.dns @project, @keyfile, options
+  end
 end

data/lib/gcloud/bigquery.rb

@@ -303,19 +303,28 @@ module Gcloud
   #
   # === A note about large uploads
   #
-  # You may encounter a broken pipe error while attempting to upload large
-  # files. To avoid this problem, add
-  # {httpclient}[https://rubygems.org/gems/httpclient] as a dependency to your
-  # project, and configure {Faraday}[https://rubygems.org/gems/faraday] to use
-  # it, after requiring Gcloud, but before initiating your Gcloud connection.
+  # You may encounter a Broken pipe (Errno::EPIPE) error when attempting to
+  # upload large files. To avoid this problem, add the
+  # {httpclient}[https://rubygems.org/gems/httpclient] gem to your project, and
+  # the line (or lines) of configuration shown below. These lines must execute
+  # after you require gcloud but before you make your first gcloud connection.
+  # The first statement configures {Faraday}[https://rubygems.org/gems/faraday]
+  # to use httpclient. The second statement, which should only be added if you
+  # are using a version of Faraday at or above 0.9.2, is a workaround for {this
+  # gzip issue}[https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/367].
   #
   #   require "gcloud"
   #
+  #   # Use httpclient to avoid broken pipe errors with large uploads
   #   Faraday.default_adapter = :httpclient
   #
+  #   # Only add the following statement if using Faraday >= 0.9.2
+  #   # Override gzip middleware with no-op for httpclient
+  #   Faraday::Response.register_middleware :gzip =>
+  #                                           Faraday::Response::Middleware
+  #
   #   gcloud = Gcloud.new
   #   bigquery = gcloud.bigquery
-  #   dataset = bigquery.dataset "my_dataset"
   #
   # == Exporting query results to Google Cloud Storage
   #

data/lib/gcloud/bigquery/connection.rb

@@ -332,9 +332,10 @@ module Gcloud
         unless m
           fail ArgumentError, "unable to identify table from #{str.inspect}"
         end
-        default_table_ref.merge("projectId" => m["prj"],
-                                "datasetId" => m["dts"],
-                                "tableId" => m["tbl"])
+        str_table_ref = { "projectId" => m["prj"],
+                          "datasetId" => m["dts"],
+                          "tableId"   => m["tbl"] }.delete_if { |_, v| v.nil? }
+        default_table_ref.merge str_table_ref
       end
 
       def inspect #:nodoc:
@@ -526,9 +527,12 @@ module Gcloud
         {
           "configuration" => {
             "extract" => {
-              "destinationUris" => Array(storage_urls),
-              "sourceTable" => table,
-              "destinationFormat" => dest_format
+              "destinationUris"   => Array(storage_urls),
+              "sourceTable"       => table,
+              "destinationFormat" => dest_format,
+              "compression"       => options[:compression],
+              "fieldDelimiter"    => options[:delimiter],
+              "printHeader"       => options[:header]
             }.delete_if { |_, v| v.nil? },
             "dryRun" => options[:dryrun]
           }.delete_if { |_, v| v.nil? }
@@ -541,12 +545,21 @@ module Gcloud
         {
           "configuration" => {
             "load" => {
-              "sourceUris" => Array(urls),
-              "destinationTable" => table,
-              "createDisposition" => create_disposition(options[:create]),
-              "writeDisposition" => write_disposition(options[:write]),
-              "sourceFormat" => source_format(path, options[:format]),
-              "projectionFields" => projection_fields(options[:projection_fields])
+              "sourceUris"          => Array(urls),
+              "destinationTable"    => table,
+              "createDisposition"   => create_disposition(options[:create]),
+              "writeDisposition"    => write_disposition(options[:write]),
+              "sourceFormat"        => source_format(path, options[:format]),
+              "projectionFields"    => projection_fields(options[:projection_fields]),
+              "allowJaggedRows"     => options[:jagged_rows],
+              "allowQuotedNewlines" => options[:quoted_newlines],
+              "encoding"            => options[:encoding],
+              "fieldDelimiter"      => options[:delimiter],
+              "ignoreUnknownValues" => options[:ignore_unknown],
+              "maxBadRecords"       => options[:max_bad_records],
+              "quote"               => options[:quote],
+              "schema"              => options[:schema],
+              "skipLeadingRows"     => options[:skip_leading]
             }.delete_if { |_, v| v.nil? },
             "dryRun" => options[:dryrun]
           }.delete_if { |_, v| v.nil? }

data/lib/gcloud/bigquery/table.rb

@@ -583,6 +583,15 @@ module Gcloud
       #   * +csv+ - CSV
       #   * +json+ - {Newline-delimited JSON}[http://jsonlines.org/]
       #   * +avro+ - {Avro}[http://avro.apache.org/]
+      # <code>options[:compression]</code>::
+      #   The compression type to use for exported files. Possible values
+      #   include +GZIP+ and +NONE+. The default value is +NONE+. (+String+)
+      # <code>options[:delimiter]</code>::
+      #   Delimiter to use between fields in the exported data. Default is
+      #   <code>,</code>. (+String+)
+      # <code>options[:header]</code>::
+      #   Whether to print out a header row in the results. Default is +true+.
+      #   (+Boolean+)
       #
       # === Returns
       #
@@ -653,6 +662,55 @@ module Gcloud
       #   names are case sensitive and must be top-level properties. If not set,
       #   BigQuery loads all properties. If any named property isn't found in
       #   the Cloud Datastore backup, an invalid error is returned. (+Array+)
+      # <code>options[:jagged_rows]</code>::
+      #   Accept rows that are missing trailing optional columns. The missing
+      #   values are treated as nulls. If +false+, records with missing trailing
+      #   columns are treated as bad records, and if there are too many bad
+      #   records, an invalid error is returned in the job result. The default
+      #   value is +false+. Only applicable to CSV, ignored for other formats.
+      #   (+Boolean+)
+      # <code>options[:quoted_newlines]</code>::
+      #   Indicates if BigQuery should allow quoted data sections that contain
+      #   newline characters in a CSV file. The default value is +false+.
+      #   (+Boolean+)
+      # <code>options[:encoding]</code>::
+      #   The character encoding of the data. The supported values are +UTF-8+
+      #   or +ISO-8859-1+. The default value is +UTF-8+. (+String+)
+      # <code>options[:delimiter]</code>::
+      #   Specifices the separator for fields in a CSV file. BigQuery converts
+      #   the string to +ISO-8859-1+ encoding, and then uses the first byte of
+      #   the encoded string to split the data in its raw, binary state. Default
+      #   is <code>,</code>. (+String+)
+      # <code>options[:ignore_unknown]</code>::
+      #   Indicates if BigQuery should allow extra values that are not
+      #   represented in the table schema. If true, the extra values are
+      #   ignored. If false, records with extra columns are treated as bad
+      #   records, and if there are too many bad records, an invalid error is
+      #   returned in the job result. The default value is +false+. (+Boolean+)
+      #
+      #   The +format+ property determines what BigQuery treats as an extra
+      #   value:
+      #
+      #   * +CSV+: Trailing columns
+      #   * +JSON+: Named values that don't match any column names
+      # <code>options[:max_bad_records]</code>::
+      #   The maximum number of bad records that BigQuery can ignore when
+      #   running the job. If the number of bad records exceeds this value, an
+      #   invalid error is returned in the job result. The default value is +0+,
+      #   which requires that all records are valid. (+Integer+)
+      # <code>options[:quote]</code>::
+      #   The value that is used to quote data sections in a CSV file. BigQuery
+      #   converts the string to ISO-8859-1 encoding, and then uses the first
+      #   byte of the encoded string to split the data in its raw, binary state.
+      #   The default value is a double-quote <code>"</code>. If your data does
+      #   not contain quoted sections, set the property value to an empty
+      #   string. If your data contains quoted newline characters, you must also
+      #   set the allowQuotedNewlines property to true. (+String+)
+      # <code>options[:skip_leading]</code>::
+      #   The number of rows at the top of a CSV file that BigQuery will skip
+      #   when loading the data. The default value is +0+. This property is
+      #   useful if you have header rows in the file that should be skipped.
+      #   (+Integer+)
       #
       # === Returns
       #
@@ -700,20 +758,29 @@ module Gcloud
       #
       # === A note about large direct uploads
       #
-      # You may encounter a broken pipe error while attempting to upload large
-      # files. To avoid this problem, add
-      # {httpclient}[https://rubygems.org/gems/httpclient] as a dependency to
-      # your project, and configure {Faraday}[https://rubygems.org/gems/faraday]
-      # to use it, after requiring Gcloud, but before initiating your Gcloud
-      # connection.
+      # You may encounter a Broken pipe (Errno::EPIPE) error when attempting to
+      # upload large files. To avoid this problem, add the
+      # {httpclient}[https://rubygems.org/gems/httpclient] gem to your project,
+      # and the line (or lines) of configuration shown below. These lines must
+      # execute after you require gcloud but before you make your first gcloud
+      # connection. The first statement configures
+      # {Faraday}[https://rubygems.org/gems/faraday] to use httpclient. The
+      # second statement, which should only be added if you are using a version
+      # of Faraday at or above 0.9.2, is a workaround for {this gzip
+      # issue}[https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/367].
       #
       #   require "gcloud"
       #
+      #   # Use httpclient to avoid broken pipe errors with large uploads
       #   Faraday.default_adapter = :httpclient
       #
+      #   # Only add the following statement if using Faraday >= 0.9.2
+      #   # Override gzip middleware with no-op for httpclient
+      #   Faraday::Response.register_middleware :gzip =>
+      #                                           Faraday::Response::Middleware
+      #
       #   gcloud = Gcloud.new
       #   bigquery = gcloud.bigquery
-      #   dataset = bigquery.dataset "my_dataset"
       #
       # :category: Data
       #

data/lib/gcloud/dns.rb

@@ -0,0 +1,280 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gcloud"
+require "gcloud/dns/project"
+
+#--
+# Google Cloud DNS
+module Gcloud
+  ##
+  # Creates a new +Project+ instance connected to the DNS service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Identifier for a DNS project. If not present, the default project for
+  #   the credentials is used. (+String+)
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  # +options+::
+  #   An optional Hash for controlling additional behavior. (+Hash+)
+  # <code>options[:scope]</code>::
+  #   The OAuth 2.0 scopes controlling the set of resources and operations that
+  #   the connection can access. See {Using OAuth 2.0 to Access Google
+  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
+  #   or +Array+)
+  #
+  #   The default scope is:
+  #
+  #   * +https://www.googleapis.com/auth/ndev.clouddns.readwrite+
+  #
+  # === Returns
+  #
+  # Gcloud::Dns::Project
+  #
+  # === Example
+  #
+  #   require "gcloud"
+  #
+  #   dns = Gcloud.dns "my-dns-project",
+  #                    "/path/to/keyfile.json"
+  #
+  #   zone = dns.zone "example-com"
+  #
+  def self.dns project = nil, keyfile = nil, options = {}
+    project ||= Gcloud::Dns::Project.default_project
+    if keyfile.nil?
+      credentials = Gcloud::Dns::Credentials.default options
+    else
+      credentials = Gcloud::Dns::Credentials.new keyfile, options
+    end
+    Gcloud::Dns::Project.new project, credentials
+  end
+
+  ##
+  # = Google Cloud DNS
+  #
+  # Google Cloud DNS is a high-performance, resilient, global DNS service that
+  # provides a cost-effective way to make your applications and services
+  # available to your users. This programmable, authoritative DNS service can be
+  # used to easily publish and manage DNS records using the same infrastructure
+  # relied upon by Google. To learn more, read {What is Google Cloud
+  # DNS?}[https://cloud.google.com/dns/what-is-cloud-dns].
+  #
+  # Gcloud's goal is to provide an API that is familiar and comfortable to
+  # Rubyists. Authentication is handled by Gcloud#dns. You can provide
+  # the project and credential information to connect to the Cloud DNS service,
+  # or if you are running on Google Compute Engine this configuration is taken
+  # care of for you. You can read more about the options for connecting in the
+  # {Authentication Guide}[link:AUTHENTICATION.md].
+  #
+  # == Creating Zones
+  #
+  # To get started with Google Cloud DNS, use your DNS Project to create a new
+  # Zone. The second argument to Project#create_zone must be a unique
+  # domain name for which you can {verify
+  # ownership}[https://www.google.com/webmasters/verification/home]. Substitute
+  # a domain name of your own (ending with a dot to signify that it is {fully
+  # qualified}[https://en.wikipedia.org/wiki/Fully_qualified_domain_name]) as
+  # you follow along with these examples.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.create_zone "example-com", "example.com."
+  #   puts zone.id # unique identifier defined by the server
+  #
+  # For more information, see {Managing
+  # Zones}[https://cloud.google.com/dns/zones/].
+  #
+  # == Listing Zones
+  #
+  # You can retrieve all the zones in your project.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zones = dns.zones
+  #   zones.each do |zone|
+  #     puts "#{zone.name} - #{zone.dns}"
+  #   end
+  #
+  # You can also retrieve a single zone by either name or id.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #
+  # == Listing Records
+  #
+  # When you create a zone, the Cloud DNS service automatically creates two
+  # Record instances for it, providing configuration for Cloud DNS nameservers.
+  # Let's take a look at these records.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   records = zone.records
+  #   records.count #=> 2
+  #   records.map &:type #=> ["NS", "SOA"]
+  #   zone.records.first.data.count #=> 4
+  #   zone.records.first.data #=> ["ns-cloud-d1.googledomains.com.", ...]
+  #
+  # Note that Record#data returns an array. The Cloud DNS service only allows
+  # the zone to have one Record instance for each name and type combination. It
+  # supports multiple "resource records" (in this case, the four nameserver
+  # addresses) via this +data+ collection.
+  #
+  # == Managing Records
+  #
+  # You can easily add your own records to the zone. Each call to Zone#add
+  # results in a new Cloud DNS Change instance.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.add "www", "A", 86400, ["1.2.3.4"]
+  #   change.additions.map &:type #=> ["A", "SOA"]
+  #   change.deletions.map &:type #=> ["SOA"]
+  #
+  # Whenever you change the set of records belonging to a zone, the zone's start
+  # of authority (SOA) record should be updated with a higher serial number. The
+  # gcloud library automates this update for you, deleting the old SOA record
+  # and adding an updated one, as shown in the example above. You can disable or
+  # modify this behavior, of course. See Zone#update for details.
+  #
+  # You can retrieve records by name and type. The name argument can be a
+  # subdomain (e.g., +www+) fragment for convenience, but notice that the
+  # retrieved record's domain name is always fully-qualified.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   records = zone.records "www", "A"
+  #   records.first.name #=> "www.example.com."
+  #
+  # You can use Zone#replace to update the +ttl+ and +data+ for a record.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.replace "www", "A", 86400, ["5.6.7.8"]
+  #
+  # Or, you can use Zone#modify to update just the +ttl+ or +data+, without the
+  # risk of inadvertently changing values that you wish to leave unchanged.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.modify "www", "A" do |r|
+  #     r.ttl = 3600 # change only the TTL
+  #   end
+  #
+  # You can also delete records by name and type.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.remove "www", "A"
+  #   record = change.deletions.first
+  #
+  # The best way to add, remove, and update multiple records in a single
+  # {transaction}[https://cloud.google.com/dns/records] is to call Zone#update
+  # with a block. See Zone::Transaction.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.update do |tx|
+  #     tx.add     "www", "A",  86400, "1.2.3.4"
+  #     tx.remove  "example.com.", "TXT"
+  #     tx.replace "example.com.", "MX", 86400, ["10 mail1.example.com.",
+  #                                              "20 mail2.example.com."]
+  #     tx.modify "www.example.com.", "CNAME" do |r|
+  #       r.ttl = 86400 # only change the TTL
+  #     end
+  #   end
+  #
+  # Finally, you can add and delete records by reference, using Zone#update.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   to_add = zone.record "www", "AAAA", 86400, ["2607:f8b0:400a:801::1005"]
+  #   to_delete = zone.records "www", "A"
+  #   change = zone.update to_add, to_delete
+  #
+  # == Listing Changes
+  #
+  # Because the transactions you execute against your zone do not always
+  # complete immediately, you can retrieve and inspect changes.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   changes = zone.changes
+  #   changes.each do |change|
+  #     puts "#{change.id} - #{change.started_at} - #{change.status}"
+  #   end
+  #
+  # == Importing and exporting zone files
+  #
+  # You can import from a zone file. Because the Cloud DNS service only allows
+  # the zone to have one Record instance for each name and type combination,
+  # lines may be merged as needed into records with multiple +data+ values.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #   change = zone.import "path/to/db.example.com"
+  #
+  # You can also export to a zone file.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   dns = gcloud.dns
+  #   zone = dns.zone "example-com"
+  #
+  #   zone.export "path/to/db.example.com"
+  module Dns
+  end
+end