google-cloud-pubsub 1.1.3 → 1.10.0

data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Google LLC
+# Copyright 2020 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@ module Google
   module Cloud
   module PubSub
     module V1
+      # A policy constraining the storage of messages published to the topic.
       # @!attribute [rw] allowed_persistence_regions
       #   @return [Array<String>]
       #     A list of IDs of GCP regions where messages that are published to the topic
@@ -29,7 +30,7 @@ module Google
       # A topic resource.
       # @!attribute [rw] name
       #   @return [String]
-      #     The name of the topic. It must have the format
+      #     Required. The name of the topic. It must have the format
       #     `"projects/{project}/topics/{topic}"`. `{topic}` must start with a letter,
       #     and contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
       #     underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
@@ -66,7 +67,9 @@ module Google
       #     at least one attribute.
       # @!attribute [rw] attributes
       #   @return [Hash{String => String}]
-      #     Optional attributes for this message.
+      #     Attributes for this message. If this field is empty, the message must
+      #     contain non-empty data. This can be used to filter messages on the
+      #     subscription.
       # @!attribute [rw] message_id
       #   @return [String]
       #     ID of this message, assigned by the server when the message is published.
@@ -80,10 +83,12 @@ module Google
       #     publisher in a `Publish` call.
       # @!attribute [rw] ordering_key
       #   @return [String]
-      #     Identifies related messages for which publish order should be respected.
-      #     If a `Subscription` has `enable_message_ordering` set to `true`, messages
-      #     published with the same `ordering_key` value will be delivered to
-      #     subscribers in the order in which they are received by the Pub/Sub system.
+      #     If non-empty, identifies related messages for which publish order should be
+      #     respected. If a `Subscription` has `enable_message_ordering` set to `true`,
+      #     messages published with the same non-empty `ordering_key` value will be
+      #     delivered to subscribers in the order in which they are received by the
+      #     Pub/Sub system. All `PubsubMessage`s published in a given `PublishRequest`
+      #     must specify the same `ordering_key` value.
       #     <b>EXPERIMENTAL:</b> This feature is part of a closed 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.
@@ -92,31 +97,31 @@ module Google
       # Request for the GetTopic method.
       # @!attribute [rw] topic
       #   @return [String]
-      #     The name of the topic to get.
+      #     Required. The name of the topic to get.
       #     Format is `projects/{project}/topics/{topic}`.
       class GetTopicRequest; end
 
       # Request for the UpdateTopic method.
       # @!attribute [rw] topic
       #   @return [Google::Cloud::PubSub::V1::Topic]
-      #     The updated topic object.
+      #     Required. The updated topic object.
       # @!attribute [rw] update_mask
       #   @return [Google::Protobuf::FieldMask]
-      #     Indicates which fields in the provided topic to update. Must be specified
-      #     and non-empty. Note that if `update_mask` contains
-      #     "message_storage_policy" then the new value will be determined based on the
-      #     policy configured at the project or organization level. The
-      #     `message_storage_policy` must not be set in the `topic` provided above.
+      #     Required. Indicates which fields in the provided topic to update. Must be
+      #     specified and non-empty. Note that if `update_mask` contains
+      #     "message_storage_policy" but the `message_storage_policy` is not set in
+      #     the `topic` provided above, then the updated value is determined by the
+      #     policy configured at the project or organization level.
       class UpdateTopicRequest; end
 
       # Request for the Publish method.
       # @!attribute [rw] topic
       #   @return [String]
-      #     The messages in the request will be published on this topic.
+      #     Required. The messages in the request will be published on this topic.
       #     Format is `projects/{project}/topics/{topic}`.
       # @!attribute [rw] messages
       #   @return [Array<Google::Cloud::PubSub::V1::PubsubMessage>]
-      #     The messages to publish.
+      #     Required. The messages to publish.
       class PublishRequest; end
 
       # Response for the `Publish` method.
@@ -130,7 +135,7 @@ module Google
       # Request for the `ListTopics` method.
       # @!attribute [rw] project
       #   @return [String]
-      #     The name of the project in which to list topics.
+      #     Required. The name of the project in which to list topics.
       #     Format is `projects/{project-id}`.
       # @!attribute [rw] page_size
       #   @return [Integer]
