Update Pub/Sub reference/resource documentation (#2725)

* Add reference?/resource? helper methods
  * Topic#reference?
  * Topic#resource?
  * Subscription#reference?
  * Subscription#resource?
* Add documentation for methods that will make an API call
  when called on a reference object.
  * Topic#labels
  * Subscription#topic
  * Subscription#deadline
  * Subscription#retain_acked
  * Subscription#retention
  * Subscription#endpoint
  * Subscription#labels
  * Subscription#exists?
  * Subscription#listen (without deadline optional argument)
* Add example code for avoiding API calls to Overview guide.

google-cloud-pubsub/OVERVIEW.md

@@ -316,6 +316,44 @@ received_messages = sub.pull
 sub.modify_ack_deadline 120, received_messages
 ```
 
+## Minimizing API calls before receiving and acknowledging messages
+
+A subscription object can be created without making any API calls by providing
+the `skip_lookup` argument to {Google::Cloud::Pubsub::Project#subscription
+Project#subscription} or {Google::Cloud::Pubsub::Topic#subscription
+Topic#subscription}. A subscriber object can also be created without an API call
+by providing the `deadline` optional argument to
+{Google::Cloud::Pubsub::Subscription#listen Subscription#listen}:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::Pubsub.new
+
+# No API call is made to retrieve the subscription resource.
+sub = pubsub.subscription "my-topic-sub", skip_lookup: true
+
+# No API call is made to retrieve the subscription deadline.
+subscriber = sub.listen deadline: 60 do |received_message|
+  # process message
+  received_message.acknowledge!
+end
+
+# Start background threads that will call block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop.wait!
+```
+
+Skipping API calls may be used to avoid `Google::Cloud::PermissionDeniedError`
+if your account has limited access to the Pub/Sub API. In particular, the role
+`roles/pubsub.subscriber` does not have the permission
+`pubsub.subscriptions.get`, which is required to retrieve a subscription
+resource. See [Access Control -
+Roles](https://cloud.google.com/pubsub/docs/access-control#tbl_roles) for the
+complete list of Pub/Sub roles and permissions.
+
 ## Creating a snapshot and using seek
 
 You can create a snapshot to retain the existing backlog on a subscription. The

google-cloud-pubsub/acceptance/pubsub/pubsub_test.rb

@@ -33,7 +33,7 @@ def retrieve_snapshot project, subscription, snapshot_name
 
   let(:new_topic_name)  {  $topic_names[0] }
   let(:topic_names)     {  $topic_names[3..6] }
-  let(:lazy_topic_name) {  $topic_names[7] }
+  let(:reference_topic_name) {  $topic_names[7] }
   let(:labels) { { "foo" => "bar" } }
 
   before do

google-cloud-pubsub/lib/google/cloud/pubsub/project.rb

@@ -150,7 +150,7 @@ def project_id
         def topic topic_name, project: nil, skip_lookup: nil, async: nil
           ensure_service!
           options = { project: project }
-          return Topic.new_lazy(topic_name, service, options) if skip_lookup
+          return Topic.from_name(topic_name, service, options) if skip_lookup
           grpc = service.get_topic topic_name
           Topic.from_grpc grpc, service, async: async
         rescue Google::Cloud::NotFoundError
@@ -282,7 +282,7 @@ def subscription subscription_name, project: nil, skip_lookup: nil
           ensure_service!
           options = { project: project }
           if skip_lookup
-            return Subscription.new_lazy subscription_name, service, options
+            return Subscription.from_name subscription_name, service, options
           end
           grpc = service.get_subscription subscription_name
           Subscription.from_grpc grpc, service

google-cloud-pubsub/lib/google/cloud/pubsub/snapshot.rb

@@ -79,7 +79,7 @@ def name
         #   snapshot.topic.name #=> "projects/my-project/topics/my-topic"
         #
         def topic
-          Topic.new_lazy @grpc.topic, service
+          Topic.from_name @grpc.topic, service
         end
 
         ##