Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/pubsub_v1/types/pubsub.py: 98%
241 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 06:03 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2022 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from __future__ import annotations
18from typing import MutableMapping, MutableSequence
20import proto # type: ignore
22from google.protobuf import duration_pb2 # type: ignore
23from google.protobuf import field_mask_pb2 # type: ignore
24from google.protobuf import timestamp_pb2 # type: ignore
25from google.pubsub_v1.types import schema as gp_schema
28__protobuf__ = proto.module(
29 package="google.pubsub.v1",
30 manifest={
31 "MessageStoragePolicy",
32 "SchemaSettings",
33 "Topic",
34 "PubsubMessage",
35 "GetTopicRequest",
36 "UpdateTopicRequest",
37 "PublishRequest",
38 "PublishResponse",
39 "ListTopicsRequest",
40 "ListTopicsResponse",
41 "ListTopicSubscriptionsRequest",
42 "ListTopicSubscriptionsResponse",
43 "ListTopicSnapshotsRequest",
44 "ListTopicSnapshotsResponse",
45 "DeleteTopicRequest",
46 "DetachSubscriptionRequest",
47 "DetachSubscriptionResponse",
48 "Subscription",
49 "RetryPolicy",
50 "DeadLetterPolicy",
51 "ExpirationPolicy",
52 "PushConfig",
53 "BigQueryConfig",
54 "CloudStorageConfig",
55 "ReceivedMessage",
56 "GetSubscriptionRequest",
57 "UpdateSubscriptionRequest",
58 "ListSubscriptionsRequest",
59 "ListSubscriptionsResponse",
60 "DeleteSubscriptionRequest",
61 "ModifyPushConfigRequest",
62 "PullRequest",
63 "PullResponse",
64 "ModifyAckDeadlineRequest",
65 "AcknowledgeRequest",
66 "StreamingPullRequest",
67 "StreamingPullResponse",
68 "CreateSnapshotRequest",
69 "UpdateSnapshotRequest",
70 "Snapshot",
71 "GetSnapshotRequest",
72 "ListSnapshotsRequest",
73 "ListSnapshotsResponse",
74 "DeleteSnapshotRequest",
75 "SeekRequest",
76 "SeekResponse",
77 },
78)
81class MessageStoragePolicy(proto.Message):
82 r"""A policy constraining the storage of messages published to
83 the topic.
85 Attributes:
86 allowed_persistence_regions (MutableSequence[str]):
87 A list of IDs of GCP regions where messages
88 that are published to the topic may be persisted
89 in storage. Messages published by publishers
90 running in non-allowed GCP regions (or running
91 outside of GCP altogether) will be routed for
92 storage in one of the allowed regions. An empty
93 list means that no regions are allowed, and is
94 not a valid configuration.
95 """
97 allowed_persistence_regions: MutableSequence[str] = proto.RepeatedField(
98 proto.STRING,
99 number=1,
100 )
103class SchemaSettings(proto.Message):
104 r"""Settings for validating messages published against a schema.
106 Attributes:
107 schema (str):
108 Required. The name of the schema that messages published
109 should be validated against. Format is
110 ``projects/{project}/schemas/{schema}``. The value of this
111 field will be ``_deleted-schema_`` if the schema has been
112 deleted.
113 encoding (google.pubsub_v1.types.Encoding):
114 The encoding of messages validated against ``schema``.
115 first_revision_id (str):
116 The minimum (inclusive) revision allowed for validating
117 messages. If empty or not present, allow any revision to be
118 validated against last_revision or any revision created
119 before.
120 last_revision_id (str):
121 The maximum (inclusive) revision allowed for validating
122 messages. If empty or not present, allow any revision to be
123 validated against first_revision or any revision created
124 after.
125 """
127 schema: str = proto.Field(
128 proto.STRING,
129 number=1,
130 )
131 encoding: gp_schema.Encoding = proto.Field(
132 proto.ENUM,
133 number=2,
134 enum=gp_schema.Encoding,
135 )
136 first_revision_id: str = proto.Field(
137 proto.STRING,
138 number=3,
139 )
140 last_revision_id: str = proto.Field(
141 proto.STRING,
142 number=4,
143 )
146class Topic(proto.Message):
147 r"""A topic resource.
149 Attributes:
150 name (str):
151 Required. The name of the topic. It must have the format
152 ``"projects/{project}/topics/{topic}"``. ``{topic}`` must
153 start with a letter, and contain only letters
154 (``[A-Za-z]``), numbers (``[0-9]``), dashes (``-``),
155 underscores (``_``), periods (``.``), tildes (``~``), plus
156 (``+``) or percent signs (``%``). It must be between 3 and
157 255 characters in length, and it must not start with
158 ``"goog"``.
159 labels (MutableMapping[str, str]):
160 See [Creating and managing labels]
161 (https://cloud.google.com/pubsub/docs/labels).
162 message_storage_policy (google.pubsub_v1.types.MessageStoragePolicy):
163 Policy constraining the set of Google Cloud
164 Platform regions where messages published to the
165 topic may be stored. If not present, then no
166 constraints are in effect.
167 kms_key_name (str):
168 The resource name of the Cloud KMS CryptoKey to be used to
169 protect access to messages published on this topic.
171 The expected format is
172 ``projects/*/locations/*/keyRings/*/cryptoKeys/*``.
173 schema_settings (google.pubsub_v1.types.SchemaSettings):
174 Settings for validating messages published
175 against a schema.
176 satisfies_pzs (bool):
177 Reserved for future use. This field is set
178 only in responses from the server; it is ignored
179 if it is set in any requests.
180 message_retention_duration (google.protobuf.duration_pb2.Duration):
181 Indicates the minimum duration to retain a message after it
182 is published to the topic. If this field is set, messages
183 published to the topic in the last
184 ``message_retention_duration`` are always available to
185 subscribers. For instance, it allows any attached
186 subscription to `seek to a
187 timestamp <https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time>`__
188 that is up to ``message_retention_duration`` in the past. If
189 this field is not set, message retention is controlled by
190 settings on individual subscriptions. Cannot be more than 31
191 days or less than 10 minutes.
192 """
194 name: str = proto.Field(
195 proto.STRING,
196 number=1,
197 )
198 labels: MutableMapping[str, str] = proto.MapField(
199 proto.STRING,
200 proto.STRING,
201 number=2,
202 )
203 message_storage_policy: "MessageStoragePolicy" = proto.Field(
204 proto.MESSAGE,
205 number=3,
206 message="MessageStoragePolicy",
207 )
208 kms_key_name: str = proto.Field(
209 proto.STRING,
210 number=5,
211 )
212 schema_settings: "SchemaSettings" = proto.Field(
213 proto.MESSAGE,
214 number=6,
215 message="SchemaSettings",
216 )
217 satisfies_pzs: bool = proto.Field(
218 proto.BOOL,
219 number=7,
220 )
221 message_retention_duration: duration_pb2.Duration = proto.Field(
222 proto.MESSAGE,
223 number=8,
224 message=duration_pb2.Duration,
225 )
228class PubsubMessage(proto.Message):
229 r"""A message that is published by publishers and consumed by
230 subscribers. The message must contain either a non-empty data field
231 or at least one attribute. Note that client libraries represent this
232 object differently depending on the language. See the corresponding
233 `client library
234 documentation <https://cloud.google.com/pubsub/docs/reference/libraries>`__
235 for more information. See [quotas and limits]
236 (https://cloud.google.com/pubsub/quotas) for more information about
237 message limits.
239 Attributes:
240 data (bytes):
241 The message data field. If this field is
242 empty, the message must contain at least one
243 attribute.
244 attributes (MutableMapping[str, str]):
245 Attributes for this message. If this field is
246 empty, the message must contain non-empty data.
247 This can be used to filter messages on the
248 subscription.
249 message_id (str):
250 ID of this message, assigned by the server when the message
251 is published. Guaranteed to be unique within the topic. This
252 value may be read by a subscriber that receives a
253 ``PubsubMessage`` via a ``Pull`` call or a push delivery. It
254 must not be populated by the publisher in a ``Publish``
255 call.
256 publish_time (google.protobuf.timestamp_pb2.Timestamp):
257 The time at which the message was published, populated by
258 the server when it receives the ``Publish`` call. It must
259 not be populated by the publisher in a ``Publish`` call.
260 ordering_key (str):
261 If non-empty, identifies related messages for which publish
262 order should be respected. If a ``Subscription`` has
263 ``enable_message_ordering`` set to ``true``, messages
264 published with the same non-empty ``ordering_key`` value
265 will be delivered to subscribers in the order in which they
266 are received by the Pub/Sub system. All ``PubsubMessage``\ s
267 published in a given ``PublishRequest`` must specify the
268 same ``ordering_key`` value. For more information, see
269 `ordering
270 messages <https://cloud.google.com/pubsub/docs/ordering>`__.
271 """
273 data: bytes = proto.Field(
274 proto.BYTES,
275 number=1,
276 )
277 attributes: MutableMapping[str, str] = proto.MapField(
278 proto.STRING,
279 proto.STRING,
280 number=2,
281 )
282 message_id: str = proto.Field(
283 proto.STRING,
284 number=3,
285 )
286 publish_time: timestamp_pb2.Timestamp = proto.Field(
287 proto.MESSAGE,
288 number=4,
289 message=timestamp_pb2.Timestamp,
290 )
291 ordering_key: str = proto.Field(
292 proto.STRING,
293 number=5,
294 )
297class GetTopicRequest(proto.Message):
298 r"""Request for the GetTopic method.
300 Attributes:
301 topic (str):
302 Required. The name of the topic to get. Format is
303 ``projects/{project}/topics/{topic}``.
304 """
306 topic: str = proto.Field(
307 proto.STRING,
308 number=1,
309 )
312class UpdateTopicRequest(proto.Message):
313 r"""Request for the UpdateTopic method.
315 Attributes:
316 topic (google.pubsub_v1.types.Topic):
317 Required. The updated topic object.
318 update_mask (google.protobuf.field_mask_pb2.FieldMask):
319 Required. Indicates which fields in the provided topic to
320 update. Must be specified and non-empty. Note that if
321 ``update_mask`` contains "message_storage_policy" but the
322 ``message_storage_policy`` is not set in the ``topic``
323 provided above, then the updated value is determined by the
324 policy configured at the project or organization level.
325 """
327 topic: "Topic" = proto.Field(
328 proto.MESSAGE,
329 number=1,
330 message="Topic",
331 )
332 update_mask: field_mask_pb2.FieldMask = proto.Field(
333 proto.MESSAGE,
334 number=2,
335 message=field_mask_pb2.FieldMask,
336 )
339class PublishRequest(proto.Message):
340 r"""Request for the Publish method.
342 Attributes:
343 topic (str):
344 Required. The messages in the request will be published on
345 this topic. Format is ``projects/{project}/topics/{topic}``.
346 messages (MutableSequence[google.pubsub_v1.types.PubsubMessage]):
347 Required. The messages to publish.
348 """
350 topic: str = proto.Field(
351 proto.STRING,
352 number=1,
353 )
354 messages: MutableSequence["PubsubMessage"] = proto.RepeatedField(
355 proto.MESSAGE,
356 number=2,
357 message="PubsubMessage",
358 )
361class PublishResponse(proto.Message):
362 r"""Response for the ``Publish`` method.
364 Attributes:
365 message_ids (MutableSequence[str]):
366 The server-assigned ID of each published
367 message, in the same order as the messages in
368 the request. IDs are guaranteed to be unique
369 within the topic.
370 """
372 message_ids: MutableSequence[str] = proto.RepeatedField(
373 proto.STRING,
374 number=1,
375 )
378class ListTopicsRequest(proto.Message):
379 r"""Request for the ``ListTopics`` method.
381 Attributes:
382 project (str):
383 Required. The name of the project in which to list topics.
384 Format is ``projects/{project-id}``.
385 page_size (int):
386 Maximum number of topics to return.
387 page_token (str):
388 The value returned by the last ``ListTopicsResponse``;
389 indicates that this is a continuation of a prior
390 ``ListTopics`` call, and that the system should return the
391 next page of data.
392 """
394 project: str = proto.Field(
395 proto.STRING,
396 number=1,
397 )
398 page_size: int = proto.Field(
399 proto.INT32,
400 number=2,
401 )
402 page_token: str = proto.Field(
403 proto.STRING,
404 number=3,
405 )
408class ListTopicsResponse(proto.Message):
409 r"""Response for the ``ListTopics`` method.
411 Attributes:
412 topics (MutableSequence[google.pubsub_v1.types.Topic]):
413 The resulting topics.
414 next_page_token (str):
415 If not empty, indicates that there may be more topics that
416 match the request; this value should be passed in a new
417 ``ListTopicsRequest``.
418 """
420 @property
421 def raw_page(self):
422 return self
424 topics: MutableSequence["Topic"] = proto.RepeatedField(
425 proto.MESSAGE,
426 number=1,
427 message="Topic",
428 )
429 next_page_token: str = proto.Field(
430 proto.STRING,
431 number=2,
432 )
435class ListTopicSubscriptionsRequest(proto.Message):
436 r"""Request for the ``ListTopicSubscriptions`` method.
438 Attributes:
439 topic (str):
440 Required. The name of the topic that subscriptions are
441 attached to. Format is
442 ``projects/{project}/topics/{topic}``.
443 page_size (int):
444 Maximum number of subscription names to
445 return.
446 page_token (str):
447 The value returned by the last
448 ``ListTopicSubscriptionsResponse``; indicates that this is a
449 continuation of a prior ``ListTopicSubscriptions`` call, and
450 that the system should return the next page of data.
451 """
453 topic: str = proto.Field(
454 proto.STRING,
455 number=1,
456 )
457 page_size: int = proto.Field(
458 proto.INT32,
459 number=2,
460 )
461 page_token: str = proto.Field(
462 proto.STRING,
463 number=3,
464 )
467class ListTopicSubscriptionsResponse(proto.Message):
468 r"""Response for the ``ListTopicSubscriptions`` method.
470 Attributes:
471 subscriptions (MutableSequence[str]):
472 The names of subscriptions attached to the
473 topic specified in the request.
474 next_page_token (str):
475 If not empty, indicates that there may be more subscriptions
476 that match the request; this value should be passed in a new
477 ``ListTopicSubscriptionsRequest`` to get more subscriptions.
478 """
480 @property
481 def raw_page(self):
482 return self
484 subscriptions: MutableSequence[str] = proto.RepeatedField(
485 proto.STRING,
486 number=1,
487 )
488 next_page_token: str = proto.Field(
489 proto.STRING,
490 number=2,
491 )
494class ListTopicSnapshotsRequest(proto.Message):
495 r"""Request for the ``ListTopicSnapshots`` method.
497 Attributes:
498 topic (str):
499 Required. The name of the topic that snapshots are attached
500 to. Format is ``projects/{project}/topics/{topic}``.
501 page_size (int):
502 Maximum number of snapshot names to return.
503 page_token (str):
504 The value returned by the last
505 ``ListTopicSnapshotsResponse``; indicates that this is a
506 continuation of a prior ``ListTopicSnapshots`` call, and
507 that the system should return the next page of data.
508 """
510 topic: str = proto.Field(
511 proto.STRING,
512 number=1,
513 )
514 page_size: int = proto.Field(
515 proto.INT32,
516 number=2,
517 )
518 page_token: str = proto.Field(
519 proto.STRING,
520 number=3,
521 )
524class ListTopicSnapshotsResponse(proto.Message):
525 r"""Response for the ``ListTopicSnapshots`` method.
527 Attributes:
528 snapshots (MutableSequence[str]):
529 The names of the snapshots that match the
530 request.
531 next_page_token (str):
532 If not empty, indicates that there may be more snapshots
533 that match the request; this value should be passed in a new
534 ``ListTopicSnapshotsRequest`` to get more snapshots.
535 """
537 @property
538 def raw_page(self):
539 return self
541 snapshots: MutableSequence[str] = proto.RepeatedField(
542 proto.STRING,
543 number=1,
544 )
545 next_page_token: str = proto.Field(
546 proto.STRING,
547 number=2,
548 )
551class DeleteTopicRequest(proto.Message):
552 r"""Request for the ``DeleteTopic`` method.
554 Attributes:
555 topic (str):
556 Required. Name of the topic to delete. Format is
557 ``projects/{project}/topics/{topic}``.
558 """
560 topic: str = proto.Field(
561 proto.STRING,
562 number=1,
563 )
566class DetachSubscriptionRequest(proto.Message):
567 r"""Request for the DetachSubscription method.
569 Attributes:
570 subscription (str):
571 Required. The subscription to detach. Format is
572 ``projects/{project}/subscriptions/{subscription}``.
573 """
575 subscription: str = proto.Field(
576 proto.STRING,
577 number=1,
578 )
581class DetachSubscriptionResponse(proto.Message):
582 r"""Response for the DetachSubscription method.
583 Reserved for future use.
585 """
588class Subscription(proto.Message):
589 r"""A subscription resource. If none of ``push_config``,
590 ``bigquery_config``, or ``cloud_storage_config`` is set, then the
591 subscriber will pull and ack messages using API methods. At most one
592 of these fields may be set.
594 Attributes:
595 name (str):
596 Required. The name of the subscription. It must have the
597 format
598 ``"projects/{project}/subscriptions/{subscription}"``.
599 ``{subscription}`` must start with a letter, and contain
600 only letters (``[A-Za-z]``), numbers (``[0-9]``), dashes
601 (``-``), underscores (``_``), periods (``.``), tildes
602 (``~``), plus (``+``) or percent signs (``%``). It must be
603 between 3 and 255 characters in length, and it must not
604 start with ``"goog"``.
605 topic (str):
606 Required. The name of the topic from which this subscription
607 is receiving messages. Format is
608 ``projects/{project}/topics/{topic}``. The value of this
609 field will be ``_deleted-topic_`` if the topic has been
610 deleted.
611 push_config (google.pubsub_v1.types.PushConfig):
612 If push delivery is used with this
613 subscription, this field is used to configure
614 it.
615 bigquery_config (google.pubsub_v1.types.BigQueryConfig):
616 If delivery to BigQuery is used with this
617 subscription, this field is used to configure
618 it.
619 cloud_storage_config (google.pubsub_v1.types.CloudStorageConfig):
620 If delivery to Google Cloud Storage is used
621 with this subscription, this field is used to
622 configure it.
623 ack_deadline_seconds (int):
624 The approximate amount of time (on a best-effort basis)
625 Pub/Sub waits for the subscriber to acknowledge receipt
626 before resending the message. In the interval after the
627 message is delivered and before it is acknowledged, it is
628 considered to be *outstanding*. During that time period, the
629 message will not be redelivered (on a best-effort basis).
631 For pull subscriptions, this value is used as the initial
632 value for the ack deadline. To override this value for a
633 given message, call ``ModifyAckDeadline`` with the
634 corresponding ``ack_id`` if using non-streaming pull or send
635 the ``ack_id`` in a ``StreamingModifyAckDeadlineRequest`` if
636 using streaming pull. The minimum custom deadline you can
637 specify is 10 seconds. The maximum custom deadline you can
638 specify is 600 seconds (10 minutes). If this parameter is 0,
639 a default value of 10 seconds is used.
641 For push delivery, this value is also used to set the
642 request timeout for the call to the push endpoint.
644 If the subscriber never acknowledges the message, the
645 Pub/Sub system will eventually redeliver the message.
646 retain_acked_messages (bool):
647 Indicates whether to retain acknowledged messages. If true,
648 then messages are not expunged from the subscription's
649 backlog, even if they are acknowledged, until they fall out
650 of the ``message_retention_duration`` window. This must be
651 true if you would like to [``Seek`` to a timestamp]
652 (https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
653 in the past to replay previously-acknowledged messages.
654 message_retention_duration (google.protobuf.duration_pb2.Duration):
655 How long to retain unacknowledged messages in the
656 subscription's backlog, from the moment a message is
657 published. If ``retain_acked_messages`` is true, then this
658 also configures the retention of acknowledged messages, and
659 thus configures how far back in time a ``Seek`` can be done.
660 Defaults to 7 days. Cannot be more than 7 days or less than
661 10 minutes.
662 labels (MutableMapping[str, str]):
663 See `Creating and managing
664 labels <https://cloud.google.com/pubsub/docs/labels>`__.
665 enable_message_ordering (bool):
666 If true, messages published with the same ``ordering_key``
667 in ``PubsubMessage`` will be delivered to the subscribers in
668 the order in which they are received by the Pub/Sub system.
669 Otherwise, they may be delivered in any order.
670 expiration_policy (google.pubsub_v1.types.ExpirationPolicy):
671 A policy that specifies the conditions for this
672 subscription's expiration. A subscription is considered
673 active as long as any connected subscriber is successfully
674 consuming messages from the subscription or is issuing
675 operations on the subscription. If ``expiration_policy`` is
676 not set, a *default policy* with ``ttl`` of 31 days will be
677 used. The minimum allowed value for
678 ``expiration_policy.ttl`` is 1 day. If ``expiration_policy``
679 is set, but ``expiration_policy.ttl`` is not set, the
680 subscription never expires.
681 filter (str):
682 An expression written in the Pub/Sub `filter
683 language <https://cloud.google.com/pubsub/docs/filtering>`__.
684 If non-empty, then only ``PubsubMessage``\ s whose
685 ``attributes`` field matches the filter are delivered on
686 this subscription. If empty, then no messages are filtered
687 out.
688 dead_letter_policy (google.pubsub_v1.types.DeadLetterPolicy):
689 A policy that specifies the conditions for dead lettering
690 messages in this subscription. If dead_letter_policy is not
691 set, dead lettering is disabled.
693 The Cloud Pub/Sub service account associated with this
694 subscriptions's parent project (i.e.,
695 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)
696 must have permission to Acknowledge() messages on this
697 subscription.
698 retry_policy (google.pubsub_v1.types.RetryPolicy):
699 A policy that specifies how Pub/Sub retries
700 message delivery for this subscription.
702 If not set, the default retry policy is applied.
703 This generally implies that messages will be
704 retried as soon as possible for healthy
705 subscribers. RetryPolicy will be triggered on
706 NACKs or acknowledgement deadline exceeded
707 events for a given message.
708 detached (bool):
709 Indicates whether the subscription is detached from its
710 topic. Detached subscriptions don't receive messages from
711 their topic and don't retain any backlog. ``Pull`` and
712 ``StreamingPull`` requests will return FAILED_PRECONDITION.
713 If the subscription is a push subscription, pushes to the
714 endpoint will not be made.
715 enable_exactly_once_delivery (bool):
716 If true, Pub/Sub provides the following guarantees for the
717 delivery of a message with a given value of ``message_id``
718 on this subscription:
720 - The message sent to a subscriber is guaranteed not to be
721 resent before the message's acknowledgement deadline
722 expires.
723 - An acknowledged message will not be resent to a
724 subscriber.
726 Note that subscribers may still receive multiple copies of a
727 message when ``enable_exactly_once_delivery`` is true if the
728 message was published multiple times by a publisher client.
729 These copies are considered distinct by Pub/Sub and have
730 distinct ``message_id`` values.
731 topic_message_retention_duration (google.protobuf.duration_pb2.Duration):
732 Output only. Indicates the minimum duration for which a
733 message is retained after it is published to the
734 subscription's topic. If this field is set, messages
735 published to the subscription's topic in the last
736 ``topic_message_retention_duration`` are always available to
737 subscribers. See the ``message_retention_duration`` field in
738 ``Topic``. This field is set only in responses from the
739 server; it is ignored if it is set in any requests.
740 state (google.pubsub_v1.types.Subscription.State):
741 Output only. An output-only field indicating
742 whether or not the subscription can receive
743 messages.
744 """
746 class State(proto.Enum):
747 r"""Possible states for a subscription.
749 Values:
750 STATE_UNSPECIFIED (0):
751 Default value. This value is unused.
752 ACTIVE (1):
753 The subscription can actively receive
754 messages
755 RESOURCE_ERROR (2):
756 The subscription cannot receive messages
757 because of an error with the resource to which
758 it pushes messages. See the more detailed error
759 state in the corresponding configuration.
760 """
761 STATE_UNSPECIFIED = 0
762 ACTIVE = 1
763 RESOURCE_ERROR = 2
765 name: str = proto.Field(
766 proto.STRING,
767 number=1,
768 )
769 topic: str = proto.Field(
770 proto.STRING,
771 number=2,
772 )
773 push_config: "PushConfig" = proto.Field(
774 proto.MESSAGE,
775 number=4,
776 message="PushConfig",
777 )
778 bigquery_config: "BigQueryConfig" = proto.Field(
779 proto.MESSAGE,
780 number=18,
781 message="BigQueryConfig",
782 )
783 cloud_storage_config: "CloudStorageConfig" = proto.Field(
784 proto.MESSAGE,
785 number=22,
786 message="CloudStorageConfig",
787 )
788 ack_deadline_seconds: int = proto.Field(
789 proto.INT32,
790 number=5,
791 )
792 retain_acked_messages: bool = proto.Field(
793 proto.BOOL,
794 number=7,
795 )
796 message_retention_duration: duration_pb2.Duration = proto.Field(
797 proto.MESSAGE,
798 number=8,
799 message=duration_pb2.Duration,
800 )
801 labels: MutableMapping[str, str] = proto.MapField(
802 proto.STRING,
803 proto.STRING,
804 number=9,
805 )
806 enable_message_ordering: bool = proto.Field(
807 proto.BOOL,
808 number=10,
809 )
810 expiration_policy: "ExpirationPolicy" = proto.Field(
811 proto.MESSAGE,
812 number=11,
813 message="ExpirationPolicy",
814 )
815 filter: str = proto.Field(
816 proto.STRING,
817 number=12,
818 )
819 dead_letter_policy: "DeadLetterPolicy" = proto.Field(
820 proto.MESSAGE,
821 number=13,
822 message="DeadLetterPolicy",
823 )
824 retry_policy: "RetryPolicy" = proto.Field(
825 proto.MESSAGE,
826 number=14,
827 message="RetryPolicy",
828 )
829 detached: bool = proto.Field(
830 proto.BOOL,
831 number=15,
832 )
833 enable_exactly_once_delivery: bool = proto.Field(
834 proto.BOOL,
835 number=16,
836 )
837 topic_message_retention_duration: duration_pb2.Duration = proto.Field(
838 proto.MESSAGE,
839 number=17,
840 message=duration_pb2.Duration,
841 )
842 state: State = proto.Field(
843 proto.ENUM,
844 number=19,
845 enum=State,
846 )
849class RetryPolicy(proto.Message):
850 r"""A policy that specifies how Cloud Pub/Sub retries message delivery.
852 Retry delay will be exponential based on provided minimum and
853 maximum backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
855 RetryPolicy will be triggered on NACKs or acknowledgement deadline
856 exceeded events for a given message.
858 Retry Policy is implemented on a best effort basis. At times, the
859 delay between consecutive deliveries may not match the
860 configuration. That is, delay can be more or less than configured
861 backoff.
863 Attributes:
864 minimum_backoff (google.protobuf.duration_pb2.Duration):
865 The minimum delay between consecutive
866 deliveries of a given message. Value should be
867 between 0 and 600 seconds. Defaults to 10
868 seconds.
869 maximum_backoff (google.protobuf.duration_pb2.Duration):
870 The maximum delay between consecutive
871 deliveries of a given message. Value should be
872 between 0 and 600 seconds. Defaults to 600
873 seconds.
874 """
876 minimum_backoff: duration_pb2.Duration = proto.Field(
877 proto.MESSAGE,
878 number=1,
879 message=duration_pb2.Duration,
880 )
881 maximum_backoff: duration_pb2.Duration = proto.Field(
882 proto.MESSAGE,
883 number=2,
884 message=duration_pb2.Duration,
885 )
888class DeadLetterPolicy(proto.Message):
889 r"""Dead lettering is done on a best effort basis. The same
890 message might be dead lettered multiple times.
892 If validation on any of the fields fails at subscription
893 creation/updation, the create/update subscription request will
894 fail.
896 Attributes:
897 dead_letter_topic (str):
898 The name of the topic to which dead letter messages should
899 be published. Format is
900 ``projects/{project}/topics/{topic}``.The Cloud Pub/Sub
901 service account associated with the enclosing subscription's
902 parent project (i.e.,
903 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)
904 must have permission to Publish() to this topic.
906 The operation will fail if the topic does not exist. Users
907 should ensure that there is a subscription attached to this
908 topic since messages published to a topic with no
909 subscriptions are lost.
910 max_delivery_attempts (int):
911 The maximum number of delivery attempts for any message. The
912 value must be between 5 and 100.
914 The number of delivery attempts is defined as 1 + (the sum
915 of number of NACKs and number of times the acknowledgement
916 deadline has been exceeded for the message).
918 A NACK is any call to ModifyAckDeadline with a 0 deadline.
919 Note that client libraries may automatically extend
920 ack_deadlines.
922 This field will be honored on a best effort basis.
924 If this parameter is 0, a default value of 5 is used.
925 """
927 dead_letter_topic: str = proto.Field(
928 proto.STRING,
929 number=1,
930 )
931 max_delivery_attempts: int = proto.Field(
932 proto.INT32,
933 number=2,
934 )
937class ExpirationPolicy(proto.Message):
938 r"""A policy that specifies the conditions for resource
939 expiration (i.e., automatic resource deletion).
941 Attributes:
942 ttl (google.protobuf.duration_pb2.Duration):
943 Specifies the "time-to-live" duration for an associated
944 resource. The resource expires if it is not active for a
945 period of ``ttl``. The definition of "activity" depends on
946 the type of the associated resource. The minimum and maximum
947 allowed values for ``ttl`` depend on the type of the
948 associated resource, as well. If ``ttl`` is not set, the
949 associated resource never expires.
950 """
952 ttl: duration_pb2.Duration = proto.Field(
953 proto.MESSAGE,
954 number=1,
955 message=duration_pb2.Duration,
956 )
959class PushConfig(proto.Message):
960 r"""Configuration for a push delivery endpoint.
962 This message has `oneof`_ fields (mutually exclusive fields).
963 For each oneof, at most one member field can be set at the same time.
964 Setting any member of the oneof automatically clears all other
965 members.
967 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
969 Attributes:
970 push_endpoint (str):
971 A URL locating the endpoint to which messages should be
972 pushed. For example, a Webhook endpoint might use
973 ``https://example.com/push``.
974 attributes (MutableMapping[str, str]):
975 Endpoint configuration attributes that can be used to
976 control different aspects of the message delivery.
978 The only currently supported attribute is
979 ``x-goog-version``, which you can use to change the format
980 of the pushed message. This attribute indicates the version
981 of the data expected by the endpoint. This controls the
982 shape of the pushed message (i.e., its fields and metadata).
984 If not present during the ``CreateSubscription`` call, it
985 will default to the version of the Pub/Sub API used to make
986 such call. If not present in a ``ModifyPushConfig`` call,
987 its value will not be changed. ``GetSubscription`` calls
988 will always return a valid version, even if the subscription
989 was created without this attribute.
991 The only supported values for the ``x-goog-version``
992 attribute are:
994 - ``v1beta1``: uses the push format defined in the v1beta1
995 Pub/Sub API.
996 - ``v1`` or ``v1beta2``: uses the push format defined in
997 the v1 Pub/Sub API.
999 For example: ``attributes { "x-goog-version": "v1" }``
1000 oidc_token (google.pubsub_v1.types.PushConfig.OidcToken):
1001 If specified, Pub/Sub will generate and attach an OIDC JWT
1002 token as an ``Authorization`` header in the HTTP request for
1003 every pushed message.
1005 This field is a member of `oneof`_ ``authentication_method``.
1006 pubsub_wrapper (google.pubsub_v1.types.PushConfig.PubsubWrapper):
1007 When set, the payload to the push endpoint is
1008 in the form of the JSON representation of a
1009 PubsubMessage
1010 (https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#pubsubmessage).
1012 This field is a member of `oneof`_ ``wrapper``.
1013 no_wrapper (google.pubsub_v1.types.PushConfig.NoWrapper):
1014 When set, the payload to the push endpoint is
1015 not wrapped.
1017 This field is a member of `oneof`_ ``wrapper``.
1018 """
1020 class OidcToken(proto.Message):
1021 r"""Contains information needed for generating an `OpenID Connect
1022 token <https://developers.google.com/identity/protocols/OpenIDConnect>`__.
1024 Attributes:
1025 service_account_email (str):
1026 `Service account
1027 email <https://cloud.google.com/iam/docs/service-accounts>`__
1028 used for generating the OIDC token. For more information on
1029 setting up authentication, see `Push
1030 subscriptions <https://cloud.google.com/pubsub/docs/push>`__.
1031 audience (str):
1032 Audience to be used when generating OIDC
1033 token. The audience claim identifies the
1034 recipients that the JWT is intended for. The
1035 audience value is a single case-sensitive
1036 string. Having multiple values (array) for the
1037 audience field is not supported. More info about
1038 the OIDC JWT token audience here:
1039 https://tools.ietf.org/html/rfc7519#section-4.1.3
1040 Note: if not specified, the Push endpoint URL
1041 will be used.
1042 """
1044 service_account_email: str = proto.Field(
1045 proto.STRING,
1046 number=1,
1047 )
1048 audience: str = proto.Field(
1049 proto.STRING,
1050 number=2,
1051 )
1053 class PubsubWrapper(proto.Message):
1054 r"""The payload to the push endpoint is in the form of the JSON
1055 representation of a PubsubMessage
1056 (https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#pubsubmessage).
1058 """
1060 class NoWrapper(proto.Message):
1061 r"""Sets the ``data`` field as the HTTP body for delivery.
1063 Attributes:
1064 write_metadata (bool):
1065 When true, writes the Pub/Sub message metadata to
1066 ``x-goog-pubsub-<KEY>:<VAL>`` headers of the HTTP request.
1067 Writes the Pub/Sub message attributes to ``<KEY>:<VAL>``
1068 headers of the HTTP request.
1069 """
1071 write_metadata: bool = proto.Field(
1072 proto.BOOL,
1073 number=1,
1074 )
1076 push_endpoint: str = proto.Field(
1077 proto.STRING,
1078 number=1,
1079 )
1080 attributes: MutableMapping[str, str] = proto.MapField(
1081 proto.STRING,
1082 proto.STRING,
1083 number=2,
1084 )
1085 oidc_token: OidcToken = proto.Field(
1086 proto.MESSAGE,
1087 number=3,
1088 oneof="authentication_method",
1089 message=OidcToken,
1090 )
1091 pubsub_wrapper: PubsubWrapper = proto.Field(
1092 proto.MESSAGE,
1093 number=4,
1094 oneof="wrapper",
1095 message=PubsubWrapper,
1096 )
1097 no_wrapper: NoWrapper = proto.Field(
1098 proto.MESSAGE,
1099 number=5,
1100 oneof="wrapper",
1101 message=NoWrapper,
1102 )
1105class BigQueryConfig(proto.Message):
1106 r"""Configuration for a BigQuery subscription.
1108 Attributes:
1109 table (str):
1110 The name of the table to which to write data,
1111 of the form {projectId}.{datasetId}.{tableId}
1112 use_topic_schema (bool):
1113 When true, use the topic's schema as the
1114 columns to write to in BigQuery, if it exists.
1115 write_metadata (bool):
1116 When true, write the subscription name, message_id,
1117 publish_time, attributes, and ordering_key to additional
1118 columns in the table. The subscription name, message_id, and
1119 publish_time fields are put in their own columns while all
1120 other message properties (other than data) are written to a
1121 JSON object in the attributes column.
1122 drop_unknown_fields (bool):
1123 When true and use_topic_schema is true, any fields that are
1124 a part of the topic schema that are not part of the BigQuery
1125 table schema are dropped when writing to BigQuery.
1126 Otherwise, the schemas must be kept in sync and any messages
1127 with extra fields are not written and remain in the
1128 subscription's backlog.
1129 state (google.pubsub_v1.types.BigQueryConfig.State):
1130 Output only. An output-only field that
1131 indicates whether or not the subscription can
1132 receive messages.
1133 """
1135 class State(proto.Enum):
1136 r"""Possible states for a BigQuery subscription.
1138 Values:
1139 STATE_UNSPECIFIED (0):
1140 Default value. This value is unused.
1141 ACTIVE (1):
1142 The subscription can actively send messages
1143 to BigQuery
1144 PERMISSION_DENIED (2):
1145 Cannot write to the BigQuery table because of permission
1146 denied errors. This can happen if
1148 - Pub/Sub SA has not been granted the `appropriate BigQuery
1149 IAM
1150 permissions <https://cloud.google.com/pubsub/docs/create-subscription#assign_bigquery_service_account>`__
1151 - bigquery.googleapis.com API is not enabled for the
1152 project
1153 (`instructions <https://cloud.google.com/service-usage/docs/enable-disable>`__)
1154 NOT_FOUND (3):
1155 Cannot write to the BigQuery table because it
1156 does not exist.
1157 SCHEMA_MISMATCH (4):
1158 Cannot write to the BigQuery table due to a
1159 schema mismatch.
1160 """
1161 STATE_UNSPECIFIED = 0
1162 ACTIVE = 1
1163 PERMISSION_DENIED = 2
1164 NOT_FOUND = 3
1165 SCHEMA_MISMATCH = 4
1167 table: str = proto.Field(
1168 proto.STRING,
1169 number=1,
1170 )
1171 use_topic_schema: bool = proto.Field(
1172 proto.BOOL,
1173 number=2,
1174 )
1175 write_metadata: bool = proto.Field(
1176 proto.BOOL,
1177 number=3,
1178 )
1179 drop_unknown_fields: bool = proto.Field(
1180 proto.BOOL,
1181 number=4,
1182 )
1183 state: State = proto.Field(
1184 proto.ENUM,
1185 number=5,
1186 enum=State,
1187 )
1190class CloudStorageConfig(proto.Message):
1191 r"""Configuration for a Cloud Storage subscription.
1193 This message has `oneof`_ fields (mutually exclusive fields).
1194 For each oneof, at most one member field can be set at the same time.
1195 Setting any member of the oneof automatically clears all other
1196 members.
1198 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1200 Attributes:
1201 bucket (str):
1202 Required. User-provided name for the Cloud Storage bucket.
1203 The bucket must be created by the user. The bucket name must
1204 be without any prefix like "gs://". See the [bucket naming
1205 requirements]
1206 (https://cloud.google.com/storage/docs/buckets#naming).
1207 filename_prefix (str):
1208 User-provided prefix for Cloud Storage filename. See the
1209 `object naming
1210 requirements <https://cloud.google.com/storage/docs/objects#naming>`__.
1211 filename_suffix (str):
1212 User-provided suffix for Cloud Storage filename. See the
1213 `object naming
1214 requirements <https://cloud.google.com/storage/docs/objects#naming>`__.
1215 text_config (google.pubsub_v1.types.CloudStorageConfig.TextConfig):
1216 If set, message data will be written to Cloud
1217 Storage in text format.
1219 This field is a member of `oneof`_ ``output_format``.
1220 avro_config (google.pubsub_v1.types.CloudStorageConfig.AvroConfig):
1221 If set, message data will be written to Cloud
1222 Storage in Avro format.
1224 This field is a member of `oneof`_ ``output_format``.
1225 max_duration (google.protobuf.duration_pb2.Duration):
1226 The maximum duration that can elapse before a
1227 new Cloud Storage file is created. Min 1 minute,
1228 max 10 minutes, default 5 minutes. May not
1229 exceed the subscription's acknowledgement
1230 deadline.
1231 max_bytes (int):
1232 The maximum bytes that can be written to a Cloud Storage
1233 file before a new file is created. Min 1 KB, max 10 GiB. The
1234 max_bytes limit may be exceeded in cases where messages are
1235 larger than the limit.
1236 state (google.pubsub_v1.types.CloudStorageConfig.State):
1237 Output only. An output-only field that
1238 indicates whether or not the subscription can
1239 receive messages.
1240 """
1242 class State(proto.Enum):
1243 r"""Possible states for a Cloud Storage subscription.
1245 Values:
1246 STATE_UNSPECIFIED (0):
1247 Default value. This value is unused.
1248 ACTIVE (1):
1249 The subscription can actively send messages
1250 to Cloud Storage.
1251 PERMISSION_DENIED (2):
1252 Cannot write to the Cloud Storage bucket
1253 because of permission denied errors.
1254 NOT_FOUND (3):
1255 Cannot write to the Cloud Storage bucket
1256 because it does not exist.
1257 """
1258 STATE_UNSPECIFIED = 0
1259 ACTIVE = 1
1260 PERMISSION_DENIED = 2
1261 NOT_FOUND = 3
1263 class TextConfig(proto.Message):
1264 r"""Configuration for writing message data in text format.
1265 Message payloads will be written to files as raw text, separated
1266 by a newline.
1268 """
1270 class AvroConfig(proto.Message):
1271 r"""Configuration for writing message data in Avro format.
1272 Message payloads and metadata will be written to files as an
1273 Avro binary.
1275 Attributes:
1276 write_metadata (bool):
1277 When true, write the subscription name, message_id,
1278 publish_time, attributes, and ordering_key as additional
1279 fields in the output.
1280 """
1282 write_metadata: bool = proto.Field(
1283 proto.BOOL,
1284 number=1,
1285 )
1287 bucket: str = proto.Field(
1288 proto.STRING,
1289 number=1,
1290 )
1291 filename_prefix: str = proto.Field(
1292 proto.STRING,
1293 number=2,
1294 )
1295 filename_suffix: str = proto.Field(
1296 proto.STRING,
1297 number=3,
1298 )
1299 text_config: TextConfig = proto.Field(
1300 proto.MESSAGE,
1301 number=4,
1302 oneof="output_format",
1303 message=TextConfig,
1304 )
1305 avro_config: AvroConfig = proto.Field(
1306 proto.MESSAGE,
1307 number=5,
1308 oneof="output_format",
1309 message=AvroConfig,
1310 )
1311 max_duration: duration_pb2.Duration = proto.Field(
1312 proto.MESSAGE,
1313 number=6,
1314 message=duration_pb2.Duration,
1315 )
1316 max_bytes: int = proto.Field(
1317 proto.INT64,
1318 number=7,
1319 )
1320 state: State = proto.Field(
1321 proto.ENUM,
1322 number=9,
1323 enum=State,
1324 )
1327class ReceivedMessage(proto.Message):
1328 r"""A message and its corresponding acknowledgment ID.
1330 Attributes:
1331 ack_id (str):
1332 This ID can be used to acknowledge the
1333 received message.
1334 message (google.pubsub_v1.types.PubsubMessage):
1335 The message.
1336 delivery_attempt (int):
1337 The approximate number of times that Cloud Pub/Sub has
1338 attempted to deliver the associated message to a subscriber.
1340 More precisely, this is 1 + (number of NACKs) + (number of
1341 ack_deadline exceeds) for this message.
1343 A NACK is any call to ModifyAckDeadline with a 0 deadline.
1344 An ack_deadline exceeds event is whenever a message is not
1345 acknowledged within ack_deadline. Note that ack_deadline is
1346 initially Subscription.ackDeadlineSeconds, but may get
1347 extended automatically by the client library.
1349 Upon the first delivery of a given message,
1350 ``delivery_attempt`` will have a value of 1. The value is
1351 calculated at best effort and is approximate.
1353 If a DeadLetterPolicy is not set on the subscription, this
1354 will be 0.
1355 """
1357 ack_id: str = proto.Field(
1358 proto.STRING,
1359 number=1,
1360 )
1361 message: "PubsubMessage" = proto.Field(
1362 proto.MESSAGE,
1363 number=2,
1364 message="PubsubMessage",
1365 )
1366 delivery_attempt: int = proto.Field(
1367 proto.INT32,
1368 number=3,
1369 )
1372class GetSubscriptionRequest(proto.Message):
1373 r"""Request for the GetSubscription method.
1375 Attributes:
1376 subscription (str):
1377 Required. The name of the subscription to get. Format is
1378 ``projects/{project}/subscriptions/{sub}``.
1379 """
1381 subscription: str = proto.Field(
1382 proto.STRING,
1383 number=1,
1384 )
1387class UpdateSubscriptionRequest(proto.Message):
1388 r"""Request for the UpdateSubscription method.
1390 Attributes:
1391 subscription (google.pubsub_v1.types.Subscription):
1392 Required. The updated subscription object.
1393 update_mask (google.protobuf.field_mask_pb2.FieldMask):
1394 Required. Indicates which fields in the
1395 provided subscription to update. Must be
1396 specified and non-empty.
1397 """
1399 subscription: "Subscription" = proto.Field(
1400 proto.MESSAGE,
1401 number=1,
1402 message="Subscription",
1403 )
1404 update_mask: field_mask_pb2.FieldMask = proto.Field(
1405 proto.MESSAGE,
1406 number=2,
1407 message=field_mask_pb2.FieldMask,
1408 )
1411class ListSubscriptionsRequest(proto.Message):
1412 r"""Request for the ``ListSubscriptions`` method.
1414 Attributes:
1415 project (str):
1416 Required. The name of the project in which to list
1417 subscriptions. Format is ``projects/{project-id}``.
1418 page_size (int):
1419 Maximum number of subscriptions to return.
1420 page_token (str):
1421 The value returned by the last
1422 ``ListSubscriptionsResponse``; indicates that this is a
1423 continuation of a prior ``ListSubscriptions`` call, and that
1424 the system should return the next page of data.
1425 """
1427 project: str = proto.Field(
1428 proto.STRING,
1429 number=1,
1430 )
1431 page_size: int = proto.Field(
1432 proto.INT32,
1433 number=2,
1434 )
1435 page_token: str = proto.Field(
1436 proto.STRING,
1437 number=3,
1438 )
1441class ListSubscriptionsResponse(proto.Message):
1442 r"""Response for the ``ListSubscriptions`` method.
1444 Attributes:
1445 subscriptions (MutableSequence[google.pubsub_v1.types.Subscription]):
1446 The subscriptions that match the request.
1447 next_page_token (str):
1448 If not empty, indicates that there may be more subscriptions
1449 that match the request; this value should be passed in a new
1450 ``ListSubscriptionsRequest`` to get more subscriptions.
1451 """
1453 @property
1454 def raw_page(self):
1455 return self
1457 subscriptions: MutableSequence["Subscription"] = proto.RepeatedField(
1458 proto.MESSAGE,
1459 number=1,
1460 message="Subscription",
1461 )
1462 next_page_token: str = proto.Field(
1463 proto.STRING,
1464 number=2,
1465 )
1468class DeleteSubscriptionRequest(proto.Message):
1469 r"""Request for the DeleteSubscription method.
1471 Attributes:
1472 subscription (str):
1473 Required. The subscription to delete. Format is
1474 ``projects/{project}/subscriptions/{sub}``.
1475 """
1477 subscription: str = proto.Field(
1478 proto.STRING,
1479 number=1,
1480 )
1483class ModifyPushConfigRequest(proto.Message):
1484 r"""Request for the ModifyPushConfig method.
1486 Attributes:
1487 subscription (str):
1488 Required. The name of the subscription. Format is
1489 ``projects/{project}/subscriptions/{sub}``.
1490 push_config (google.pubsub_v1.types.PushConfig):
1491 Required. The push configuration for future deliveries.
1493 An empty ``pushConfig`` indicates that the Pub/Sub system
1494 should stop pushing messages from the given subscription and
1495 allow messages to be pulled and acknowledged - effectively
1496 pausing the subscription if ``Pull`` or ``StreamingPull`` is
1497 not called.
1498 """
1500 subscription: str = proto.Field(
1501 proto.STRING,
1502 number=1,
1503 )
1504 push_config: "PushConfig" = proto.Field(
1505 proto.MESSAGE,
1506 number=2,
1507 message="PushConfig",
1508 )
1511class PullRequest(proto.Message):
1512 r"""Request for the ``Pull`` method.
1514 Attributes:
1515 subscription (str):
1516 Required. The subscription from which messages should be
1517 pulled. Format is
1518 ``projects/{project}/subscriptions/{sub}``.
1519 return_immediately (bool):
1520 Optional. If this field set to true, the system will respond
1521 immediately even if it there are no messages available to
1522 return in the ``Pull`` response. Otherwise, the system may
1523 wait (for a bounded amount of time) until at least one
1524 message is available, rather than returning no messages.
1525 Warning: setting this field to ``true`` is discouraged
1526 because it adversely impacts the performance of ``Pull``
1527 operations. We recommend that users do not set this field.
1528 max_messages (int):
1529 Required. The maximum number of messages to
1530 return for this request. Must be a positive
1531 integer. The Pub/Sub system may return fewer
1532 than the number specified.
1533 """
1535 subscription: str = proto.Field(
1536 proto.STRING,
1537 number=1,
1538 )
1539 return_immediately: bool = proto.Field(
1540 proto.BOOL,
1541 number=2,
1542 )
1543 max_messages: int = proto.Field(
1544 proto.INT32,
1545 number=3,
1546 )
1549class PullResponse(proto.Message):
1550 r"""Response for the ``Pull`` method.
1552 Attributes:
1553 received_messages (MutableSequence[google.pubsub_v1.types.ReceivedMessage]):
1554 Received Pub/Sub messages. The list will be empty if there
1555 are no more messages available in the backlog, or if no
1556 messages could be returned before the request timeout. For
1557 JSON, the response can be entirely empty. The Pub/Sub system
1558 may return fewer than the ``maxMessages`` requested even if
1559 there are more messages available in the backlog.
1560 """
1562 received_messages: MutableSequence["ReceivedMessage"] = proto.RepeatedField(
1563 proto.MESSAGE,
1564 number=1,
1565 message="ReceivedMessage",
1566 )
1569class ModifyAckDeadlineRequest(proto.Message):
1570 r"""Request for the ModifyAckDeadline method.
1572 Attributes:
1573 subscription (str):
1574 Required. The name of the subscription. Format is
1575 ``projects/{project}/subscriptions/{sub}``.
1576 ack_ids (MutableSequence[str]):
1577 Required. List of acknowledgment IDs.
1578 ack_deadline_seconds (int):
1579 Required. The new ack deadline with respect to the time this
1580 request was sent to the Pub/Sub system. For example, if the
1581 value is 10, the new ack deadline will expire 10 seconds
1582 after the ``ModifyAckDeadline`` call was made. Specifying
1583 zero might immediately make the message available for
1584 delivery to another subscriber client. This typically
1585 results in an increase in the rate of message redeliveries
1586 (that is, duplicates). The minimum deadline you can specify
1587 is 0 seconds. The maximum deadline you can specify is 600
1588 seconds (10 minutes).
1589 """
1591 subscription: str = proto.Field(
1592 proto.STRING,
1593 number=1,
1594 )
1595 ack_ids: MutableSequence[str] = proto.RepeatedField(
1596 proto.STRING,
1597 number=4,
1598 )
1599 ack_deadline_seconds: int = proto.Field(
1600 proto.INT32,
1601 number=3,
1602 )
1605class AcknowledgeRequest(proto.Message):
1606 r"""Request for the Acknowledge method.
1608 Attributes:
1609 subscription (str):
1610 Required. The subscription whose message is being
1611 acknowledged. Format is
1612 ``projects/{project}/subscriptions/{sub}``.
1613 ack_ids (MutableSequence[str]):
1614 Required. The acknowledgment ID for the messages being
1615 acknowledged that was returned by the Pub/Sub system in the
1616 ``Pull`` response. Must not be empty.
1617 """
1619 subscription: str = proto.Field(
1620 proto.STRING,
1621 number=1,
1622 )
1623 ack_ids: MutableSequence[str] = proto.RepeatedField(
1624 proto.STRING,
1625 number=2,
1626 )
1629class StreamingPullRequest(proto.Message):
1630 r"""Request for the ``StreamingPull`` streaming RPC method. This request
1631 is used to establish the initial stream as well as to stream
1632 acknowledgements and ack deadline modifications from the client to
1633 the server.
1635 Attributes:
1636 subscription (str):
1637 Required. The subscription for which to initialize the new
1638 stream. This must be provided in the first request on the
1639 stream, and must not be set in subsequent requests from
1640 client to server. Format is
1641 ``projects/{project}/subscriptions/{sub}``.
1642 ack_ids (MutableSequence[str]):
1643 List of acknowledgement IDs for acknowledging previously
1644 received messages (received on this stream or a different
1645 stream). If an ack ID has expired, the corresponding message
1646 may be redelivered later. Acknowledging a message more than
1647 once will not result in an error. If the acknowledgement ID
1648 is malformed, the stream will be aborted with status
1649 ``INVALID_ARGUMENT``.
1650 modify_deadline_seconds (MutableSequence[int]):
1651 The list of new ack deadlines for the IDs listed in
1652 ``modify_deadline_ack_ids``. The size of this list must be
1653 the same as the size of ``modify_deadline_ack_ids``. If it
1654 differs the stream will be aborted with
1655 ``INVALID_ARGUMENT``. Each element in this list is applied
1656 to the element in the same position in
1657 ``modify_deadline_ack_ids``. The new ack deadline is with
1658 respect to the time this request was sent to the Pub/Sub
1659 system. Must be >= 0. For example, if the value is 10, the
1660 new ack deadline will expire 10 seconds after this request
1661 is received. If the value is 0, the message is immediately
1662 made available for another streaming or non-streaming pull
1663 request. If the value is < 0 (an error), the stream will be
1664 aborted with status ``INVALID_ARGUMENT``.
1665 modify_deadline_ack_ids (MutableSequence[str]):
1666 List of acknowledgement IDs whose deadline will be modified
1667 based on the corresponding element in
1668 ``modify_deadline_seconds``. This field can be used to
1669 indicate that more time is needed to process a message by
1670 the subscriber, or to make the message available for
1671 redelivery if the processing was interrupted.
1672 stream_ack_deadline_seconds (int):
1673 Required. The ack deadline to use for the
1674 stream. This must be provided in the first
1675 request on the stream, but it can also be
1676 updated on subsequent requests from client to
1677 server. The minimum deadline you can specify is
1678 10 seconds. The maximum deadline you can specify
1679 is 600 seconds (10 minutes).
1680 client_id (str):
1681 A unique identifier that is used to distinguish client
1682 instances from each other. Only needs to be provided on the
1683 initial request. When a stream disconnects and reconnects
1684 for the same stream, the client_id should be set to the same
1685 value so that state associated with the old stream can be
1686 transferred to the new stream. The same client_id should not
1687 be used for different client instances.
1688 max_outstanding_messages (int):
1689 Flow control settings for the maximum number of outstanding
1690 messages. When there are ``max_outstanding_messages`` or
1691 more currently sent to the streaming pull client that have
1692 not yet been acked or nacked, the server stops sending more
1693 messages. The sending of messages resumes once the number of
1694 outstanding messages is less than this value. If the value
1695 is <= 0, there is no limit to the number of outstanding
1696 messages. This property can only be set on the initial
1697 StreamingPullRequest. If it is set on a subsequent request,
1698 the stream will be aborted with status ``INVALID_ARGUMENT``.
1699 max_outstanding_bytes (int):
1700 Flow control settings for the maximum number of outstanding
1701 bytes. When there are ``max_outstanding_bytes`` or more
1702 worth of messages currently sent to the streaming pull
1703 client that have not yet been acked or nacked, the server
1704 will stop sending more messages. The sending of messages
1705 resumes once the number of outstanding bytes is less than
1706 this value. If the value is <= 0, there is no limit to the
1707 number of outstanding bytes. This property can only be set
1708 on the initial StreamingPullRequest. If it is set on a
1709 subsequent request, the stream will be aborted with status
1710 ``INVALID_ARGUMENT``.
1711 """
1713 subscription: str = proto.Field(
1714 proto.STRING,
1715 number=1,
1716 )
1717 ack_ids: MutableSequence[str] = proto.RepeatedField(
1718 proto.STRING,
1719 number=2,
1720 )
1721 modify_deadline_seconds: MutableSequence[int] = proto.RepeatedField(
1722 proto.INT32,
1723 number=3,
1724 )
1725 modify_deadline_ack_ids: MutableSequence[str] = proto.RepeatedField(
1726 proto.STRING,
1727 number=4,
1728 )
1729 stream_ack_deadline_seconds: int = proto.Field(
1730 proto.INT32,
1731 number=5,
1732 )
1733 client_id: str = proto.Field(
1734 proto.STRING,
1735 number=6,
1736 )
1737 max_outstanding_messages: int = proto.Field(
1738 proto.INT64,
1739 number=7,
1740 )
1741 max_outstanding_bytes: int = proto.Field(
1742 proto.INT64,
1743 number=8,
1744 )
1747class StreamingPullResponse(proto.Message):
1748 r"""Response for the ``StreamingPull`` method. This response is used to
1749 stream messages from the server to the client.
1751 Attributes:
1752 received_messages (MutableSequence[google.pubsub_v1.types.ReceivedMessage]):
1753 Received Pub/Sub messages. This will not be
1754 empty.
1755 acknowledge_confirmation (google.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation):
1756 This field will only be set if
1757 ``enable_exactly_once_delivery`` is set to ``true``.
1758 modify_ack_deadline_confirmation (google.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation):
1759 This field will only be set if
1760 ``enable_exactly_once_delivery`` is set to ``true``.
1761 subscription_properties (google.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties):
1762 Properties associated with this subscription.
1763 """
1765 class AcknowledgeConfirmation(proto.Message):
1766 r"""Acknowledgement IDs sent in one or more previous requests to
1767 acknowledge a previously received message.
1769 Attributes:
1770 ack_ids (MutableSequence[str]):
1771 Successfully processed acknowledgement IDs.
1772 invalid_ack_ids (MutableSequence[str]):
1773 List of acknowledgement IDs that were
1774 malformed or whose acknowledgement deadline has
1775 expired.
1776 unordered_ack_ids (MutableSequence[str]):
1777 List of acknowledgement IDs that were out of
1778 order.
1779 temporary_failed_ack_ids (MutableSequence[str]):
1780 List of acknowledgement IDs that failed
1781 processing with temporary issues.
1782 """
1784 ack_ids: MutableSequence[str] = proto.RepeatedField(
1785 proto.STRING,
1786 number=1,
1787 )
1788 invalid_ack_ids: MutableSequence[str] = proto.RepeatedField(
1789 proto.STRING,
1790 number=2,
1791 )
1792 unordered_ack_ids: MutableSequence[str] = proto.RepeatedField(
1793 proto.STRING,
1794 number=3,
1795 )
1796 temporary_failed_ack_ids: MutableSequence[str] = proto.RepeatedField(
1797 proto.STRING,
1798 number=4,
1799 )
1801 class ModifyAckDeadlineConfirmation(proto.Message):
1802 r"""Acknowledgement IDs sent in one or more previous requests to
1803 modify the deadline for a specific message.
1805 Attributes:
1806 ack_ids (MutableSequence[str]):
1807 Successfully processed acknowledgement IDs.
1808 invalid_ack_ids (MutableSequence[str]):
1809 List of acknowledgement IDs that were
1810 malformed or whose acknowledgement deadline has
1811 expired.
1812 temporary_failed_ack_ids (MutableSequence[str]):
1813 List of acknowledgement IDs that failed
1814 processing with temporary issues.
1815 """
1817 ack_ids: MutableSequence[str] = proto.RepeatedField(
1818 proto.STRING,
1819 number=1,
1820 )
1821 invalid_ack_ids: MutableSequence[str] = proto.RepeatedField(
1822 proto.STRING,
1823 number=2,
1824 )
1825 temporary_failed_ack_ids: MutableSequence[str] = proto.RepeatedField(
1826 proto.STRING,
1827 number=3,
1828 )
1830 class SubscriptionProperties(proto.Message):
1831 r"""Subscription properties sent as part of the response.
1833 Attributes:
1834 exactly_once_delivery_enabled (bool):
1835 True iff exactly once delivery is enabled for
1836 this subscription.
1837 message_ordering_enabled (bool):
1838 True iff message ordering is enabled for this
1839 subscription.
1840 """
1842 exactly_once_delivery_enabled: bool = proto.Field(
1843 proto.BOOL,
1844 number=1,
1845 )
1846 message_ordering_enabled: bool = proto.Field(
1847 proto.BOOL,
1848 number=2,
1849 )
1851 received_messages: MutableSequence["ReceivedMessage"] = proto.RepeatedField(
1852 proto.MESSAGE,
1853 number=1,
1854 message="ReceivedMessage",
1855 )
1856 acknowledge_confirmation: AcknowledgeConfirmation = proto.Field(
1857 proto.MESSAGE,
1858 number=5,
1859 message=AcknowledgeConfirmation,
1860 )
1861 modify_ack_deadline_confirmation: ModifyAckDeadlineConfirmation = proto.Field(
1862 proto.MESSAGE,
1863 number=3,
1864 message=ModifyAckDeadlineConfirmation,
1865 )
1866 subscription_properties: SubscriptionProperties = proto.Field(
1867 proto.MESSAGE,
1868 number=4,
1869 message=SubscriptionProperties,
1870 )
1873class CreateSnapshotRequest(proto.Message):
1874 r"""Request for the ``CreateSnapshot`` method.
1876 Attributes:
1877 name (str):
1878 Required. User-provided name for this snapshot. If the name
1879 is not provided in the request, the server will assign a
1880 random name for this snapshot on the same project as the
1881 subscription. Note that for REST API requests, you must
1882 specify a name. See the `resource name
1883 rules <https://cloud.google.com/pubsub/docs/admin#resource_names>`__.
1884 Format is ``projects/{project}/snapshots/{snap}``.
1885 subscription (str):
1886 Required. The subscription whose backlog the snapshot
1887 retains. Specifically, the created snapshot is guaranteed to
1888 retain: (a) The existing backlog on the subscription. More
1889 precisely, this is defined as the messages in the
1890 subscription's backlog that are unacknowledged upon the
1891 successful completion of the ``CreateSnapshot`` request; as
1892 well as: (b) Any messages published to the subscription's
1893 topic following the successful completion of the
1894 CreateSnapshot request. Format is
1895 ``projects/{project}/subscriptions/{sub}``.
1896 labels (MutableMapping[str, str]):
1897 See `Creating and managing
1898 labels <https://cloud.google.com/pubsub/docs/labels>`__.
1899 """
1901 name: str = proto.Field(
1902 proto.STRING,
1903 number=1,
1904 )
1905 subscription: str = proto.Field(
1906 proto.STRING,
1907 number=2,
1908 )
1909 labels: MutableMapping[str, str] = proto.MapField(
1910 proto.STRING,
1911 proto.STRING,
1912 number=3,
1913 )
1916class UpdateSnapshotRequest(proto.Message):
1917 r"""Request for the UpdateSnapshot method.
1919 Attributes:
1920 snapshot (google.pubsub_v1.types.Snapshot):
1921 Required. The updated snapshot object.
1922 update_mask (google.protobuf.field_mask_pb2.FieldMask):
1923 Required. Indicates which fields in the
1924 provided snapshot to update. Must be specified
1925 and non-empty.
1926 """
1928 snapshot: "Snapshot" = proto.Field(
1929 proto.MESSAGE,
1930 number=1,
1931 message="Snapshot",
1932 )
1933 update_mask: field_mask_pb2.FieldMask = proto.Field(
1934 proto.MESSAGE,
1935 number=2,
1936 message=field_mask_pb2.FieldMask,
1937 )
1940class Snapshot(proto.Message):
1941 r"""A snapshot resource. Snapshots are used in
1942 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__
1943 operations, which allow you to manage message acknowledgments in
1944 bulk. That is, you can set the acknowledgment state of messages in
1945 an existing subscription to the state captured by a snapshot.
1947 Attributes:
1948 name (str):
1949 The name of the snapshot.
1950 topic (str):
1951 The name of the topic from which this
1952 snapshot is retaining messages.
1953 expire_time (google.protobuf.timestamp_pb2.Timestamp):
1954 The snapshot is guaranteed to exist up until this time. A
1955 newly-created snapshot expires no later than 7 days from the
1956 time of its creation. Its exact lifetime is determined at
1957 creation by the existing backlog in the source subscription.
1958 Specifically, the lifetime of the snapshot is
1959 ``7 days - (age of oldest unacked message in the subscription)``.
1960 For example, consider a subscription whose oldest unacked
1961 message is 3 days old. If a snapshot is created from this
1962 subscription, the snapshot -- which will always capture this
1963 3-day-old backlog as long as the snapshot exists -- will
1964 expire in 4 days. The service will refuse to create a
1965 snapshot that would expire in less than 1 hour after
1966 creation.
1967 labels (MutableMapping[str, str]):
1968 See [Creating and managing labels]
1969 (https://cloud.google.com/pubsub/docs/labels).
1970 """
1972 name: str = proto.Field(
1973 proto.STRING,
1974 number=1,
1975 )
1976 topic: str = proto.Field(
1977 proto.STRING,
1978 number=2,
1979 )
1980 expire_time: timestamp_pb2.Timestamp = proto.Field(
1981 proto.MESSAGE,
1982 number=3,
1983 message=timestamp_pb2.Timestamp,
1984 )
1985 labels: MutableMapping[str, str] = proto.MapField(
1986 proto.STRING,
1987 proto.STRING,
1988 number=4,
1989 )
1992class GetSnapshotRequest(proto.Message):
1993 r"""Request for the GetSnapshot method.
1995 Attributes:
1996 snapshot (str):
1997 Required. The name of the snapshot to get. Format is
1998 ``projects/{project}/snapshots/{snap}``.
1999 """
2001 snapshot: str = proto.Field(
2002 proto.STRING,
2003 number=1,
2004 )
2007class ListSnapshotsRequest(proto.Message):
2008 r"""Request for the ``ListSnapshots`` method.
2010 Attributes:
2011 project (str):
2012 Required. The name of the project in which to list
2013 snapshots. Format is ``projects/{project-id}``.
2014 page_size (int):
2015 Maximum number of snapshots to return.
2016 page_token (str):
2017 The value returned by the last ``ListSnapshotsResponse``;
2018 indicates that this is a continuation of a prior
2019 ``ListSnapshots`` call, and that the system should return
2020 the next page of data.
2021 """
2023 project: str = proto.Field(
2024 proto.STRING,
2025 number=1,
2026 )
2027 page_size: int = proto.Field(
2028 proto.INT32,
2029 number=2,
2030 )
2031 page_token: str = proto.Field(
2032 proto.STRING,
2033 number=3,
2034 )
2037class ListSnapshotsResponse(proto.Message):
2038 r"""Response for the ``ListSnapshots`` method.
2040 Attributes:
2041 snapshots (MutableSequence[google.pubsub_v1.types.Snapshot]):
2042 The resulting snapshots.
2043 next_page_token (str):
2044 If not empty, indicates that there may be more snapshot that
2045 match the request; this value should be passed in a new
2046 ``ListSnapshotsRequest``.
2047 """
2049 @property
2050 def raw_page(self):
2051 return self
2053 snapshots: MutableSequence["Snapshot"] = proto.RepeatedField(
2054 proto.MESSAGE,
2055 number=1,
2056 message="Snapshot",
2057 )
2058 next_page_token: str = proto.Field(
2059 proto.STRING,
2060 number=2,
2061 )
2064class DeleteSnapshotRequest(proto.Message):
2065 r"""Request for the ``DeleteSnapshot`` method.
2067 Attributes:
2068 snapshot (str):
2069 Required. The name of the snapshot to delete. Format is
2070 ``projects/{project}/snapshots/{snap}``.
2071 """
2073 snapshot: str = proto.Field(
2074 proto.STRING,
2075 number=1,
2076 )
2079class SeekRequest(proto.Message):
2080 r"""Request for the ``Seek`` method.
2082 This message has `oneof`_ fields (mutually exclusive fields).
2083 For each oneof, at most one member field can be set at the same time.
2084 Setting any member of the oneof automatically clears all other
2085 members.
2087 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
2089 Attributes:
2090 subscription (str):
2091 Required. The subscription to affect.
2092 time (google.protobuf.timestamp_pb2.Timestamp):
2093 The time to seek to. Messages retained in the subscription
2094 that were published before this time are marked as
2095 acknowledged, and messages retained in the subscription that
2096 were published after this time are marked as unacknowledged.
2097 Note that this operation affects only those messages
2098 retained in the subscription (configured by the combination
2099 of ``message_retention_duration`` and
2100 ``retain_acked_messages``). For example, if ``time``
2101 corresponds to a point before the message retention window
2102 (or to a point before the system's notion of the
2103 subscription creation time), only retained messages will be
2104 marked as unacknowledged, and already-expunged messages will
2105 not be restored.
2107 This field is a member of `oneof`_ ``target``.
2108 snapshot (str):
2109 The snapshot to seek to. The snapshot's topic must be the
2110 same as that of the provided subscription. Format is
2111 ``projects/{project}/snapshots/{snap}``.
2113 This field is a member of `oneof`_ ``target``.
2114 """
2116 subscription: str = proto.Field(
2117 proto.STRING,
2118 number=1,
2119 )
2120 time: timestamp_pb2.Timestamp = proto.Field(
2121 proto.MESSAGE,
2122 number=2,
2123 oneof="target",
2124 message=timestamp_pb2.Timestamp,
2125 )
2126 snapshot: str = proto.Field(
2127 proto.STRING,
2128 number=3,
2129 oneof="target",
2130 )
2133class SeekResponse(proto.Message):
2134 r"""Response for the ``Seek`` method (this response is empty)."""
2137__all__ = tuple(sorted(__protobuf__.manifest))