Version History (fa4563d)
Report an Issue

Subscriptions#

Define API Subscriptions.

class gcloud.pubsub.subscription.Subscription(name, topic, ack_deadline=None, push_endpoint=None)[source]#

Bases: object

Subscriptions receive messages published to their topics.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions

Parameters:
  • name (string) – the name of the subscription
  • topic (gcloud.pubsub.topic.Topic) – the topic to which the subscription belongs..
  • ack_deadline (int) – the deadline (in seconds) by which messages pulled from the back-end must be acknowledged.
  • push_endpoint (string) – URL to which messages will be pushed by the back-end. If not set, the application must pull messages.
acknowledge(ack_ids, client=None)[source]#

API call: acknowledge retrieved messages for the subscription.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/acknowledge

Parameters:
  • ack_ids (list of string) – ack IDs of messages being acknowledged
  • client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
create(client=None)[source]#

API call: create the subscription via a PUT request

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/create

Parameters:client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
delete(client=None)[source]#

API call: delete the subscription via a DELETE request.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/delete

Parameters:client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
exists(client=None)[source]#

API call: test existence of the subscription via a GET request

See https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/get

Parameters:client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
classmethod from_api_repr(resource, client, topics=None)[source]#

Factory: construct a topic given its API representation

Parameters:
  • resource (dict) – topic resource representation returned from the API
  • client (gcloud.pubsub.client.Client) – Client which holds credentials and project configuration for a topic.
  • topics (dict or None) – A mapping of topic names -> topics. If not passed, the subscription will have a newly-created topic.
Return type:

gcloud.pubsub.subscription.Subscription
Returns:

Subscription parsed from resource.
modify_ack_deadline(ack_id, ack_deadline, client=None)[source]#

API call: update acknowledgement deadline for a retrieved message.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/acknowledge

Parameters:
  • ack_id (string) – ack ID of message being updated
  • ack_deadline (int) – new deadline for the message, in seconds
  • client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
modify_push_configuration(push_endpoint, client=None)[source]#

API call: update the push endpoint for the subscription.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/modifyPushConfig

Parameters:
  • push_endpoint (string) – URL to which messages will be pushed by the back-end. If None, the application must pull messages.
  • client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
path#

URL path for the subscription’s APIs

pull(return_immediately=False, max_messages=1, client=None)[source]#

API call: retrieve messages for the subscription.

See: https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/pull

Parameters:
  • return_immediately (boolean) – if True, the back-end returns even if no messages are available; if False, the API call blocks until one or more messages are available.
  • max_messages (int) – the maximum number of messages to return.
  • client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
Return type:

list of (ack_id, message) tuples
Returns:

sequence of tuples: ack_id is the ID to be used in a subsequent call to acknowledge(), and message is an instance of gcloud.pubsub.message.Message.
reload(client=None)[source]#

API call: sync local subscription configuration via a GET request

See https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/get

Parameters:client (gcloud.pubsub.client.Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.