def pull(self, return_immediately=False, max_messages=1, connection=None):
"""API call: retrieve messages for the subscription.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/pull
:type return_immediately: boolean
:param return_immediately: 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.
:type max_messages: int
:param max_messages: the maximum number of messages to return.
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
:rtype: list of (ack_id, message) tuples
:returns: sequence of tuples: ``ack_id`` is the ID to be used in a
subsequent call to :meth:`acknowledge`, and ``message``
is an instance of :class:`gcloud.pubsub.message.Message`.
"""
connection = _require_connection(connection)
data = {
'returnImmediately': return_immediately,
'maxMessages': max_messages
}
response = connection.api_request(method='POST',
path='%s:pull' % self.path,
data=data)
return [(info['ackId'], Message.from_api_repr(info['message']))
for info in response['receivedMessages']]
def publish(self, message, connection=None, **attrs):
"""API call: publish a message to a topic via a POST request
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/topics/publish
:type message: bytes
:param message: the message payload
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the ``connection`` attribute.
:type attrs: dict (string -> string)
:message attrs: key-value pairs to send as message attributes
:rtype: str
:returns: message ID assigned by the server to the published message
"""
connection = _require_connection(connection)
self._timestamp_message(attrs)
message_b = base64.b64encode(message).decode('ascii')
message_data = {'data': message_b, 'attributes': attrs}
data = {'messages': [message_data]}
response = connection.api_request(method='POST',
path='%s:publish' % self.path,
data=data)
return response['messageIds'][0]
def list_subscriptions(page_size=None, page_token=None, topic_name=None,
project=None, connection=None):
"""List subscriptions for a given project.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/topics/list
and (where ``topic_name`` is passed):
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/topics/subscriptions/list
:type page_size: int
:param page_size: maximum number of topics to return, If not passed,
defaults to a value set by the API.
:type page_token: string
:param page_token: opaque marker for the next "page" of topics. If not
passed, the API will return the first page of topics.
:type topic_name: string
:param topic_name: limit results to subscriptions bound to the given topic.
:type project: string
:param project: project ID to query. If not passed, defaults to the
project ID inferred from the environment.
:type connection: :class:`gcloud.pubsub.connection.Connection`
:param connection: connection to use for the query. If not passed,
defaults to the connection inferred from the
environment.
:rtype: tuple, (list, str)
:returns: list of :class:`gcloud.pubsub.subscription.Subscription`, plus a
"next page token" string: if not None, indicates that
more topics can be retrieved with another call (pass that
value as ``page_token``).
"""
if project is None:
project = get_default_project()
connection = _require_connection(connection)
params = {}
if page_size is not None:
params['pageSize'] = page_size
if page_token is not None:
params['pageToken'] = page_token
if topic_name is None:
path = '/projects/%s/subscriptions' % project
else:
path = '/projects/%s/topics/%s/subscriptions' % (project, topic_name)
resp = connection.api_request(method='GET', path=path, query_params=params)
topics = {}
subscriptions = [Subscription.from_api_repr(resource, topics=topics)
for resource in resp['subscriptions']]
return subscriptions, resp.get('nextPageToken')
def delete(self, connection=None):
"""API call: delete the subscription via a DELETE request.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/delete
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
connection.api_request(method='DELETE', path=self.path)
def create(self, connection=None):
"""API call: create the topic via a PUT request
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/topics/create
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the ``connection`` attribute.
"""
connection = _require_connection(connection)
connection.api_request(method='PUT', path=self.path)
def reload(self, connection=None):
"""API call: sync local subscription configuration via a GET request
See
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/get
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
data = connection.api_request(method='GET', path=self.path)
self.ack_deadline = data.get('ackDeadline')
push_config = data.get('pushConfig', {})
self.push_endpoint = push_config.get('pushEndpoint')
def commit(self, connection=None):
"""Send saved messages as a single API call.
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the ``connection`` attribute.
"""
if connection is None and self.connection is not None:
connection = self.connection
connection = _require_connection(connection)
response = connection.api_request(method='POST',
path='%s:publish' % self.topic.path,
data={'messages': self.messages[:]})
self.message_ids.extend(response['messageIds'])
del self.messages[:]
def exists(self, connection=None):
"""API call: test existence of the subscription via a GET request
See
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/get
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
try:
connection.api_request(method='GET', path=self.path)
except NotFound:
return False
else:
return True
def acknowledge(self, ack_ids, connection=None):
"""API call: acknowledge retrieved messages for the subscription.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/acknowledge
:type ack_ids: list of string
:param ack_ids: ack IDs of messages being acknowledged
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
data = {'ackIds': ack_ids}
connection.api_request(method='POST',
path='%s:acknowledge' % self.path,
data=data)
def exists(self, connection=None):
"""API call: test for the existence of the topic via a GET request
See
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/topics/get
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the ``connection`` attribute.
"""
connection = _require_connection(connection)
try:
connection.api_request(method='GET', path=self.path)
except NotFound:
return False
else:
return True
def create(self, connection=None):
"""API call: create the subscription via a PUT request
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/create
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
data = {'topic': self.topic.full_name}
if self.ack_deadline is not None:
data['ackDeadline'] = self.ack_deadline
if self.push_endpoint is not None:
data['pushConfig'] = {'pushEndpoint': self.push_endpoint}
connection = _require_connection(connection)
connection.api_request(method='PUT', path=self.path, data=data)
def modify_ack_deadline(self, ack_id, ack_deadline, connection=None):
"""API call: update acknowledgement deadline for a retrieved message.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/acknowledge
:type ack_id: string
:param ack_id: ack ID of message being updated
:type ack_deadline: int
:param ack_deadline: new deadline for the message, in seconds
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
data = {'ackId': ack_id, 'ackDeadlineSeconds': ack_deadline}
connection.api_request(method='POST',
path='%s:modifyAckDeadline' % self.path,
data=data)
def modify_push_configuration(self, push_endpoint, connection=None):
"""API call: update the push endpoint for the subscription.
See:
https://cloud.google.com/pubsub/reference/rest/v1beta2/projects/subscriptions/modifyPushConfig
:type push_endpoint: string
:param push_endpoint: URL to which messages will be pushed by the
back-end. If None, the application must pull
messages.
:type connection: :class:`gcloud.pubsub.connection.Connection` or None
:param connection: the connection to use. If not passed,
falls back to the topic's connection.
"""
connection = _require_connection(connection)
data = {}
config = data['pushConfig'] = {}
if push_endpoint is not None:
config['pushEndpoint'] = push_endpoint
connection.api_request(method='POST',
path='%s:modifyPushConfig' % self.path,
data=data)
self.push_endpoint = push_endpoint
def _callFUT(self, connection=None):
from gcloud.pubsub._implicit_environ import _require_connection
return _require_connection(connection=connection)