google-cloud-pubsub-v1 0.5.0 → 0.6.1

data/lib/google/cloud/pubsub/v1/publisher/client.rb

@@ -42,13 +42,12 @@ module Google
             # See {::Google::Cloud::PubSub::V1::Publisher::Client::Configuration}
             # for a description of the configuration fields.
             #
-            # ## Example
+            # @example
             #
-            # To modify the configuration for all Publisher clients:
-            #
-            #     ::Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
-            #       config.timeout = 10.0
-            #     end
+            #   # Modify the configuration for all Publisher clients
+            #   ::Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
+            #     config.timeout = 10.0
+            #   end
             #
             # @yield [config] Configure the Client client.
             # @yieldparam config [Client::Configuration]
@@ -140,19 +139,15 @@ module Google
             ##
             # Create a new Publisher client object.
             #
-            # ## Examples
-            #
-            # To create a new Publisher client with the default
-            # configuration:
-            #
-            #     client = ::Google::Cloud::PubSub::V1::Publisher::Client.new
+            # @example
             #
-            # To create a new Publisher client with a custom
-            # configuration:
+            #   # Create a client using the default configuration
+            #   client = ::Google::Cloud::PubSub::V1::Publisher::Client.new
             #
-            #     client = ::Google::Cloud::PubSub::V1::Publisher::Client.new do |config|
-            #       config.timeout = 10.0
-            #     end
+            #   # Create a client using a custom configuration
+            #   client = ::Google::Cloud::PubSub::V1::Publisher::Client.new do |config|
+            #     config.timeout = 10.0
+            #   end
             #
             # @yield [config] Configure the Publisher client.
             # @yieldparam config [Client::Configuration]
@@ -172,10 +167,9 @@ module Google
 
               # Create credentials
               credentials = @config.credentials
-              # Use self-signed JWT if the scope and endpoint are unchanged from default,
+              # Use self-signed JWT if the endpoint is unchanged from default,
               # but only if the default endpoint does not have a region prefix.
-              enable_self_signed_jwt = @config.scope == Client.configure.scope &&
-                                       @config.endpoint == Client.configure.endpoint &&
+              enable_self_signed_jwt = @config.endpoint == Client.configure.endpoint &&
                                        !@config.endpoint.split(".").first.include?("-")
               credentials ||= Credentials.default scope: @config.scope,
                                                   enable_self_signed_jwt: enable_self_signed_jwt
@@ -210,7 +204,7 @@ module Google
             #   @param options [::Gapic::CallOptions, ::Hash]
             #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
             #
-            # @overload create_topic(name: nil, labels: nil, message_storage_policy: nil, kms_key_name: nil, schema_settings: nil, satisfies_pzs: nil)
+            # @overload create_topic(name: nil, labels: nil, message_storage_policy: nil, kms_key_name: nil, schema_settings: nil, satisfies_pzs: nil, message_retention_duration: nil)
             #   Pass arguments to `create_topic` via keyword arguments. Note that at
             #   least one keyword argument is required. To specify no parameters, or to keep all
             #   the default parameter values, pass an empty Hash as a request object (see above).
@@ -239,6 +233,15 @@ module Google
             #   @param satisfies_pzs [::Boolean]
             #     Reserved for future use. This field is set only in responses from the
             #     server; it is ignored if it is set in any requests.
+            #   @param message_retention_duration [::Google::Protobuf::Duration, ::Hash]
+            #     Indicates the minimum duration to retain a message after it is published to
+            #     the topic. If this field is set, messages published to the topic in the
+            #     last `message_retention_duration` are always available to subscribers. For
+            #     instance, it allows any attached subscription to [seek to a
+            #     timestamp](https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
+            #     that is up to `message_retention_duration` in the past. If this field is
+            #     not set, message retention is controlled by settings on individual
+            #     subscriptions. Cannot be more than 7 days or less than 10 minutes.
             #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Google::Cloud::PubSub::V1::Topic]
@@ -248,6 +251,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::Topic.new
+            #
+            #   # Call the create_topic method.
+            #   result = client.create_topic request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::Topic.
+            #   p result
+            #
             def create_topic request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -265,16 +283,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "name" => request.name
-              }
+              header_params = {}
+              if request.name
+                header_params["name"] = request.name
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.create_topic.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.create_topic.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :create_topic, request, options: options do |response, operation|
@@ -321,6 +343,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::UpdateTopicRequest.new
+            #
+            #   # Call the update_topic method.
+            #   result = client.update_topic request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::Topic.
+            #   p result
+            #
             def update_topic request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -338,16 +375,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic.name" => request.topic.name
-              }
+              header_params = {}
+              if request.topic&.name
+                header_params["topic.name"] = request.topic.name
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.update_topic.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.update_topic.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :update_topic, request, options: options do |response, operation|
@@ -391,6 +432,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::PublishRequest.new
+            #
+            #   # Call the publish method.
+            #   result = client.publish request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::PublishResponse.
+            #   p result
+            #
             def publish request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -408,16 +464,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic" => request.topic
-              }
+              header_params = {}
+              if request.topic
+                header_params["topic"] = request.topic
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.publish.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.publish.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :publish, request, options: options do |response, operation|
@@ -458,6 +518,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::GetTopicRequest.new
+            #
+            #   # Call the get_topic method.
+            #   result = client.get_topic request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::Topic.
+            #   p result
+            #
             def get_topic request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -475,16 +550,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic" => request.topic
