lib/google/cloud/pubsub/v1/subscriber_client.rb in google-cloud-pubsub-0.32.2 vs lib/google/cloud/pubsub/v1/subscriber_client.rb in google-cloud-pubsub-0.33.0

- old
+ new

@@ -32,12 +32,12 @@ module Google module Cloud module Pubsub module V1 # The service that an application uses to manipulate subscriptions and to - # consume messages from a subscription via the +Pull+ method or by - # establishing a bi-directional stream using the +StreamingPull+ method. + # consume messages from a subscription via the `Pull` method or by + # establishing a bi-directional stream using the `StreamingPull` method. # # @!attribute [r] iam_policy_stub # @return [Google::Iam::V1::IAMPolicy::Stub] # @!attribute [r] subscriber_stub # @return [Google::Pubsub::V1::Subscriber::Stub] @@ -351,35 +351,35 @@ # Service calls # Creates a subscription to a given topic. See the # <a href="/pubsub/docs/admin#resource_names"> resource name rules</a>. - # If the subscription already exists, returns +ALREADY_EXISTS+. - # If the corresponding topic doesn't exist, returns +NOT_FOUND+. + # If the subscription already exists, returns `ALREADY_EXISTS`. + # If the corresponding topic doesn't exist, returns `NOT_FOUND`. # # If the name is not provided in the request, the server will assign a random # name for this subscription on the same project as the topic, conforming # to the # [resource name format](https://cloud.google.com/pubsub/docs/overview#names). # The generated name is populated in the returned Subscription object. # Note that for REST API requests, you must specify a name in the request. # # @param name [String] # The name of the subscription. It must have the format - # +"projects/\\{project}/subscriptions/\\{subscription}"+. +\\{subscription}+ must - # start with a letter, and contain only letters (+[A-Za-z]+), numbers - # (+[0-9]+), dashes (+-+), underscores (+_+), periods (+.+), tildes (+~+), - # plus (+++) or percent signs (+%+). It must be between 3 and 255 characters - # in length, and it must not start with +"goog"+ + # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must + # start with a letter, and contain only letters (`[A-Za-z]`), numbers + # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`), + # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters + # in length, and it must not start with `"goog"` # @param topic [String] # The name of the topic from which this subscription is receiving messages. - # Format is +projects/\\{project}/topics/\\{topic}+. - # The value of this field will be +_deleted-topic_+ if the topic has been + # Format is `projects/{project}/topics/{topic}`. + # The value of this field will be `_deleted-topic_` if the topic has been # deleted. # @param push_config [Google::Pubsub::V1::PushConfig | Hash] # If push delivery is used with this subscription, this field is - # used to configure it. An empty +pushConfig+ signifies that the subscriber + # used to configure it. An empty `pushConfig` signifies that the subscriber # will pull and ack messages using API methods. # A hash of the same form as `Google::Pubsub::V1::PushConfig` # can also be provided. # @param ack_deadline_seconds [Integer] # This value is the maximum time after a subscriber receives a message @@ -388,13 +388,13 @@ # acknowledged, it is an outstanding message and will not be delivered # again during that time (on a best-effort basis). # # For pull subscriptions, this value is used as the initial value for the ack # deadline. To override this value for a given message, call - # +ModifyAckDeadline+ with the corresponding +ack_id+ if using - # non-streaming pull or send the +ack_id+ in a - # +StreamingModifyAckDeadlineRequest+ if using streaming pull. + # `ModifyAckDeadline` with the corresponding `ack_id` if using + # non-streaming pull or send the `ack_id` in a + # `StreamingModifyAckDeadlineRequest` if using streaming pull. # The minimum custom deadline you can specify is 10 seconds. # The maximum custom deadline you can specify is 600 seconds (10 minutes). # If this parameter is 0, a default value of 10 seconds is used. # # For push delivery, this value is also used to set the request timeout for @@ -403,20 +403,20 @@ # If the subscriber never acknowledges the message, the Pub/Sub # system will eventually redeliver the message. # @param retain_acked_messages [true, false] # Indicates whether to retain acknowledged messages. If true, then # messages are not expunged from the subscription's backlog, even if they are - # acknowledged, until they fall out of the +message_retention_duration+ + # acknowledged, until they fall out of the `message_retention_duration` # window.<br><br> # <b>ALPHA:</b> This feature is part of an alpha release. This API might be # changed in backward-incompatible ways and is not recommended for production # use. It is not subject to any SLA or deprecation policy. # @param message_retention_duration [Google::Protobuf::Duration | Hash] # How long to retain unacknowledged messages in the subscription's backlog, # from the moment a message is published. - # If +retain_acked_messages+ is true, then this also configures the retention - # of acknowledged messages, and thus configures how far back in time a +Seek+ + # If `retain_acked_messages` is true, then this also configures the retention + # of acknowledged messages, and thus configures how far back in time a `Seek` # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10 # minutes.<br><br> # <b>ALPHA:</b> This feature is part of an alpha release. This API might be # changed in backward-incompatible ways and is not recommended for production # use. It is not subject to any SLA or deprecation policy. @@ -465,11 +465,11 @@ # Gets the configuration details of a subscription. # # @param subscription [String] # The name of the subscription to get. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [Google::Pubsub::V1::Subscription] @@ -540,11 +540,11 @@ # Lists matching subscriptions. # # @param project [String] # The name of the cloud project that subscriptions belong to. - # Format is +projects/\\{project}+. + # Format is `projects/{project}`. # @param page_size [Integer] # The maximum number of resources contained in the underlying API # response. If page streaming is performed per-resource, this # parameter does not affect the return value. If page streaming is # performed per-page, this determines the maximum number of @@ -592,18 +592,18 @@ req = Google::Gax::to_proto(req, Google::Pubsub::V1::ListSubscriptionsRequest) @list_subscriptions.call(req, options, &block) end # Deletes an existing subscription. All messages retained in the subscription - # are immediately dropped. Calls to +Pull+ after deletion will return - # +NOT_FOUND+. After a subscription is deleted, a new one may be created with + # are immediately dropped. Calls to `Pull` after deletion will return + # `NOT_FOUND`. After a subscription is deleted, a new one may be created with # the same name, but the new one has no association with the old # subscription or its topic unless the same topic is specified. # # @param subscription [String] # The subscription to delete. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [] @@ -630,21 +630,21 @@ # Modifies the ack deadline for a specific message. This method is useful # to indicate that more time is needed to process a message by the # subscriber, or to make the message available for redelivery if the # processing was interrupted. Note that this does not modify the - # subscription-level +ackDeadlineSeconds+ used for subsequent messages. + # subscription-level `ackDeadlineSeconds` used for subsequent messages. # # @param subscription [String] # The name of the subscription. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param ack_ids [Array<String>] # List of acknowledgment IDs. # @param ack_deadline_seconds [Integer] # The new ack deadline with respect to the time this request was sent to # the Pub/Sub system. For example, if the value is 10, the new - # ack deadline will expire 10 seconds after the +ModifyAckDeadline+ call + # ack deadline will expire 10 seconds after the `ModifyAckDeadline` call # was made. Specifying zero may immediately make the message available for # another pull request. # The minimum deadline you can specify is 0 seconds. # The maximum deadline you can specify is 600 seconds (10 minutes). # @param options [Google::Gax::CallOptions] @@ -658,14 +658,14 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_subscription = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +ack_ids+: + # # TODO: Initialize `ack_ids`: # ack_ids = [] # - # # TODO: Initialize +ack_deadline_seconds+: + # # TODO: Initialize `ack_deadline_seconds`: # ack_deadline_seconds = 0 # subscriber_client.modify_ack_deadline(formatted_subscription, ack_ids, ack_deadline_seconds) def modify_ack_deadline \ subscription, @@ -681,24 +681,24 @@ req = Google::Gax::to_proto(req, Google::Pubsub::V1::ModifyAckDeadlineRequest) @modify_ack_deadline.call(req, options, &block) nil end - # Acknowledges the messages associated with the +ack_ids+ in the - # +AcknowledgeRequest+. The Pub/Sub system can remove the relevant messages + # Acknowledges the messages associated with the `ack_ids` in the + # `AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages # from the subscription. # # Acknowledging a message whose ack deadline has expired may succeed, # but such a message may be redelivered later. Acknowledging a message more # than once will not result in an error. # # @param subscription [String] # The subscription whose message is being acknowledged. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param ack_ids [Array<String>] # The acknowledgment ID for the messages being acknowledged that was returned - # by the Pub/Sub system in the +Pull+ response. Must not be empty. + # by the Pub/Sub system in the `Pull` response. Must not be empty. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [] @@ -708,11 +708,11 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_subscription = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +ack_ids+: + # # TODO: Initialize `ack_ids`: # ack_ids = [] # subscriber_client.acknowledge(formatted_subscription, ack_ids) def acknowledge \ subscription, @@ -727,23 +727,23 @@ @acknowledge.call(req, options, &block) nil end # Pulls messages from the server. Returns an empty list if there are no - # messages available in the backlog. The server may return +UNAVAILABLE+ if + # messages available in the backlog. The server may return `UNAVAILABLE` if # there are too many concurrent pull requests pending for the given # subscription. # # @param subscription [String] # The subscription from which messages should be pulled. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param max_messages [Integer] # The maximum number of messages returned for this request. The Pub/Sub # system may return fewer than the number specified. # @param return_immediately [true, false] # If this field set to true, the system will respond immediately even if - # it there are no messages available to return in the +Pull+ response. + # it there are no messages available to return in the `Pull` response. # Otherwise, the system may wait (for a bounded amount of time) until at # least one message is available, rather than returning no messages. The # client may cancel the request if it does not wish to wait any longer for # the response. # @param options [Google::Gax::CallOptions] @@ -758,11 +758,11 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_subscription = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +max_messages+: + # # TODO: Initialize `max_messages`: # max_messages = 0 # response = subscriber_client.pull(formatted_subscription, max_messages) def pull \ subscription, @@ -780,11 +780,11 @@ end # Establishes a stream with the server, which sends messages down to the # client. The client streams acknowledgements and ack deadline modifications # back to the server. The server will close the stream and return the status - # on any error. The server may close the stream with status +UNAVAILABLE+ to + # on any error. The server may close the stream with status `UNAVAILABLE` to # reassign server-side resources, in which case, the client should # re-establish the stream. Flow control can be achieved by configuring the # underlying RPC channel. # # @param reqs [Enumerable<Google::Pubsub::V1::StreamingPullRequest>] @@ -806,11 +806,11 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_subscription = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +stream_ack_deadline_seconds+: + # # TODO: Initialize `stream_ack_deadline_seconds`: # stream_ack_deadline_seconds = 0 # request = { subscription: formatted_subscription, stream_ack_deadline_seconds: stream_ack_deadline_seconds } # requests = [request] # subscriber_client.streaming_pull(requests).each do |element| # # Process element. @@ -821,27 +821,27 @@ Google::Gax::to_proto(req, Google::Pubsub::V1::StreamingPullRequest) end @streaming_pull.call(request_protos, options) end - # Modifies the +PushConfig+ for a specified subscription. + # Modifies the `PushConfig` for a specified subscription. # # This may be used to change a push subscription to a pull one (signified by - # an empty +PushConfig+) or vice versa, or change the endpoint URL and other + # an empty `PushConfig`) or vice versa, or change the endpoint URL and other # attributes of a push subscription. Messages will accumulate for delivery - # continuously through the call regardless of changes to the +PushConfig+. + # continuously through the call regardless of changes to the `PushConfig`. # # @param subscription [String] # The name of the subscription. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param push_config [Google::Pubsub::V1::PushConfig | Hash] # The push configuration for future deliveries. # - # An empty +pushConfig+ indicates that the Pub/Sub system should + # An empty `pushConfig` indicates that the Pub/Sub system should # stop pushing messages from the given subscription and allow # messages to be pulled and acknowledged - effectively pausing - # the subscription if +Pull+ or +StreamingPull+ is not called. + # the subscription if `Pull` or `StreamingPull` is not called. # A hash of the same form as `Google::Pubsub::V1::PushConfig` # can also be provided. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. @@ -853,11 +853,11 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_subscription = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +push_config+: + # # TODO: Initialize `push_config`: # push_config = {} # subscriber_client.modify_push_config(formatted_subscription, push_config) def modify_push_config \ subscription, @@ -878,11 +878,11 @@ # changed in backward-incompatible ways and is not recommended for production # use. It is not subject to any SLA or deprecation policy. # # @param project [String] # The name of the cloud project that snapshots belong to. - # Format is +projects/\\{project}+. + # Format is `projects/{project}`. # @param page_size [Integer] # The maximum number of resources contained in the underlying API # response. If page streaming is performed per-resource, this # parameter does not affect the return value. If page streaming is # performed per-page, this determines the maximum number of @@ -933,15 +933,15 @@ # Creates a snapshot from the requested subscription.<br><br> # <b>ALPHA:</b> This feature is part of an alpha release. This API might be # changed in backward-incompatible ways and is not recommended for production # use. It is not subject to any SLA or deprecation policy. - # If the snapshot already exists, returns +ALREADY_EXISTS+. - # If the requested subscription doesn't exist, returns +NOT_FOUND+. + # If the snapshot already exists, returns `ALREADY_EXISTS`. + # If the requested subscription doesn't exist, returns `NOT_FOUND`. # If the backlog in the subscription is too old -- and the resulting snapshot - # would expire in less than 1 hour -- then +FAILED_PRECONDITION+ is returned. - # See also the +Snapshot.expire_time+ field. If the name is not provided in + # would expire in less than 1 hour -- then `FAILED_PRECONDITION` is returned. + # See also the `Snapshot.expire_time` field. If the name is not provided in # the request, the server will assign a random # name for this snapshot on the same project as the subscription, conforming # to the [resource name format](https://cloud.google.com/pubsub/docs/overview#names). # The generated # name is populated in the returned Snapshot object. Note that for REST API @@ -950,21 +950,21 @@ # @param name [String] # Optional user-provided name for this snapshot. # If the name is not provided in the request, the server will assign a random # name for this snapshot on the same project as the subscription. # Note that for REST API requests, you must specify a name. - # Format is +projects/\\{project}/snapshots/\\{snap}+. + # Format is `projects/{project}/snapshots/{snap}`. # @param subscription [String] # The subscription whose backlog the snapshot retains. # Specifically, the created snapshot is guaranteed to retain: # (a) The existing backlog on the subscription. More precisely, this is # defined as the messages in the subscription's backlog that are # unacknowledged upon the successful completion of the - # +CreateSnapshot+ request; as well as: + # `CreateSnapshot` request; as well as: # (b) Any messages published to the subscription's topic following the # successful completion of the CreateSnapshot request. - # Format is +projects/\\{project}/subscriptions/\\{sub}+. + # Format is `projects/{project}/subscriptions/{sub}`. # @param labels [Hash{String => String}] # User labels. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. @@ -1053,11 +1053,11 @@ # created with the same name, but the new one has no association with the old # snapshot or its subscription, unless the same subscription is specified. # # @param snapshot [String] # The name of the snapshot to delete. - # Format is +projects/\\{project}/snapshots/\\{snap}+. + # Format is `projects/{project}/snapshots/{snap}`. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [] @@ -1095,21 +1095,21 @@ # Messages retained in the subscription that were published before this # time are marked as acknowledged, and messages retained in the # subscription that were published after this time are marked as # unacknowledged. Note that this operation affects only those messages # retained in the subscription (configured by the combination of - # +message_retention_duration+ and +retain_acked_messages+). For example, - # if +time+ corresponds to a point before the message retention + # `message_retention_duration` and `retain_acked_messages`). For example, + # if `time` corresponds to a point before the message retention # window (or to a point before the system's notion of the subscription # creation time), only retained messages will be marked as unacknowledged, # and already-expunged messages will not be restored. # A hash of the same form as `Google::Protobuf::Timestamp` # can also be provided. # @param snapshot [String] # The snapshot to seek to. The snapshot's topic must be the same as that of # the provided subscription. - # Format is +projects/\\{project}/snapshots/\\{snap}+. + # Format is `projects/{project}/snapshots/{snap}`. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [Google::Pubsub::V1::SeekResponse] @@ -1141,14 +1141,14 @@ # Sets the access control policy on the specified resource. Replaces any # existing policy. # # @param resource [String] # REQUIRED: The resource for which the policy is being specified. - # +resource+ is usually specified as a path. For example, a Project - # resource is specified as +projects/\\{project}+. + # `resource` is usually specified as a path. For example, a Project + # resource is specified as `projects/{project}`. # @param policy [Google::Iam::V1::Policy | Hash] - # REQUIRED: The complete policy to be applied to the +resource+. The size of + # REQUIRED: The complete policy to be applied to the `resource`. The size of # the policy is limited to a few 10s of KB. An empty policy is a # valid policy but certain Cloud Platform services (such as Projects) # might reject them. # A hash of the same form as `Google::Iam::V1::Policy` # can also be provided. @@ -1164,11 +1164,11 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_resource = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +policy+: + # # TODO: Initialize `policy`: # policy = {} # response = subscriber_client.set_iam_policy(formatted_resource, policy) def set_iam_policy \ resource, @@ -1187,12 +1187,12 @@ # Returns an empty policy if the resource exists and does not have a policy # set. # # @param resource [String] # REQUIRED: The resource for which the policy is being requested. - # +resource+ is usually specified as a path. For example, a Project - # resource is specified as +projects/\\{project}+. + # `resource` is usually specified as a path. For example, a Project + # resource is specified as `projects/{project}`. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [Google::Iam::V1::Policy] @@ -1221,14 +1221,14 @@ # If the resource does not exist, this will return an empty set of # permissions, not a NOT_FOUND error. # # @param resource [String] # REQUIRED: The resource for which the policy detail is being requested. - # +resource+ is usually specified as a path. For example, a Project - # resource is specified as +projects/\\{project}+. + # `resource` is usually specified as a path. For example, a Project + # resource is specified as `projects/{project}`. # @param permissions [Array<String>] - # The set of permissions to check for the +resource+. Permissions with + # The set of permissions to check for the `resource`. Permissions with # wildcards (such as '*' or 'storage.*') are not allowed. For more # information see # [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions). # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, @@ -1242,10 +1242,10 @@ # require "google/cloud/pubsub" # # subscriber_client = Google::Cloud::Pubsub::Subscriber.new(version: :v1) # formatted_resource = Google::Cloud::Pubsub::V1::SubscriberClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]") # - # # TODO: Initialize +permissions+: + # # TODO: Initialize `permissions`: # permissions = [] # response = subscriber_client.test_iam_permissions(formatted_resource, permissions) def test_iam_permissions \ resource,