Subscriptions#
Define API Subscriptions.
-
class
google.cloud.pubsub.subscription.
Subscription
(name, topic=None, ack_deadline=None, push_endpoint=None, client=None)[source]# Bases:
object
Subscriptions receive messages published to their topics.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions
Parameters: - name (string) – the name of the subscription.
- topic (
google.cloud.pubsub.topic.Topic
orNoneType
) – the topic to which the subscription belongs; ifNone
, the subscription’s topic has been deleted. - 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.
- client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the 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 (
google.cloud.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: Returns: Subscription parsed from
resource
.
-
project
# Project bound to the subscription.
-
full_name
# Fully-qualified name used in subscription APIs
-
path
# URL path for the subscription’s APIs
-
auto_ack
(return_immediately=False, max_messages=1, client=None)[source]# AutoAck
factoryParameters: - return_immediately (boolean) – passed through to
Subscription.pull()
- max_messages (int) – passed through to
Subscription.pull()
- client (
Client
orNoneType
) – passed through toSubscription.pull()
andSubscription.acknowledge()
.
Return type: Returns: the instance created for the given
ack_id
andmessage
- return_immediately (boolean) – passed through to
-
create
(client=None)[source]# API call: create the subscription via a PUT request
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create
Example:
subscription = topic.subscription(SUB_NAME) subscription.create() # API request
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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/docs/reference/rest/v1/projects.subscriptions/get
Example:
assert subscription.exists() # API request
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current subscription’s topic.Return type: bool Returns: Boolean indicating existence of the subscription.
-
reload
(client=None)[source]# API call: sync local subscription configuration via a GET request
See https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/get
Example:
subscription.reload() # API request
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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/docs/reference/rest/v1/projects.subscriptions/delete
Example:
subscription.delete() # API request
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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/docs/reference/rest/v1/projects.subscriptions/modifyPushConfig
Example:
subscription.modify_push_configuration(push_endpoint=None) # API request
subscription.modify_push_configuration( push_endpoint=PUSH_URL) # API request
Parameters:
-
pull
(return_immediately=False, max_messages=1, client=None)[source]# API call: retrieve messages for the subscription.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull
Example:
pulled = subscription.pull(max_messages=2)
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 (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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 toacknowledge()
, andmessage
is an instance ofMessage
.
-
acknowledge
(ack_ids, client=None)[source]# API call: acknowledge retrieved messages for the subscription.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/acknowledge
Example:
for ack_id, message in pulled: try: do_something_with(message) except ApplicationException as e: log_exception(e) else: subscription.acknowledge([ack_id])
Parameters: - ack_ids (list of string) – ack IDs of messages being acknowledged
- client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current subscription’s topic.
-
modify_ack_deadline
(ack_ids, ack_deadline, client=None)[source]# API call: update acknowledgement deadline for a retrieved message.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/modifyAckDeadline
Parameters:
-
get_iam_policy
(client=None)[source]# Fetch the IAM policy for the subscription.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/getIamPolicy
Example:
policy = subscription.get_iam_policy() # API request
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current subscription’s topic.Return type: google.cloud.pubsub.iam.Policy
Returns: policy created from the resource returned by the getIamPolicy
API request.
-
set_iam_policy
(policy, client=None)[source]# Update the IAM policy for the subscription.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/setIamPolicy
Example:
ALL_USERS = policy.all_users() policy.viewers.add(ALL_USERS) LOGS_GROUP = policy.group('cloud-logs@google.com') policy.editors.add(LOGS_GROUP) new_policy = subscription.set_iam_policy(policy) # API request
Parameters: - policy (
google.cloud.pubsub.iam.Policy
) – the new policy, typically fetched viaget_iam_policy()
and updated in place. - client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current subscription’s topic.
Return type: Returns: updated policy created from the resource returned by the
setIamPolicy
API request.- policy (
-
check_iam_permissions
(permissions, client=None)[source]# Verify permissions allowed for the current user.
See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/testIamPermissions
Example:
from google.cloud.pubsub.iam import OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE TO_CHECK = [OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE] ALLOWED = subscription.check_iam_permissions(TO_CHECK) assert set(ALLOWED) == set(TO_CHECK)
Parameters: - permissions (list of string) – list of permissions to be tested
- client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current subscription’s topic.
Return type: sequence of string
Returns: subset of
permissions
allowed by current IAM policy.
-
class
google.cloud.pubsub.subscription.
AutoAck
(subscription, return_immediately=False, max_messages=1, client=None)[source]# Bases:
dict
Wrapper for
Subscription.pull()
results.Mapping, tracks messages still-to-be-acknowledged.
When used as a context manager, acknowledges all messages still in the mapping on __exit__. When processing the pulled messages, application code MUST delete messages from the
AutoAck
mapping which are not successfully processed, e.g.:Parameters: - subscription (
Subscription
) – subscription to be pulled. - return_immediately (boolean) – passed through to
Subscription.pull()
- max_messages (int) – passed through to
Subscription.pull()
- client (
Client
orNoneType
) – passed through toSubscription.pull()
andSubscription.acknowledge()
.
- subscription (