@@ -155,7 +160,7 @@ module Google
       # Request for the `ListTopicSubscriptions` method.
       # @!attribute [rw] topic
       #   @return [String]
-      #     The name of the topic that subscriptions are attached to.
+      #     Required. The name of the topic that subscriptions are attached to.
       #     Format is `projects/{project}/topics/{topic}`.
       # @!attribute [rw] page_size
       #   @return [Integer]
@@ -170,7 +175,7 @@ module Google
       # Response for the `ListTopicSubscriptions` method.
       # @!attribute [rw] subscriptions
       #   @return [Array<String>]
-      #     The names of the subscriptions that match the request.
+      #     The names of subscriptions attached to the topic specified in the request.
       # @!attribute [rw] next_page_token
       #   @return [String]
       #     If not empty, indicates that there may be more subscriptions that match
@@ -181,7 +186,7 @@ module Google
       # Request for the `ListTopicSnapshots` method.
       # @!attribute [rw] topic
       #   @return [String]
-      #     The name of the topic that snapshots are attached to.
+      #     Required. The name of the topic that snapshots are attached to.
       #     Format is `projects/{project}/topics/{topic}`.
       # @!attribute [rw] page_size
       #   @return [Integer]
@@ -207,25 +212,35 @@ module Google
       # Request for the `DeleteTopic` method.
       # @!attribute [rw] topic
       #   @return [String]
-      #     Name of the topic to delete.
+      #     Required. Name of the topic to delete.
       #     Format is `projects/{project}/topics/{topic}`.
       class DeleteTopicRequest; end
 
+      # Request for the DetachSubscription method.
+      # @!attribute [rw] subscription
+      #   @return [String]
+      #     Required. The subscription to detach.
+      #     Format is `projects/{project}/subscriptions/{subscription}`.
+      class DetachSubscriptionRequest; end
+
+      # Response for the DetachSubscription method.
+      # Reserved for future use.
+      class DetachSubscriptionResponse; end
+
       # A subscription resource.
       # @!attribute [rw] name
       #   @return [String]
-      #     The name of the subscription. It must have the format
+      #     Required. 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"`
+      #     in length, and it must not start with `"goog"`.
       # @!attribute [rw] topic
       #   @return [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
-      #     deleted.
+      #     Required. 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 deleted.
       # @!attribute [rw] push_config
       #   @return [Google::Cloud::PubSub::V1::PushConfig]
       #     If push delivery is used with this subscription, this field is
@@ -291,6 +306,13 @@ module Google
       #     operations on the subscription. If `expiration_policy` is not set, a
       #     *default policy* with `ttl` of 31 days will be used. The minimum allowed
       #     value for `expiration_policy.ttl` is 1 day.
+      # @!attribute [rw] filter
+      #   @return [String]
+      #     An expression written in the Pub/Sub [filter
+      #     language](https://cloud.google.com/pubsub/docs/filtering). If non-empty,
+      #     then only `PubsubMessage`s whose `attributes` field matches the filter are
+      #     delivered on this subscription. If empty, then no messages are filtered
+      #     out.
       # @!attribute [rw] dead_letter_policy
       #   @return [Google::Cloud::PubSub::V1::DeadLetterPolicy]
       #     A policy that specifies the conditions for dead lettering messages in
@@ -301,11 +323,45 @@ module Google
       #     parent project (i.e.,
       #     service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
       #     permission to Acknowledge() messages on this subscription.
-      #     <b>EXPERIMENTAL:</b> This feature is part of a closed 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.
+      # @!attribute [rw] retry_policy
+      #   @return [Google::Cloud::PubSub::V1::RetryPolicy]
+      #     A policy that specifies how Pub/Sub retries message delivery for this
+      #     subscription.
+      #
+      #     If not set, the default retry policy is applied. This generally implies
+      #     that messages will be retried as soon as possible for healthy subscribers.
+      #     RetryPolicy will be triggered on NACKs or acknowledgement deadline
+      #     exceeded events for a given message.
+      # @!attribute [rw] detached
+      #   @return [true, false]
+      #     Indicates whether the subscription is detached from its topic. Detached
+      #     subscriptions don't receive messages from their topic and don't retain any
+      #     backlog. `Pull` and `StreamingPull` requests will return
+      #     FAILED_PRECONDITION. If the subscription is a push subscription, pushes to
+      #     the endpoint will not be made.
       class Subscription; end
 
