As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Messages

class google.cloud.pubsub_v1.subscriber.message.Message(message, ack_id, delivery_attempt, request_queue)

A representation of a single Pub/Sub message.

The common way to interact with Message objects is to receive them in callbacks on subscriptions; most users should never have a need to instantiate them by hand. (The exception to this is if you are implementing a custom subclass to Consumer.)

message_id

The message ID. In general, you should not need to use this directly.

Type

str

data

The data in the message. Note that this will be a bytes, not a text string.

Type

bytes

attributes

The attributes sent along with the message. See attributes for more information on this type.

Type

ScalarMapContainer

publish_time

The time that this message was originally published.

Type

datetime

Construct the Message.

Note

This class should not be constructed directly; it is the responsibility of BasePolicy subclasses to do so.

Parameters

• message (PubsubMessage) – The message received from Pub/Sub. For performance reasons it should be the the raw protobuf message wrapped by the PubsubMessage class obtained through the message’s .pb() method.

• ack_id (str) – The ack_id received from Pub/Sub.

• delivery_attempt (int) – The delivery attempt counter received from Pub/Sub if a DeadLetterPolicy is set on the subscription, and zero otherwise.

• request_queue (queue.Queue) – A queue provided by the policy that can accept requests; the policy is responsible for handling those requests.

ack()

Acknowledge the given message.

Acknowledging a message in Pub/Sub means that you are done with it, and it will not be delivered to this subscription again. You should avoid acknowledging messages until you have finished processing them, so that in the event of a failure, you receive the message again.

Warning

Acks in Pub/Sub are best effort. You should always ensure that your processing code is idempotent, as you may receive any given message more than once.

property ack_id

the ID used to ack the message.

Type

str

property attributes

Return the attributes of the underlying Pub/Sub Message.

Warning

A ScalarMapContainer behaves slightly differently than a dict. For a Pub / Sub message this is a string->string map. When trying to access a value via map['key'], if the key is not in the map, then the default value for the string type will be returned, which is an empty string. It may be more intuitive to just cast the map to a dict or to one use map.get.

Returns

The message’s attributes. This is a dict-like object provided by google.protobuf.

Return type

ScalarMapContainer

property data

Return the data for the underlying Pub/Sub Message.

Returns

The message data. This is always a bytestring; if you

want a text string, call bytes.decode().

Return type

bytes

property delivery_attempt

The delivery attempt counter is 1 + (the sum of number of NACKs and number of ack_deadline exceeds) for this message. It is set to None if a DeadLetterPolicy is not set on the subscription.

A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline exceeds event is whenever a message is not acknowledged within ack_deadline. Note that ack_deadline is initially Subscription.ackDeadlineSeconds, but may get extended automatically by the client library.

The first delivery of a given message will have this value as 1. The value is calculated at best effort and is approximate.

Returns

The delivery attempt counter or None.

Return type

Optional[int]

drop()

Release the message from lease management.

This informs the policy to no longer hold on to the lease for this message. Pub/Sub will re-deliver the message if it is not acknowledged before the existing lease expires.

Warning

For most use cases, the only reason to drop a message from lease management is on ack or nack; this library automatically drop()s the message on ack or nack. You probably do not want to call this method directly.

modify_ack_deadline(seconds)

Resets the deadline for acknowledgement.

New deadline will be the given value of seconds from now.

The default implementation handles this for you; you should not need to manually deal with setting ack deadlines. The exception case is if you are implementing your own custom subclass of Consumer.

Parameters

seconds (int) – The number of seconds to set the lease deadline to. This should be between 0 and 600. Due to network latency, values below 10 are advised against.

nack()

Decline to acknowldge the given message.

This will cause the message to be re-delivered to the subscription.

property ordering_key

the ordering key used to publish the message.

Type

str

property publish_time

Return the time that the message was originally published.

Returns

The date and time that the message was published.

Return type

datetime

property size

Return the size of the underlying message, in bytes.