ReceiveClient Class
An AMQP client for receiving messages.
- Inheritance
-
ReceiveClient
Constructor
ReceiveClient(source, auth=None, client_name=None, debug=False, timeout=0, auto_complete=True, error_policy=None, **kwargs)Parameters
| Name | Description |
|---|---|
|
target
Required
|
The source AMQP service endpoint. This can either be the URI as a string or a ~uamqp.address.Source object. |
|
auth
|
Authentication for the connection. This should be one of the subclasses of uamqp.authentication.AMQPAuth. Currently this includes:
If no authentication is supplied, SASLAnnoymous will be used by default. default value: None
|
|
client_name
|
The name for the client, also known as the Container ID. If no name is provided, a random GUID will be used. default value: None
|
|
debug
|
Whether to turn on network trace logs. If True, trace logs will be logged at INFO level. Default is False. default value: False
|
|
timeout
|
A timeout in milliseconds. The receiver will shut down if no new messages are received after the specified timeout. If set to 0, the receiver will never timeout and will continue to listen. The default is 0. Set shutdown_after_timeout to False if keeping the receiver open after timeout is needed. default value: 0
|
|
shutdown_after_timeout
Required
|
Whether to automatically shutdown the receiver if no new messages are received after the specified timeout. Default is True. |
|
auto_complete
|
Whether to automatically settle message received via callback or via iterator. If the message has not been explicitly settled after processing the message will be accepted. Alternatively, when used with batch receive, this setting will determine whether the messages are pre-emptively settled during batching, or otherwise let to the user to be explicitly settled. default value: True
|
|
error_policy
|
A policy for parsing errors on link, connection and message disposition to determine whether the error should be retryable. default value: None
|
|
keep_alive_interval
Required
|
If set, a thread will be started to keep the connection alive during periods of user inactivity. The value will determine how long the thread will sleep (in seconds) between pinging the connection. If 0 or None, no thread will be started. |
|
send_settle_mode
Required
|
The mode by which to settle message send operations. If set to Unsettled, the client will wait for a confirmation from the service that the message was successfully sent. If set to 'Settled', the client will not wait for confirmation and assume success. |
|
receive_settle_mode
Required
|
The mode by which to settle message receive operations. If set to PeekLock, the receiver will lock a message once received until the client accepts or rejects the message. If set to ReceiveAndDelete, the service will assume successful receipt of the message and clear it from the queue. The default is PeekLock. |
|
desired_capabilities
Required
|
The extension capabilities desired from the peer endpoint. To create a desired_capabilities object, please do as follows:
|
|
max_message_size
Required
|
The maximum allowed message size negotiated for the Link. |
|
link_properties
Required
|
Metadata to be sent in the Link ATTACH frame. |
|
prefetch
Required
|
The receiver Link credit that determines how many messages the Link will attempt to handle per connection iteration. The default is 300. |
|
max_frame_size
Required
|
Maximum AMQP frame size. Default is 63488 bytes. |
|
channel_max
Required
|
Maximum number of Session channels in the Connection. |
|
idle_timeout
Required
|
Timeout in milliseconds after which the Connection will close if there is no further activity. |
|
properties
Required
|
Connection properties. |
|
remote_idle_timeout_empty_frame_send_ratio
Required
|
Ratio of empty frames to idle time for Connections with no activity. Value must be between 0.0 and 1.0 inclusive. Default is 0.5. |
|
incoming_window
Required
|
The size of the allowed window for incoming messages. |
|
outgoing_window
Required
|
The size of the allowed window for outgoing messages. |
|
handle_max
Required
|
The maximum number of concurrent link handles. |
|
on_attach
Required
|
A callback function to be run on receipt of an ATTACH frame. The function must take 4 arguments: source, target, properties and error. |
|
encoding
Required
|
The encoding to use for parameters supplied as strings. Default is 'UTF-8' |
|
source
Required
|
|
Methods
| auth_complete |
Whether the authentication handshake is complete during connection initialization. |
| client_ready |
Whether the handler has completed all start up processes such as establishing the connection, session, link and authentication, and is not ready to process messages. |
| close |
Close the client. This includes closing the Session and CBS authentication layer as well as the Connection. If the client was opened using an external Connection, this will be left intact. No further messages can be sent or received and the client cannot be re-opened. All pending, unsent messages will remain uncleared to allow them to be inspected and queued to a new client. |
| do_work |
Run a single connection iteration. This will return True if the connection is still open and ready to be used for further work, or False if it needs to be shut down. |
| mgmt_request |
Run a request/response operation. These are frequently used for management tasks against a $management node, however any node name can be specified and the available options will depend on the target service. |
| open |
Open the client. The client can create a new Connection or an existing Connection can be passed in. This existing Connection may have an existing CBS authentication Session, which will be used for this client as well. Otherwise a new Session will be created. |
| receive_message_batch |
Receive a batch of messages. Messages returned in the batch have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. This method will return as soon as some messages are available rather than waiting to achieve a specific batch size, and therefore the number of messages returned per call will vary up to the maximum allowed. If the receive client is configured with auto_complete=True then the messages received in the batch returned by this function will already be settled. Alternatively, if auto_complete=False, then each message will need to be explicitly settled before it expires and is released. |
| receive_messages |
Receive messages. This function will run indefinitely, until the client closes either via timeout, error or forced interruption (e.g. keyboard interrupt). If the receive client is configured with auto_complete=True then the messages that have not been settled on completion of the provided callback will automatically be accepted provided it has not expired. If an error occurs or the message has expired it will be released. Alternatively if auto_complete=False, each message will need to be explicitly settled during the callback, otherwise it will be released. |
| receive_messages_iter |
Receive messages by generator. Messages returned in the generator have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. |
| redirect |
Redirect the client endpoint using a Link DETACH redirect response. |
auth_complete
Whether the authentication handshake is complete during connection initialization.
auth_complete()Returns
| Type | Description |
|---|---|
client_ready
Whether the handler has completed all start up processes such as establishing the connection, session, link and authentication, and is not ready to process messages.
client_ready()Returns
| Type | Description |
|---|---|
close
Close the client. This includes closing the Session and CBS authentication layer as well as the Connection. If the client was opened using an external Connection, this will be left intact.
No further messages can be sent or received and the client cannot be re-opened.
All pending, unsent messages will remain uncleared to allow them to be inspected and queued to a new client.
close()do_work
Run a single connection iteration. This will return True if the connection is still open and ready to be used for further work, or False if it needs to be shut down.
do_work(**kwargs)Returns
| Type | Description |
|---|---|
Exceptions
| Type | Description |
|---|---|
|
TimeoutError or uamqp.errors.ClientTimeout if CBS authentication timeout reached.
|
mgmt_request
Run a request/response operation. These are frequently used for management tasks against a $management node, however any node name can be specified and the available options will depend on the target service.
mgmt_request(message, operation, op_type=None, node=None, callback=None, **kwargs)Parameters
| Name | Description |
|---|---|
|
message
Required
|
The message to send in the management request. |
|
operation
Required
|
The type of operation to be performed. This value will be service-specific, but common values include READ, CREATE and UPDATE. This value will be added as an application property on the message. |
|
op_type
|
The type on which to carry out the operation. This will be specific to the entities of the service. This value will be added as an application property on the message. default value: None
|
|
node
|
The target node. Default is b"$management". default value: None
|
|
timeout
Required
|
Provide an optional timeout in milliseconds within which a response to the management request must be received. |
|
callback
|
The function to process the returned parameters of the management request including status code and a description if available. This can be used to reformat the response or raise an error based on content. The function must take 3 arguments - status code, response message and description. default value: None
|
|
status_code_field
Required
|
Provide an alternate name for the status code in the response body which can vary between services due to the spec still being in draft. The default is b"statusCode". |
|
description_fields
Required
|
Provide an alternate name for the description in the response body which can vary between services due to the spec still being in draft. The default is b"statusDescription". |
Returns
| Type | Description |
|---|---|
open
Open the client. The client can create a new Connection or an existing Connection can be passed in. This existing Connection may have an existing CBS authentication Session, which will be used for this client as well. Otherwise a new Session will be created.
open(connection=None)Parameters
| Name | Description |
|---|---|
|
connection
|
An existing Connection that may be shared between multiple clients. default value: None
|
receive_message_batch
Receive a batch of messages. Messages returned in the batch have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. This method will return as soon as some messages are available rather than waiting to achieve a specific batch size, and therefore the number of messages returned per call will vary up to the maximum allowed.
If the receive client is configured with auto_complete=True then the messages received in the batch returned by this function will already be settled. Alternatively, if auto_complete=False, then each message will need to be explicitly settled before it expires and is released.
receive_message_batch(max_batch_size=None, on_message_received=None, timeout=0)Parameters
| Name | Description |
|---|---|
|
max_batch_size
|
The maximum number of messages that can be returned in one call. This value cannot be larger than the prefetch value, and if not specified, the prefetch value will be used. default value: None
|
|
on_message_received
|
A callback to process messages as they arrive from the service. It takes a single argument, a ~uamqp.message.Message object. default value: None
|
|
timeout
|
I timeout in milliseconds for which to wait to receive any messages. If no messages are received in this time, an empty list will be returned. If set to 0, the client will continue to wait until at least one message is received. The default is 0. default value: 0
|
receive_messages
Receive messages. This function will run indefinitely, until the client closes either via timeout, error or forced interruption (e.g. keyboard interrupt).
If the receive client is configured with auto_complete=True then the messages that have not been settled on completion of the provided callback will automatically be accepted provided it has not expired. If an error occurs or the message has expired it will be released. Alternatively if auto_complete=False, each message will need to be explicitly settled during the callback, otherwise it will be released.
receive_messages(on_message_received)Parameters
| Name | Description |
|---|---|
|
on_message_received
Required
|
A callback to process messages as they arrive from the service. It takes a single argument, a ~uamqp.message.Message object. |
receive_messages_iter
Receive messages by generator. Messages returned in the generator have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback.
receive_messages_iter(on_message_received=None)Parameters
| Name | Description |
|---|---|
|
on_message_received
|
A callback to process messages as they arrive from the service. It takes a single argument, a ~uamqp.message.Message object. default value: None
|
redirect
Redirect the client endpoint using a Link DETACH redirect response.
redirect(redirect, auth)Parameters
| Name | Description |
|---|---|
|
redirect
Required
|
The Link DETACH redirect details. |
|
auth
Required
|
Authentication credentials to the redirected endpoint. |
Azure SDK for Python
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for