# rabbitmq – Retrieve messages from an AMQP/AMQPS RabbitMQ queue

New in version 2.8.

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## Synopsis

- This lookup uses a basic get to retrieve all, or a limited number `count`, messages from a RabbitMQ queue.

## Requirements

The below requirements are needed on the local master node that executes this lookup.

- The python pika package https://pypi.org/project/pika/.

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
count - |  |  | How many messages to collect from the queue. If not set, defaults to retrieving all the messages from the queue.
queue - / required |  |  | The queue to get messages from.
url - / required |  |  | An URI connection string to connect to the AMQP/AMQPS RabbitMQ server. For more information refer to the URI spec https://www.rabbitmq.com/uri-spec.html.

## Notes

Note

- This lookup implements BlockingChannel.basic_get to get messages from a RabbitMQ server.

- After retrieving a message from the server, receipt of the message is acknowledged and the message on the server is deleted.

- Pika is a pure-Python implementation of the AMQP 0-9-1 protocol that tries to stay fairly independent of the underlying network support library.

- More information about pika can be found at https://pika.readthedocs.io/en/stable/.

- This plugin is tested against RabbitMQ. Other AMQP 0.9.1 protocol based servers may work but not tested/guaranteed.

- Assigning the return messages to a variable under `vars` may result in unexpected results as the lookup is evaluated every time the variable is referenced.

- Currently this plugin only handles text based messages from a queue. Unexpected results may occur when retrieving binary data.

## Examples

    - name: Get all messages off a queue
      debug:
        msg: "{{ lookup('rabbitmq', url='amqp://guest:guest@192.168.0.10:5672/%2F', queue='hello') }}"

    # If you are intending on using the returned messages as a variable in more than
    # one task (eg. debug, template), it is recommended to set_fact.

    - name: Get 2 messages off a queue and set a fact for re-use
      set_fact:
        messages: "{{ lookup('rabbitmq', url='amqp://guest:guest@192.168.0.10:5672/%2F', queue='hello', count=2) }}"

    - name: Dump out contents of the messages
      debug:
        var: messages

## Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key | Returned | Description
--- | --- | ---
_list list |  | A list of dictionaries with keys and value from the queue.
| content_type string |  | The content_type on the message in the queue.
| delivery_mode string |  | The delivery_mode on the message in the queue.
| delivery_tag string |  | The delivery_tag on the message in the queue.
| exchange string |  | The exchange the message came from.
| headers dictionary |  | The headers for the message returned from the queue.
| json dictionary |  | If application/json is specified in content_type, json will be loaded into variables.
| message_count string |  | The message_count for the message on the queue.
| msg string |  | The content of the message.
| redelivered boolean |  | The redelivered flag. True if the message has been delivered before.
| routing_key string |  | The routing_key on the message in the queue.

## Status

- This lookup is not guaranteed to have a backwards compatible interface. [preview]

- This lookup is maintained by the Ansible Community. [community]

### Authors

- John Imison <@Im0>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.