+      # A policy that specifies how Cloud Pub/Sub retries message delivery.
+      #
+      # Retry delay will be exponential based on provided minimum and maximum
+      # backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
+      #
+      # RetryPolicy will be triggered on NACKs or acknowledgement deadline exceeded
+      # events for a given message.
+      #
+      # Retry Policy is implemented on a best effort basis. At times, the delay
+      # between consecutive deliveries may not match the configuration. That is,
+      # delay can be more or less than configured backoff.
+      # @!attribute [rw] minimum_backoff
+      #   @return [Google::Protobuf::Duration]
+      #     The minimum delay between consecutive deliveries of a given message.
+      #     Value should be between 0 and 600 seconds. Defaults to 10 seconds.
+      # @!attribute [rw] maximum_backoff
+      #   @return [Google::Protobuf::Duration]
+      #     The maximum delay between consecutive deliveries of a given message.
+      #     Value should be between 0 and 600 seconds. Defaults to 600 seconds.
+      class RetryPolicy; end
+
       # Dead lettering is done on a best effort basis. The same message might be
       # dead lettered multiple times.
       #
@@ -355,7 +411,7 @@ module Google
       # @!attribute [rw] push_endpoint
       #   @return [String]
       #     A URL locating the endpoint to which messages should be pushed.
-      #     For example, a Webhook endpoint might use "https://example.com/push".
+      #     For example, a Webhook endpoint might use `https://example.com/push`.
       # @!attribute [rw] attributes
       #   @return [Hash{String => String}]
       #     Endpoint configuration attributes that can be used to control different
@@ -414,8 +470,11 @@ module Google
       #     The message.
       # @!attribute [rw] delivery_attempt
       #   @return [Integer]
-      #     Delivery attempt counter is 1 + (the sum of number of NACKs and number of
-      #     ack_deadline exceeds) for this message.
+      #     The approximate number of times that Cloud Pub/Sub has attempted to deliver
+      #     the associated message to a subscriber.
+      #
+      #     More precisely, this is 1 + (number of NACKs) +
+      #     (number of ack_deadline exceeds) for this message.
       #
       #     A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
       #     exceeds event is whenever a message is not acknowledged within
@@ -423,36 +482,33 @@ module Google
       #     Subscription.ackDeadlineSeconds, but may get extended automatically by
       #     the client library.
       #
-      #     The first delivery of a given message will have this value as 1. The value
-      #     is calculated at best effort and is approximate.
+      #     Upon the first delivery of a given message, `delivery_attempt` will have a
+      #     value of 1. The value is calculated at best effort and is approximate.
       #
       #     If a DeadLetterPolicy is not set on the subscription, this will be 0.
-      #     <b>EXPERIMENTAL:</b> This feature is part of a closed 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.
       class ReceivedMessage; end
 
       # Request for the GetSubscription method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The name of the subscription to get.
+      #     Required. The name of the subscription to get.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       class GetSubscriptionRequest; end
 
       # Request for the UpdateSubscription method.
       # @!attribute [rw] subscription
       #   @return [Google::Cloud::PubSub::V1::Subscription]
-      #     The updated subscription object.
+      #     Required. The updated subscription object.
       # @!attribute [rw] update_mask
       #   @return [Google::Protobuf::FieldMask]
-      #     Indicates which fields in the provided subscription to update.
+      #     Required. Indicates which fields in the provided subscription to update.
       #     Must be specified and non-empty.
       class UpdateSubscriptionRequest; end
 
       # Request for the `ListSubscriptions` method.
       # @!attribute [rw] project
       #   @return [String]
-      #     The name of the project in which to list subscriptions.
+      #     Required. The name of the project in which to list subscriptions.
       #     Format is `projects/{project-id}`.
       # @!attribute [rw] page_size
       #   @return [Integer]
@@ -478,18 +534,18 @@ module Google
       # Request for the DeleteSubscription method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription to delete.
