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.3.0, created at 2023-08-18 07:15 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2023 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 Must not end in "/".
1216 text_config (google.pubsub_v1.types.CloudStorageConfig.TextConfig):
1217 If set, message data will be written to Cloud
1218 Storage in text format.
1220 This field is a member of `oneof`_ ``output_format``.
1221 avro_config (google.pubsub_v1.types.CloudStorageConfig.AvroConfig):
1222 If set, message data will be written to Cloud
1223 Storage in Avro format.
1225 This field is a member of `oneof`_ ``output_format``.
1226 max_duration (google.protobuf.duration_pb2.Duration):
1227 The maximum duration that can elapse before a
1228 new Cloud Storage file is created. Min 1 minute,
1229 max 10 minutes, default 5 minutes. May not
1230 exceed the subscription's acknowledgement
1231 deadline.
1232 max_bytes (int):
1233 The maximum bytes that can be written to a Cloud Storage
1234 file before a new file is created. Min 1 KB, max 10 GiB. The
1235 max_bytes limit may be exceeded in cases where messages are
1236 larger than the limit.
1237 state (google.pubsub_v1.types.CloudStorageConfig.State):
1238 Output only. An output-only field that
1239 indicates whether or not the subscription can
1240 receive messages.
1241 """
1243 class State(proto.Enum):
1244 r"""Possible states for a Cloud Storage subscription.
1246 Values:
1247 STATE_UNSPECIFIED (0):
1248 Default value. This value is unused.
1249 ACTIVE (1):
1250 The subscription can actively send messages
1251 to Cloud Storage.
1252 PERMISSION_DENIED (2):
1253 Cannot write to the Cloud Storage bucket
1254 because of permission denied errors.
1255 NOT_FOUND (3):
1256 Cannot write to the Cloud Storage bucket
1257 because it does not exist.
1258 """
1259 STATE_UNSPECIFIED = 0
1260 ACTIVE = 1
1261 PERMISSION_DENIED = 2
1262 NOT_FOUND = 3
1264 class TextConfig(proto.Message):
1265 r"""Configuration for writing message data in text format.
1266 Message payloads will be written to files as raw text, separated
1267 by a newline.
1269 """
1271 class AvroConfig(proto.Message):
1272 r"""Configuration for writing message data in Avro format.
1273 Message payloads and metadata will be written to files as an
1274 Avro binary.
1276 Attributes:
1277 write_metadata (bool):
1278 When true, write the subscription name, message_id,
1279 publish_time, attributes, and ordering_key as additional
1280 fields in the output. The subscription name, message_id, and
1281 publish_time fields are put in their own fields while all
1282 other message properties other than data (for example, an
1283 ordering_key, if present) are added as entries in the
1284 attributes map.
1285 """
1287 write_metadata: bool = proto.Field(
1288 proto.BOOL,
1289 number=1,
1290 )
1292 bucket: str = proto.Field(
1293 proto.STRING,
1294 number=1,
1295 )
1296 filename_prefix: str = proto.Field(
1297 proto.STRING,
1298 number=2,
1299 )
1300 filename_suffix: str = proto.Field(
1301 proto.STRING,
1302 number=3,
1303 )
1304 text_config: TextConfig = proto.Field(
1305 proto.MESSAGE,
1306 number=4,
1307 oneof="output_format",
1308 message=TextConfig,
1309 )
1310 avro_config: AvroConfig = proto.Field(
1311 proto.MESSAGE,
1312 number=5,
1313 oneof="output_format",
1314 message=AvroConfig,
1315 )
1316 max_duration: duration_pb2.Duration = proto.Field(
1317 proto.MESSAGE,
1318 number=6,
1319 message=duration_pb2.Duration,
1320 )
1321 max_bytes: int = proto.Field(
1322 proto.INT64,
1323 number=7,
1324 )
1325 state: State = proto.Field(
1326 proto.ENUM,
1327 number=9,
1328 enum=State,
1329 )
1332class ReceivedMessage(proto.Message):
1333 r"""A message and its corresponding acknowledgment ID.
1335 Attributes:
1336 ack_id (str):
1337 This ID can be used to acknowledge the
1338 received message.
1339 message (google.pubsub_v1.types.PubsubMessage):
1340 The message.
1341 delivery_attempt (int):
1342 The approximate number of times that Cloud Pub/Sub has
1343 attempted to deliver the associated message to a subscriber.
1345 More precisely, this is 1 + (number of NACKs) + (number of
1346 ack_deadline exceeds) for this message.
1348 A NACK is any call to ModifyAckDeadline with a 0 deadline.
1349 An ack_deadline exceeds event is whenever a message is not
1350 acknowledged within ack_deadline. Note that ack_deadline is
1351 initially Subscription.ackDeadlineSeconds, but may get
1352 extended automatically by the client library.
1354 Upon the first delivery of a given message,
1355 ``delivery_attempt`` will have a value of 1. The value is
1356 calculated at best effort and is approximate.
1358 If a DeadLetterPolicy is not set on the subscription, this
1359 will be 0.
1360 """
1362 ack_id: str = proto.Field(
1363 proto.STRING,
1364 number=1,
1365 )
1366 message: "PubsubMessage" = proto.Field(
1367 proto.MESSAGE,
1368 number=2,
1369 message="PubsubMessage",
1370 )
1371 delivery_attempt: int = proto.Field(
1372 proto.INT32,
1373 number=3,
1374 )
1377class GetSubscriptionRequest(proto.Message):
1378 r"""Request for the GetSubscription method.
1380 Attributes:
1381 subscription (str):
1382 Required. The name of the subscription to get. Format is
1383 ``projects/{project}/subscriptions/{sub}``.
1384 """
1386 subscription: str = proto.Field(
1387 proto.STRING,
1388 number=1,
1389 )
1392class UpdateSubscriptionRequest(proto.Message):
1393 r"""Request for the UpdateSubscription method.
1395 Attributes:
1396 subscription (google.pubsub_v1.types.Subscription):
1397 Required. The updated subscription object.
1398 update_mask (google.protobuf.field_mask_pb2.FieldMask):
1399 Required. Indicates which fields in the
1400 provided subscription to update. Must be
1401 specified and non-empty.
1402 """
1404 subscription: "Subscription" = proto.Field(
1405 proto.MESSAGE,
1406 number=1,
1407 message="Subscription",
1408 )
1409 update_mask: field_mask_pb2.FieldMask = proto.Field(
1410 proto.MESSAGE,
1411 number=2,
1412 message=field_mask_pb2.FieldMask,
1413 )
1416class ListSubscriptionsRequest(proto.Message):
1417 r"""Request for the ``ListSubscriptions`` method.
1419 Attributes:
1420 project (str):
1421 Required. The name of the project in which to list
1422 subscriptions. Format is ``projects/{project-id}``.
1423 page_size (int):
1424 Maximum number of subscriptions to return.
1425 page_token (str):
1426 The value returned by the last
1427 ``ListSubscriptionsResponse``; indicates that this is a
1428 continuation of a prior ``ListSubscriptions`` call, and that
1429 the system should return the next page of data.
1430 """
1432 project: str = proto.Field(
1433 proto.STRING,
1434 number=1,
1435 )
1436 page_size: int = proto.Field(
1437 proto.INT32,
1438 number=2,
1439 )
1440 page_token: str = proto.Field(
1441 proto.STRING,
1442 number=3,
1443 )
1446class ListSubscriptionsResponse(proto.Message):
1447 r"""Response for the ``ListSubscriptions`` method.
1449 Attributes:
1450 subscriptions (MutableSequence[google.pubsub_v1.types.Subscription]):
1451 The subscriptions that match the request.
1452 next_page_token (str):
1453 If not empty, indicates that there may be more subscriptions
1454 that match the request; this value should be passed in a new
1455 ``ListSubscriptionsRequest`` to get more subscriptions.
1456 """
1458 @property
1459 def raw_page(self):
1460 return self
1462 subscriptions: MutableSequence["Subscription"] = proto.RepeatedField(
1463 proto.MESSAGE,
1464 number=1,
1465 message="Subscription",
1466 )
1467 next_page_token: str = proto.Field(
1468 proto.STRING,
1469 number=2,
1470 )
1473class DeleteSubscriptionRequest(proto.Message):
1474 r"""Request for the DeleteSubscription method.
1476 Attributes:
1477 subscription (str):
1478 Required. The subscription to delete. Format is
1479 ``projects/{project}/subscriptions/{sub}``.
1480 """
1482 subscription: str = proto.Field(
1483 proto.STRING,
1484 number=1,
1485 )
1488class ModifyPushConfigRequest(proto.Message):
1489 r"""Request for the ModifyPushConfig method.
1491 Attributes:
1492 subscription (str):
1493 Required. The name of the subscription. Format is
1494 ``projects/{project}/subscriptions/{sub}``.
1495 push_config (google.pubsub_v1.types.PushConfig):
1496 Required. The push configuration for future deliveries.
1498 An empty ``pushConfig`` indicates that the Pub/Sub system
1499 should stop pushing messages from the given subscription and
1500 allow messages to be pulled and acknowledged - effectively
1501 pausing the subscription if ``Pull`` or ``StreamingPull`` is
1502 not called.
1503 """
1505 subscription: str = proto.Field(
1506 proto.STRING,
1507 number=1,
1508 )
1509 push_config: "PushConfig" = proto.Field(
1510 proto.MESSAGE,
1511 number=2,
1512 message="PushConfig",
1513 )
1516class PullRequest(proto.Message):
1517 r"""Request for the ``Pull`` method.
1519 Attributes:
1520 subscription (str):
1521 Required. The subscription from which messages should be
1522 pulled. Format is
1523 ``projects/{project}/subscriptions/{sub}``.
1524 return_immediately (bool):
1525 Optional. If this field set to true, the system will respond
1526 immediately even if it there are no messages available to
1527 return in the ``Pull`` response. Otherwise, the system may
1528 wait (for a bounded amount of time) until at least one
1529 message is available, rather than returning no messages.
1530 Warning: setting this field to ``true`` is discouraged
1531 because it adversely impacts the performance of ``Pull``
1532 operations. We recommend that users do not set this field.
1533 max_messages (int):
1534 Required. The maximum number of messages to
1535 return for this request. Must be a positive
1536 integer. The Pub/Sub system may return fewer
1537 than the number specified.
1538 """
1540 subscription: str = proto.Field(
1541 proto.STRING,
1542 number=1,
1543 )
1544 return_immediately: bool = proto.Field(
1545 proto.BOOL,
1546 number=2,
1547 )
1548 max_messages: int = proto.Field(
1549 proto.INT32,
1550 number=3,
1551 )
1554class PullResponse(proto.Message):
1555 r"""Response for the ``Pull`` method.
1557 Attributes:
1558 received_messages (MutableSequence[google.pubsub_v1.types.ReceivedMessage]):
1559 Received Pub/Sub messages. The list will be empty if there
1560 are no more messages available in the backlog, or if no
1561 messages could be returned before the request timeout. For
1562 JSON, the response can be entirely empty. The Pub/Sub system
1563 may return fewer than the ``maxMessages`` requested even if
1564 there are more messages available in the backlog.
1565 """
1567 received_messages: MutableSequence["ReceivedMessage"] = proto.RepeatedField(
1568 proto.MESSAGE,
1569 number=1,
1570 message="ReceivedMessage",
1571 )
1574class ModifyAckDeadlineRequest(proto.Message):
1575 r"""Request for the ModifyAckDeadline method.
1577 Attributes:
1578 subscription (str):
1579 Required. The name of the subscription. Format is
1580 ``projects/{project}/subscriptions/{sub}``.
1581 ack_ids (MutableSequence[str]):
1582 Required. List of acknowledgment IDs.
1583 ack_deadline_seconds (int):
1584 Required. The new ack deadline with respect to the time this
1585 request was sent to the Pub/Sub system. For example, if the
1586 value is 10, the new ack deadline will expire 10 seconds
1587 after the ``ModifyAckDeadline`` call was made. Specifying
1588 zero might immediately make the message available for
1589 delivery to another subscriber client. This typically
1590 results in an increase in the rate of message redeliveries
1591 (that is, duplicates). The minimum deadline you can specify
1592 is 0 seconds. The maximum deadline you can specify is 600
1593 seconds (10 minutes).
1594 """
1596 subscription: str = proto.Field(
1597 proto.STRING,
1598 number=1,
1599 )
1600 ack_ids: MutableSequence[str] = proto.RepeatedField(
1601 proto.STRING,
1602 number=4,
1603 )
1604 ack_deadline_seconds: int = proto.Field(
1605 proto.INT32,
1606 number=3,
1607 )
1610class AcknowledgeRequest(proto.Message):
1611 r"""Request for the Acknowledge method.
1613 Attributes:
1614 subscription (str):
1615 Required. The subscription whose message is being
1616 acknowledged. Format is
1617 ``projects/{project}/subscriptions/{sub}``.
1618 ack_ids (MutableSequence[str]):
1619 Required. The acknowledgment ID for the messages being
1620 acknowledged that was returned by the Pub/Sub system in the
1621 ``Pull`` response. Must not be empty.
1622 """
1624 subscription: str = proto.Field(
1625 proto.STRING,
1626 number=1,
1627 )
1628 ack_ids: MutableSequence[str] = proto.RepeatedField(
1629 proto.STRING,
1630 number=2,
1631 )
1634class StreamingPullRequest(proto.Message):
1635 r"""Request for the ``StreamingPull`` streaming RPC method. This request
1636 is used to establish the initial stream as well as to stream
1637 acknowledgements and ack deadline modifications from the client to
1638 the server.
1640 Attributes:
1641 subscription (str):
1642 Required. The subscription for which to initialize the new
1643 stream. This must be provided in the first request on the
1644 stream, and must not be set in subsequent requests from
1645 client to server. Format is
1646 ``projects/{project}/subscriptions/{sub}``.
1647 ack_ids (MutableSequence[str]):
1648 List of acknowledgement IDs for acknowledging previously
1649 received messages (received on this stream or a different
1650 stream). If an ack ID has expired, the corresponding message
1651 may be redelivered later. Acknowledging a message more than
1652 once will not result in an error. If the acknowledgement ID
1653 is malformed, the stream will be aborted with status
1654 ``INVALID_ARGUMENT``.
1655 modify_deadline_seconds (MutableSequence[int]):
1656 The list of new ack deadlines for the IDs listed in
1657 ``modify_deadline_ack_ids``. The size of this list must be
1658 the same as the size of ``modify_deadline_ack_ids``. If it
1659 differs the stream will be aborted with
1660 ``INVALID_ARGUMENT``. Each element in this list is applied
1661 to the element in the same position in
1662 ``modify_deadline_ack_ids``. The new ack deadline is with
1663 respect to the time this request was sent to the Pub/Sub
1664 system. Must be >= 0. For example, if the value is 10, the
1665 new ack deadline will expire 10 seconds after this request
1666 is received. If the value is 0, the message is immediately
1667 made available for another streaming or non-streaming pull
1668 request. If the value is < 0 (an error), the stream will be
1669 aborted with status ``INVALID_ARGUMENT``.
1670 modify_deadline_ack_ids (MutableSequence[str]):
1671 List of acknowledgement IDs whose deadline will be modified
1672 based on the corresponding element in
1673 ``modify_deadline_seconds``. This field can be used to
1674 indicate that more time is needed to process a message by
1675 the subscriber, or to make the message available for
1676 redelivery if the processing was interrupted.
1677 stream_ack_deadline_seconds (int):
1678 Required. The ack deadline to use for the
1679 stream. This must be provided in the first
1680 request on the stream, but it can also be
1681 updated on subsequent requests from client to
1682 server. The minimum deadline you can specify is
1683 10 seconds. The maximum deadline you can specify
1684 is 600 seconds (10 minutes).
1685 client_id (str):
1686 A unique identifier that is used to distinguish client
1687 instances from each other. Only needs to be provided on the
1688 initial request. When a stream disconnects and reconnects
1689 for the same stream, the client_id should be set to the same
1690 value so that state associated with the old stream can be
1691 transferred to the new stream. The same client_id should not
1692 be used for different client instances.
1693 max_outstanding_messages (int):
1694 Flow control settings for the maximum number of outstanding
1695 messages. When there are ``max_outstanding_messages`` or
1696 more currently sent to the streaming pull client that have
1697 not yet been acked or nacked, the server stops sending more
1698 messages. The sending of messages resumes once the number of
1699 outstanding messages is less than this value. If the value
1700 is <= 0, there is no limit to the number of outstanding
1701 messages. This property can only be set on the initial
1702 StreamingPullRequest. If it is set on a subsequent request,
1703 the stream will be aborted with status ``INVALID_ARGUMENT``.
1704 max_outstanding_bytes (int):
1705 Flow control settings for the maximum number of outstanding
1706 bytes. When there are ``max_outstanding_bytes`` or more
1707 worth of messages currently sent to the streaming pull
1708 client that have not yet been acked or nacked, the server
1709 will stop sending more messages. The sending of messages
1710 resumes once the number of outstanding bytes is less than
1711 this value. If the value is <= 0, there is no limit to the
1712 number of outstanding bytes. This property can only be set
1713 on the initial StreamingPullRequest. If it is set on a
1714 subsequent request, the stream will be aborted with status
1715 ``INVALID_ARGUMENT``.
1716 """
1718 subscription: str = proto.Field(
1719 proto.STRING,
1720 number=1,
1721 )
1722 ack_ids: MutableSequence[str] = proto.RepeatedField(
1723 proto.STRING,
1724 number=2,
1725 )
1726 modify_deadline_seconds: MutableSequence[int] = proto.RepeatedField(
1727 proto.INT32,
1728 number=3,
1729 )
1730 modify_deadline_ack_ids: MutableSequence[str] = proto.RepeatedField(
1731 proto.STRING,
1732 number=4,
1733 )
1734 stream_ack_deadline_seconds: int = proto.Field(
1735 proto.INT32,
1736 number=5,
1737 )
1738 client_id: str = proto.Field(
1739 proto.STRING,
1740 number=6,
1741 )
1742 max_outstanding_messages: int = proto.Field(
1743 proto.INT64,
1744 number=7,
1745 )
1746 max_outstanding_bytes: int = proto.Field(
1747 proto.INT64,
1748 number=8,
1749 )
1752class StreamingPullResponse(proto.Message):
1753 r"""Response for the ``StreamingPull`` method. This response is used to
1754 stream messages from the server to the client.
1756 Attributes:
1757 received_messages (MutableSequence[google.pubsub_v1.types.ReceivedMessage]):
1758 Received Pub/Sub messages. This will not be
1759 empty.
1760 acknowledge_confirmation (google.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation):
1761 This field will only be set if
1762 ``enable_exactly_once_delivery`` is set to ``true``.
1763 modify_ack_deadline_confirmation (google.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation):
1764 This field will only be set if
1765 ``enable_exactly_once_delivery`` is set to ``true``.
1766 subscription_properties (google.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties):
1767 Properties associated with this subscription.
1768 """
1770 class AcknowledgeConfirmation(proto.Message):
1771 r"""Acknowledgement IDs sent in one or more previous requests to
1772 acknowledge a previously received message.
1774 Attributes:
1775 ack_ids (MutableSequence[str]):
1776 Successfully processed acknowledgement IDs.
1777 invalid_ack_ids (MutableSequence[str]):
1778 List of acknowledgement IDs that were
1779 malformed or whose acknowledgement deadline has
1780 expired.
1781 unordered_ack_ids (MutableSequence[str]):
1782 List of acknowledgement IDs that were out of
1783 order.
1784 temporary_failed_ack_ids (MutableSequence[str]):
1785 List of acknowledgement IDs that failed
1786 processing with temporary issues.
1787 """
1789 ack_ids: MutableSequence[str] = proto.RepeatedField(
1790 proto.STRING,
1791 number=1,
1792 )
1793 invalid_ack_ids: MutableSequence[str] = proto.RepeatedField(
1794 proto.STRING,
1795 number=2,
1796 )
1797 unordered_ack_ids: MutableSequence[str] = proto.RepeatedField(
1798 proto.STRING,
1799 number=3,
1800 )
1801 temporary_failed_ack_ids: MutableSequence[str] = proto.RepeatedField(
1802 proto.STRING,
1803 number=4,
1804 )
1806 class ModifyAckDeadlineConfirmation(proto.Message):
1807 r"""Acknowledgement IDs sent in one or more previous requests to
1808 modify the deadline for a specific message.
1810 Attributes:
1811 ack_ids (MutableSequence[str]):
1812 Successfully processed acknowledgement IDs.
1813 invalid_ack_ids (MutableSequence[str]):
1814 List of acknowledgement IDs that were
1815 malformed or whose acknowledgement deadline has
1816 expired.
1817 temporary_failed_ack_ids (MutableSequence[str]):
1818 List of acknowledgement IDs that failed
1819 processing with temporary issues.
1820 """
1822 ack_ids: MutableSequence[str] = proto.RepeatedField(
1823 proto.STRING,
1824 number=1,
1825 )
1826 invalid_ack_ids: MutableSequence[str] = proto.RepeatedField(
1827 proto.STRING,
1828 number=2,
1829 )
1830 temporary_failed_ack_ids: MutableSequence[str] = proto.RepeatedField(
1831 proto.STRING,
1832 number=3,
1833 )
1835 class SubscriptionProperties(proto.Message):
1836 r"""Subscription properties sent as part of the response.
1838 Attributes:
1839 exactly_once_delivery_enabled (bool):
1840 True iff exactly once delivery is enabled for
1841 this subscription.
1842 message_ordering_enabled (bool):
1843 True iff message ordering is enabled for this
1844 subscription.
1845 """
1847 exactly_once_delivery_enabled: bool = proto.Field(
1848 proto.BOOL,
1849 number=1,
1850 )
1851 message_ordering_enabled: bool = proto.Field(
1852 proto.BOOL,
1853 number=2,
1854 )
1856 received_messages: MutableSequence["ReceivedMessage"] = proto.RepeatedField(
1857 proto.MESSAGE,
1858 number=1,
1859 message="ReceivedMessage",
1860 )
1861 acknowledge_confirmation: AcknowledgeConfirmation = proto.Field(
1862 proto.MESSAGE,
1863 number=5,
1864 message=AcknowledgeConfirmation,
1865 )
1866 modify_ack_deadline_confirmation: ModifyAckDeadlineConfirmation = proto.Field(
1867 proto.MESSAGE,
1868 number=3,
1869 message=ModifyAckDeadlineConfirmation,
1870 )
1871 subscription_properties: SubscriptionProperties = proto.Field(
1872 proto.MESSAGE,
1873 number=4,
1874 message=SubscriptionProperties,
1875 )
1878class CreateSnapshotRequest(proto.Message):
1879 r"""Request for the ``CreateSnapshot`` method.
1881 Attributes:
1882 name (str):
1883 Required. User-provided name for this snapshot. If the name
1884 is not provided in the request, the server will assign a
1885 random name for this snapshot on the same project as the
1886 subscription. Note that for REST API requests, you must
1887 specify a name. See the `resource name
1888 rules <https://cloud.google.com/pubsub/docs/admin#resource_names>`__.
1889 Format is ``projects/{project}/snapshots/{snap}``.
1890 subscription (str):
1891 Required. The subscription whose backlog the snapshot
1892 retains. Specifically, the created snapshot is guaranteed to
1893 retain: (a) The existing backlog on the subscription. More
1894 precisely, this is defined as the messages in the
1895 subscription's backlog that are unacknowledged upon the
1896 successful completion of the ``CreateSnapshot`` request; as
1897 well as: (b) Any messages published to the subscription's
1898 topic following the successful completion of the
1899 CreateSnapshot request. Format is
1900 ``projects/{project}/subscriptions/{sub}``.
1901 labels (MutableMapping[str, str]):
1902 See `Creating and managing
1903 labels <https://cloud.google.com/pubsub/docs/labels>`__.
1904 """
1906 name: str = proto.Field(
1907 proto.STRING,
1908 number=1,
1909 )
1910 subscription: str = proto.Field(
1911 proto.STRING,
1912 number=2,
1913 )
1914 labels: MutableMapping[str, str] = proto.MapField(
1915 proto.STRING,
1916 proto.STRING,
1917 number=3,
1918 )
1921class UpdateSnapshotRequest(proto.Message):
1922 r"""Request for the UpdateSnapshot method.
1924 Attributes:
1925 snapshot (google.pubsub_v1.types.Snapshot):
1926 Required. The updated snapshot object.
1927 update_mask (google.protobuf.field_mask_pb2.FieldMask):
1928 Required. Indicates which fields in the
1929 provided snapshot to update. Must be specified
1930 and non-empty.
1931 """
1933 snapshot: "Snapshot" = proto.Field(
1934 proto.MESSAGE,
1935 number=1,
1936 message="Snapshot",
1937 )
1938 update_mask: field_mask_pb2.FieldMask = proto.Field(
1939 proto.MESSAGE,
1940 number=2,
1941 message=field_mask_pb2.FieldMask,
1942 )
1945class Snapshot(proto.Message):
1946 r"""A snapshot resource. Snapshots are used in
1947 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__
1948 operations, which allow you to manage message acknowledgments in
1949 bulk. That is, you can set the acknowledgment state of messages in
1950 an existing subscription to the state captured by a snapshot.
1952 Attributes:
1953 name (str):
1954 The name of the snapshot.
1955 topic (str):
1956 The name of the topic from which this
1957 snapshot is retaining messages.
1958 expire_time (google.protobuf.timestamp_pb2.Timestamp):
1959 The snapshot is guaranteed to exist up until this time. A
1960 newly-created snapshot expires no later than 7 days from the
1961 time of its creation. Its exact lifetime is determined at
1962 creation by the existing backlog in the source subscription.
1963 Specifically, the lifetime of the snapshot is
1964 ``7 days - (age of oldest unacked message in the subscription)``.
1965 For example, consider a subscription whose oldest unacked
1966 message is 3 days old. If a snapshot is created from this
1967 subscription, the snapshot -- which will always capture this
1968 3-day-old backlog as long as the snapshot exists -- will
1969 expire in 4 days. The service will refuse to create a
1970 snapshot that would expire in less than 1 hour after
1971 creation.
1972 labels (MutableMapping[str, str]):
1973 See [Creating and managing labels]
1974 (https://cloud.google.com/pubsub/docs/labels).
1975 """
1977 name: str = proto.Field(
1978 proto.STRING,
1979 number=1,
1980 )
1981 topic: str = proto.Field(
1982 proto.STRING,
1983 number=2,
1984 )
1985 expire_time: timestamp_pb2.Timestamp = proto.Field(
1986 proto.MESSAGE,
1987 number=3,
1988 message=timestamp_pb2.Timestamp,
1989 )
1990 labels: MutableMapping[str, str] = proto.MapField(
1991 proto.STRING,
1992 proto.STRING,
1993 number=4,
1994 )
1997class GetSnapshotRequest(proto.Message):
1998 r"""Request for the GetSnapshot method.
2000 Attributes:
2001 snapshot (str):
2002 Required. The name of the snapshot to get. Format is
2003 ``projects/{project}/snapshots/{snap}``.
2004 """
2006 snapshot: str = proto.Field(
2007 proto.STRING,
2008 number=1,
2009 )
2012class ListSnapshotsRequest(proto.Message):
2013 r"""Request for the ``ListSnapshots`` method.
2015 Attributes:
2016 project (str):
2017 Required. The name of the project in which to list
2018 snapshots. Format is ``projects/{project-id}``.
2019 page_size (int):
2020 Maximum number of snapshots to return.
2021 page_token (str):
2022 The value returned by the last ``ListSnapshotsResponse``;
2023 indicates that this is a continuation of a prior
2024 ``ListSnapshots`` call, and that the system should return
2025 the next page of data.
2026 """
2028 project: str = proto.Field(
2029 proto.STRING,
2030 number=1,
2031 )
2032 page_size: int = proto.Field(
2033 proto.INT32,
2034 number=2,
2035 )
2036 page_token: str = proto.Field(
2037 proto.STRING,
2038 number=3,
2039 )
2042class ListSnapshotsResponse(proto.Message):
2043 r"""Response for the ``ListSnapshots`` method.
2045 Attributes:
2046 snapshots (MutableSequence[google.pubsub_v1.types.Snapshot]):
2047 The resulting snapshots.
2048 next_page_token (str):
2049 If not empty, indicates that there may be more snapshot that
2050 match the request; this value should be passed in a new
2051 ``ListSnapshotsRequest``.
2052 """
2054 @property
2055 def raw_page(self):
2056 return self
2058 snapshots: MutableSequence["Snapshot"] = proto.RepeatedField(
2059 proto.MESSAGE,
2060 number=1,
2061 message="Snapshot",
2062 )
2063 next_page_token: str = proto.Field(
2064 proto.STRING,
2065 number=2,
2066 )
2069class DeleteSnapshotRequest(proto.Message):
2070 r"""Request for the ``DeleteSnapshot`` method.
2072 Attributes:
2073 snapshot (str):
2074 Required. The name of the snapshot to delete. Format is
2075 ``projects/{project}/snapshots/{snap}``.
2076 """
2078 snapshot: str = proto.Field(
2079 proto.STRING,
2080 number=1,
2081 )
2084class SeekRequest(proto.Message):
2085 r"""Request for the ``Seek`` method.
2087 This message has `oneof`_ fields (mutually exclusive fields).
2088 For each oneof, at most one member field can be set at the same time.
2089 Setting any member of the oneof automatically clears all other
2090 members.
2092 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
2094 Attributes:
2095 subscription (str):
2096 Required. The subscription to affect.
2097 time (google.protobuf.timestamp_pb2.Timestamp):
2098 The time to seek to. Messages retained in the subscription
2099 that were published before this time are marked as
2100 acknowledged, and messages retained in the subscription that
2101 were published after this time are marked as unacknowledged.
2102 Note that this operation affects only those messages
2103 retained in the subscription (configured by the combination
2104 of ``message_retention_duration`` and
2105 ``retain_acked_messages``). For example, if ``time``
2106 corresponds to a point before the message retention window
2107 (or to a point before the system's notion of the
2108 subscription creation time), only retained messages will be
2109 marked as unacknowledged, and already-expunged messages will
2110 not be restored.
2112 This field is a member of `oneof`_ ``target``.
2113 snapshot (str):
2114 The snapshot to seek to. The snapshot's topic must be the
2115 same as that of the provided subscription. Format is
2116 ``projects/{project}/snapshots/{snap}``.
2118 This field is a member of `oneof`_ ``target``.
2119 """
2121 subscription: str = proto.Field(
2122 proto.STRING,
2123 number=1,
2124 )
2125 time: timestamp_pb2.Timestamp = proto.Field(
2126 proto.MESSAGE,
2127 number=2,
2128 oneof="target",
2129 message=timestamp_pb2.Timestamp,
2130 )
2131 snapshot: str = proto.Field(
2132 proto.STRING,
2133 number=3,
2134 oneof="target",
2135 )
2138class SeekResponse(proto.Message):
2139 r"""Response for the ``Seek`` method (this response is empty)."""
2142__all__ = tuple(sorted(__protobuf__.manifest))