-              }
+              header_params = {}
+              if request.topic
+                header_params["topic"] = request.topic
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.get_topic.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.get_topic.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :get_topic, request, options: options do |response, operation|
@@ -531,6 +610,27 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::ListTopicsRequest.new
+            #
+            #   # Call the list_topics method.
+            #   result = client.list_topics request
+            #
+            #   # The returned object is of type Gapic::PagedEnumerable. You can
+            #   # iterate over all elements by calling #each, and the enumerable
+            #   # will lazily make API calls to fetch subsequent pages. Other
+            #   # methods are also available for managing paging directly.
+            #   result.each do |response|
+            #     # Each element is of type ::Google::Cloud::PubSub::V1::Topic.
+            #     p response
+            #   end
+            #
             def list_topics request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -548,16 +648,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "project" => request.project
-              }
+              header_params = {}
+              if request.project
+                header_params["project"] = request.project
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.list_topics.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.list_topics.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :list_topics, request, options: options do |response, operation|
@@ -605,6 +709,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::ListTopicSubscriptionsRequest.new
+            #
+            #   # Call the list_topic_subscriptions method.
+            #   result = client.list_topic_subscriptions request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::ListTopicSubscriptionsResponse.
+            #   p result
+            #
             def list_topic_subscriptions request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -622,16 +741,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic" => request.topic
-              }
+              header_params = {}
+              if request.topic
+                header_params["topic"] = request.topic
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.list_topic_subscriptions.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.list_topic_subscriptions.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :list_topic_subscriptions, request, options: options do |response, operation|
@@ -682,6 +805,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::ListTopicSnapshotsRequest.new
+            #
+            #   # Call the list_topic_snapshots method.
+            #   result = client.list_topic_snapshots request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::ListTopicSnapshotsResponse.
+            #   p result
+            #
             def list_topic_snapshots request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -699,16 +837,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic" => request.topic
-              }
+              header_params = {}
+              if request.topic
+                header_params["topic"] = request.topic
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.list_topic_snapshots.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.list_topic_snapshots.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :list_topic_snapshots, request, options: options do |response, operation|
@@ -753,6 +895,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::DeleteTopicRequest.new
+            #
+            #   # Call the delete_topic method.
+            #   result = client.delete_topic request
+            #
+            #   # The returned object is of type Google::Protobuf::Empty.
+            #   p result
+            #
             def delete_topic request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -770,16 +927,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "topic" => request.topic
-              }
+              header_params = {}
+              if request.topic
+                header_params["topic"] = request.topic
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.delete_topic.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.delete_topic.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :delete_topic, request, options: options do |response, operation|
@@ -823,6 +984,21 @@ module Google
             #
             # @raise [::Google::Cloud::Error] if the RPC is aborted.
             #
+            # @example Basic example
+            #   require "google/cloud/pubsub/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::PubSub::V1::Publisher::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::PubSub::V1::DetachSubscriptionRequest.new
+            #
+            #   # Call the detach_subscription method.
+            #   result = client.detach_subscription request
+            #
+            #   # The returned object is of type Google::Cloud::PubSub::V1::DetachSubscriptionResponse.
+            #   p result
+            #
             def detach_subscription request, options = nil
               raise ::ArgumentError, "request must be provided" if request.nil?
 
@@ -840,16 +1016,20 @@ module Google
                 gapic_version: ::Google::Cloud::PubSub::V1::VERSION
               metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
-              header_params = {
-                "subscription" => request.subscription
-              }
+              header_params = {}
+              if request.subscription
+                header_params["subscription"] = request.subscription
+              end
+
               request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
               metadata[:"x-goog-request-params"] ||= request_params_header
 
               options.apply_defaults timeout:      @config.rpcs.detach_subscription.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.detach_subscription.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @publisher_stub.call_rpc :detach_subscription, request, options: options do |response, operation|
@@ -873,22 +1053,21 @@ module Google
             # Configuration can be applied globally to all clients, or to a single client
             # on construction.
             #
-            # # Examples
-            #
-            # To modify the global config, setting the timeout for create_topic
-            # to 20 seconds, and all remaining timeouts to 10 seconds:
-            #
-            #     ::Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
-            #       config.timeout = 10.0
-            #       config.rpcs.create_topic.timeout = 20.0
-            #     end
-            #
-            # To apply the above configuration only to a new client:
-            #
-            #     client = ::Google::Cloud::PubSub::V1::Publisher::Client.new do |config|
-            #       config.timeout = 10.0
-            #       config.rpcs.create_topic.timeout = 20.0
-            #     end
+            # @example
+            #
+            #   # Modify the global config, setting the timeout for
+            #   # create_topic to 20 seconds,
+            #   # and all remaining timeouts to 10 seconds.
+            #   ::Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
+            #     config.timeout = 10.0
+            #     config.rpcs.create_topic.timeout = 20.0
+            #   end
+            #
+            #   # Apply the above configuration only to a new client.
+            #   client = ::Google::Cloud::PubSub::V1::Publisher::Client.new do |config|
+            #     config.timeout = 10.0
+            #     config.rpcs.create_topic.timeout = 20.0
+            #   end
             #
             # @!attribute [rw] endpoint
             #   The hostname or hostname:port of the service endpoint.