+      #     Required. The subscription to delete.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       class DeleteSubscriptionRequest; end
 
       # Request for the ModifyPushConfig method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The name of the subscription.
+      #     Required. The name of the subscription.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       # @!attribute [rw] push_config
       #   @return [Google::Cloud::PubSub::V1::PushConfig]
-      #     The push configuration for future deliveries.
+      #     Required. The push configuration for future deliveries.
       #
       #     An empty `pushConfig` indicates that the Pub/Sub system should
       #     stop pushing messages from the given subscription and allow
@@ -500,18 +556,21 @@ module Google
       # Request for the `Pull` method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription from which messages should be pulled.
+      #     Required. The subscription from which messages should be pulled.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       # @!attribute [rw] return_immediately
       #   @return [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.
-      #     Otherwise, the system may wait (for a bounded amount of time) until at
-      #     least one message is available, rather than returning no messages.
+      #     Optional. 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. Otherwise, the system may wait (for a bounded amount of time)
+      #     until at least one message is available, rather than returning no messages.
+      #     Warning: setting this field to `true` is discouraged because it adversely
+      #     impacts the performance of `Pull` operations. We recommend that users do
+      #     not set this field.
       # @!attribute [rw] max_messages
       #   @return [Integer]
-      #     The maximum number of messages to return for this request. Must be a
-      #     positive integer. The Pub/Sub system may return fewer than the number
+      #     Required. The maximum number of messages to return for this request. Must
+      #     be a positive integer. The Pub/Sub system may return fewer than the number
       #     specified.
       class PullRequest; end
 
@@ -527,17 +586,17 @@ module Google
       # Request for the ModifyAckDeadline method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The name of the subscription.
+      #     Required. The name of the subscription.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       # @!attribute [rw] ack_ids
       #   @return [Array<String>]
-      #     List of acknowledgment IDs.
+      #     Required. List of acknowledgment IDs.
       # @!attribute [rw] ack_deadline_seconds
       #   @return [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
-      #     was made. Specifying zero might immediately make the message available for
+      #     Required. 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 was
+      #     made. Specifying zero might immediately make the message available for
       #     delivery to another subscriber client. This typically results in an
       #     increase in the rate of message redeliveries (that is, duplicates).
       #     The minimum deadline you can specify is 0 seconds.
@@ -547,12 +606,13 @@ module Google
       # Request for the Acknowledge method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription whose message is being acknowledged.
+      #     Required. The subscription whose message is being acknowledged.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       # @!attribute [rw] ack_ids
       #   @return [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.
+      #     Required. The acknowledgment ID for the messages being acknowledged that
+      #     was returned by the Pub/Sub system in the `Pull` response. Must not be
+      #     empty.
       class AcknowledgeRequest; end
 
       # Request for the `StreamingPull` streaming RPC method. This request is used to
@@ -560,8 +620,8 @@ module Google
       # deadline modifications from the client to the server.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription for which to initialize the new stream. This must be
-      #     provided in the first request on the stream, and must not be set in
+      #     Required. The subscription for which to initialize the new stream. This
+      #     must be provided in the first request on the stream, and must not be set in
       #     subsequent requests from client to server.
       #     Format is `projects/{project}/subscriptions/{sub}`.
       # @!attribute [rw] ack_ids
@@ -593,10 +653,40 @@ module Google
       #     processing was interrupted.
       # @!attribute [rw] stream_ack_deadline_seconds
       #   @return [Integer]
-      #     The ack deadline to use for the stream. This must be provided in the
-      #     first request on the stream, but it can also be updated on subsequent
+      #     Required. The ack deadline to use for the stream. This must be provided in
+      #     the first request on the stream, but it can also be updated on subsequent
       #     requests from client to server. The minimum deadline you can specify is 10
       #     seconds. The maximum deadline you can specify is 600 seconds (10 minutes).
