def settle_deferred_messages(self, settlement, messages, **kwargs):
"""Settle messages that have been previously deferred.
:param settlement: How the messages are to be settled. This must be a string
of one of the following values: 'completed', 'suspended', 'abandoned'.
:type settlement: str
:param messages: A list of deferred messages to be settled.
:type messages: list[~azure.servicebus.common.message.DeferredMessage]
.. admonition:: Example:
.. literalinclude:: ../samples/sync_samples/test_examples.py
:start-after: [START settle_deferred_messages_service_bus]
:end-before: [END settle_deferred_messages_service_bus]
:language: python
:dedent: 8
:caption: Settle deferred messages.
"""
if (self.entity and self.requires_session) or kwargs.get('session'):
raise ValueError("Sessionful deferred messages can only be settled within a locked receive session.")
if settlement.lower() not in ['completed', 'suspended', 'abandoned']:
raise ValueError("Settlement must be one of: 'completed', 'suspended', 'abandoned'")
if not messages:
raise ValueError("At least one message must be specified.")
message = {
'disposition-status': settlement.lower(),
'lock-tokens': types.AMQPArray([m.lock_token for m in messages])}
with BaseHandler(self.entity_uri, self.auth_config, debug=self.debug, **kwargs) as handler:
return handler._mgmt_request_response( # pylint: disable=protected-access
REQUEST_RESPONSE_UPDATE_DISPOSTION_OPERATION,
message,
mgmt_handlers.default)
def receive_deferred_messages(self,
sequence_numbers,
mode=ReceiveSettleMode.PeekLock,
**kwargs):
"""Receive messages by sequence number that have been previously deferred.
When receiving deferred messages from a partitioned entity, all of the supplied
sequence numbers must be messages from the same partition.
:param sequence_numbers: A list of the sequence numbers of messages that have been
deferred.
:type sequence_numbers: list[int]
:param mode: The mode with which messages will be retrieved from the entity. The two options
are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given
lock period before they will be removed from the queue. Messages received with ReceiveAndDelete
will be immediately removed from the queue, and cannot be subsequently rejected or re-received if
the client fails to process the message. The default mode is PeekLock.
:type mode: ~azure.servicebus.common.constants.ReceiveSettleMode
:rtype: list[~azure.servicebus.common.message.Message]
Example:
.. literalinclude:: ../examples/test_examples.py
:start-after: [START receive_deferred_messages_service_bus]
:end-before: [END receive_deferred_messages_service_bus]
:language: python
:dedent: 8
:caption: Get the messages which were deferred using their sequence numbers
"""
if (self.entity and self.requires_session) or kwargs.get('session'):
raise ValueError(
"Sessionful deferred messages can only be received within a locked receive session."
)
if not sequence_numbers:
raise ValueError("At least one sequence number must be specified.")
try:
receive_mode = mode.value.value
except AttributeError:
receive_mode = int(mode)
message = {
'sequence-numbers':
types.AMQPArray([types.AMQPLong(s) for s in sequence_numbers]),
'receiver-settle-mode':
types.AMQPuInt(receive_mode)
}
mgmt_handler = functools.partial(mgmt_handlers.deferred_message_op,
mode=receive_mode)
with BaseHandler(self.entity_uri,
self.auth_config,
debug=self.debug,
**kwargs) as handler:
return handler._mgmt_request_response( # pylint: disable=protected-access
REQUEST_RESPONSE_RECEIVE_BY_SEQUENCE_NUMBER, message,
mgmt_handler)
def list_sessions(self,
updated_since=None,
max_results=100,
skip=0,
**kwargs):
"""List session IDs.
List the Session IDs with pending messages in the queue where the state of the session
has been updated since the timestamp provided. If no timestamp is provided, all will be returned.
If the state of a session has never been set, it will not be returned regardless of whether
there are messages pending.
:param updated_since: The UTC datetime from which to return updated pending Session IDs.
:type updated_since: datetime.datetime
:param max_results: The maximum number of Session IDs to return. Default value is 100.
:type max_results: int
:param skip: The page value to jump to. Default value is 0.
:type skip: int
:rtype: list[str]
Example:
.. literalinclude:: ../examples/test_examples.py
:start-after: [START list_sessions_service_bus]
:end-before: [END list_sessions_service_bus]
:language: python
:dedent: 4
:caption: Get the Ids of session which have messages pending in the queue
"""
if self.entity and not self.requires_session:
raise ValueError("This is not a sessionful entity.")
message = {
'last-updated-time':
updated_since or datetime.datetime.utcfromtimestamp(0),
'skip':
types.AMQPInt(skip),
'top':
types.AMQPInt(max_results),
}
with BaseHandler(self.entity_uri,
self.auth_config,
debug=self.debug,
**kwargs) as handler:
return handler._mgmt_request_response( # pylint: disable=protected-access
REQUEST_RESPONSE_GET_MESSAGE_SESSIONS_OPERATION, message,
mgmt_handlers.list_sessions_op)
def peek(self, count=1, start_from=0, session=None, **kwargs):
"""Browse messages currently pending in the queue.
Peeked messages are not removed from queue, nor are they locked. They cannot be completed,
deferred or dead-lettered.
:param count: The maximum number of messages to try and peek. The default
value is 1.
:type count: int
:param start_from: A message sequence number from which to start browsing messages.
:type start_from: int
:param session: If the entity requires sessions, a session ID must be supplied
in order that only messages from that session will be browsed. If the entity
does not require sessions this value will be ignored.
:type session: str
:rtype: list[~azure.servicebus.common.message.PeekMessage]
Example:
.. literalinclude:: ../examples/test_examples.py
:start-after: [START peek_messages_service_bus]
:end-before: [END peek_messages_service_bus]
:language: python
:dedent: 4
:caption: Look at specificied number of messages without removing them from queue
"""
message = {
'from-sequence-number': types.AMQPLong(start_from),
'message-count': int(count)
}
if self.entity and self.requires_session:
if not session:
raise ValueError("Sessions are required, please set session.")
message['session-id'] = session
with BaseHandler(self.entity_uri,
self.auth_config,
debug=self.debug,
**kwargs) as handler:
return handler._mgmt_request_response( # pylint: disable=protected-access
REQUEST_RESPONSE_PEEK_OPERATION, message,
mgmt_handlers.peek_op)