+      # @!attribute [rw] client_id
+      #   @return [String]
+      #     A unique identifier that is used to distinguish client instances from each
+      #     other. Only needs to be provided on the initial request. When a stream
+      #     disconnects and reconnects for the same stream, the client_id should be set
+      #     to the same value so that state associated with the old stream can be
+      #     transferred to the new stream. The same client_id should not be used for
+      #     different client instances.
+      # @!attribute [rw] max_outstanding_messages
+      #   @return [Integer]
+      #     Flow control settings for the maximum number of outstanding messages. When
+      #     there are `max_outstanding_messages` or more currently sent to the
+      #     streaming pull client that have not yet been acked or nacked, the server
+      #     stops sending more messages. The sending of messages resumes once the
+      #     number of outstanding messages is less than this value. If the value is
+      #     <= 0, there is no limit to the number of outstanding messages. This
+      #     property can only be set on the initial StreamingPullRequest. If it is set
+      #     on a subsequent request, the stream will be aborted with status
+      #     `INVALID_ARGUMENT`.
+      # @!attribute [rw] max_outstanding_bytes
+      #   @return [Integer]
+      #     Flow control settings for the maximum number of outstanding bytes. When
+      #     there are `max_outstanding_bytes` or more worth of messages currently sent
+      #     to the streaming pull client that have not yet been acked or nacked, the
+      #     server will stop sending more messages. The sending of messages resumes
+      #     once the number of outstanding bytes is less than this value. If the value
+      #     is <= 0, there is no limit to the number of outstanding bytes. This
+      #     property can only be set on the initial StreamingPullRequest. If it is set
+      #     on a subsequent request, the stream will be aborted with status
+      #     `INVALID_ARGUMENT`.
       class StreamingPullRequest; end
 
       # Response for the `StreamingPull` method. This response is used to stream
@@ -609,16 +699,15 @@ module Google
       # Request for the `CreateSnapshot` method.
       # @!attribute [rw] name
       #   @return [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.  See the
-      #     <a href="https://cloud.google.com/pubsub/docs/admin#resource_names">
-      #     resource name rules</a>.
-      #     Format is `projects/{project}/snapshots/{snap}`.
+      #     Required. 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.  See the <a
+      #     href="https://cloud.google.com/pubsub/docs/admin#resource_names"> resource
+      #     name rules</a>. Format is `projects/{project}/snapshots/{snap}`.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription whose backlog the snapshot retains.
+      #     Required. 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
@@ -636,10 +725,10 @@ module Google
       # Request for the UpdateSnapshot method.
       # @!attribute [rw] snapshot
       #   @return [Google::Cloud::PubSub::V1::Snapshot]
-      #     The updated snapshot object.
+      #     Required. The updated snapshot object.
       # @!attribute [rw] update_mask
       #   @return [Google::Protobuf::FieldMask]
-      #     Indicates which fields in the provided snapshot to update.
+      #     Required. Indicates which fields in the provided snapshot to update.
       #     Must be specified and non-empty.
       class UpdateSnapshotRequest; end
 
@@ -676,14 +765,14 @@ module Google
       # Request for the GetSnapshot method.
       # @!attribute [rw] snapshot
       #   @return [String]
-      #     The name of the snapshot to get.
+      #     Required. The name of the snapshot to get.
       #     Format is `projects/{project}/snapshots/{snap}`.
       class GetSnapshotRequest; end
 
       # Request for the `ListSnapshots` method.
       # @!attribute [rw] project
       #   @return [String]
-      #     The name of the project in which to list snapshots.
+      #     Required. The name of the project in which to list snapshots.
       #     Format is `projects/{project-id}`.
       # @!attribute [rw] page_size
       #   @return [Integer]
@@ -708,14 +797,14 @@ module Google
       # Request for the `DeleteSnapshot` method.
       # @!attribute [rw] snapshot
       #   @return [String]
-      #     The name of the snapshot to delete.
+      #     Required. The name of the snapshot to delete.
       #     Format is `projects/{project}/snapshots/{snap}`.
       class DeleteSnapshotRequest; end
 
       # Request for the `Seek` method.
       # @!attribute [rw] subscription
       #   @return [String]
-      #     The subscription to affect.
+      #     Required. The subscription to affect.
       # @!attribute [rw] time
       #   @return [Google::Protobuf::Timestamp]
       #     The time to seek to.

data/lib/google/cloud/pubsub/v1/doc/google/type/expr.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Google LLC
+# Copyright 2020 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.