| 1 |
.. _sample_tutorial: |
| 2 |
|
| 3 |
A Sample Tutorial |
| 4 |
================= |
| 5 |
This tutorial will show you how to use Boto3 with an AWS service. In this |
| 6 |
sample tutorial, you will learn how to use Boto3 with |
| 7 |
`Amazon Simple Queue Service (SQS) <http://aws.amazon.com/documentation/sqs/>`_ |
| 8 |
|
| 9 |
SQS |
| 10 |
--- |
| 11 |
SQS allows you to queue and then process messages. This tutorial covers how to |
| 12 |
create a new queue, get and use an existing queue, push new messages onto the |
| 13 |
queue, and process messages from the queue by using |
| 14 |
:ref:`guide_resources` and :ref:`guide_collections`. |
| 15 |
|
| 16 |
Creating a queue |
| 17 |
---------------- |
| 18 |
Queues are created with a name. You may also optionally set queue |
| 19 |
attributes, such as the number of seconds to wait before an item may be |
| 20 |
processed. The examples below will use the queue name ``test``. |
| 21 |
Before creating a queue, you must first get the SQS service resource:: |
| 22 |
|
| 23 |
# Get the service resource |
| 24 |
sqs = boto3.resource('sqs') |
| 25 |
|
| 26 |
# Create the queue. This returns an SQS.Queue instance |
| 27 |
queue = sqs.create_queue(QueueName='test', Attributes={'DelaySeconds': '5'}) |
| 28 |
|
| 29 |
# You can now access identifiers and attributes |
| 30 |
print(queue.url) |
| 31 |
print(queue.attributes.get('DelaySeconds')) |
| 32 |
|
| 33 |
Reference: :py:meth:`SQS.ServiceResource.create_queue` |
| 34 |
|
| 35 |
.. warning:: |
| 36 |
|
| 37 |
The code above may throw an exception if you already have a queue named |
| 38 |
``test``. |
| 39 |
|
| 40 |
Using an existing queue |
| 41 |
----------------------- |
| 42 |
It is possible to look up a queue by its name. If the queue does not exist, |
| 43 |
then an exception will be thrown:: |
| 44 |
|
| 45 |
# Get the service resource |
| 46 |
sqs = boto3.resource('sqs') |
| 47 |
|
| 48 |
# Get the queue. This returns an SQS.Queue instance |
| 49 |
queue = sqs.get_queue_by_name(QueueName='test') |
| 50 |
|
| 51 |
# You can now access identifiers and attributes |
| 52 |
print(queue.url) |
| 53 |
print(queue.attributes.get('DelaySeconds')) |
| 54 |
|
| 55 |
It is also possible to list all of your existing queues:: |
| 56 |
|
| 57 |
# Print out each queue name, which is part of its ARN |
| 58 |
for queue in sqs.queues.all(): |
| 59 |
print(queue.url) |
| 60 |
|
| 61 |
.. note:: |
| 62 |
|
| 63 |
To get the name from a queue, you must use its ARN, which is available |
| 64 |
in the queue's ``attributes`` attribute. Using |
| 65 |
``queue.attributes['QueueArn'].split(':')[-1]`` will return its name. |
| 66 |
|
| 67 |
Reference: :py:meth:`SQS.ServiceResource.get_queue_by_name`, |
| 68 |
:py:attr:`SQS.ServiceResource.queues` |
| 69 |
|
| 70 |
Sending messages |
| 71 |
---------------- |
| 72 |
Sending a message adds it to the end of the queue:: |
| 73 |
|
| 74 |
# Get the service resource |
| 75 |
sqs = boto3.resource('sqs') |
| 76 |
|
| 77 |
# Get the queue |
| 78 |
queue = sqs.get_queue_by_name(QueueName='test') |
| 79 |
|
| 80 |
# Create a new message |
| 81 |
response = queue.send_message(MessageBody='world') |
| 82 |
|
| 83 |
# The response is NOT a resource, but gives you a message ID and MD5 |
| 84 |
print(response.get('MessageId')) |
| 85 |
print(response.get('MD5OfMessageBody')) |
| 86 |
|
| 87 |
You can also create messages with custom attributes:: |
| 88 |
|
| 89 |
queue.send_message(MessageBody='boto3', MessageAttributes={ |
| 90 |
'Author': { |
| 91 |
'StringValue': 'Daniel', |
| 92 |
'DataType': 'String' |
| 93 |
} |
| 94 |
}) |
| 95 |
|
| 96 |
Messages can also be sent in batches. For example, sending the two messages |
| 97 |
described above in a single request would look like the following:: |
| 98 |
|
| 99 |
response = queue.send_messages(Entries=[ |
| 100 |
{ |
| 101 |
'Id': '1', |
| 102 |
'MessageBody': 'world' |
| 103 |
}, |
| 104 |
{ |
| 105 |
'Id': '2', |
| 106 |
'MessageBody': 'boto3', |
| 107 |
'MessageAttributes': { |
| 108 |
'Author': { |
| 109 |
'StringValue': 'Daniel', |
| 110 |
'DataType': 'String' |
| 111 |
} |
| 112 |
} |
| 113 |
} |
| 114 |
]) |
| 115 |
|
| 116 |
# Print out any failures |
| 117 |
print(response.get('Failed')) |
| 118 |
|
| 119 |
In this case, the response contains lists of ``Successful`` and ``Failed`` |
| 120 |
messages, so you can retry failures if needed. |
| 121 |
|
| 122 |
Reference: :py:meth:`SQS.Queue.send_message`, |
| 123 |
:py:meth:`SQS.Queue.send_messages` |
| 124 |
|
| 125 |
Processing messages |
| 126 |
------------------- |
| 127 |
Messages are processed in batches:: |
| 128 |
|
| 129 |
# Get the service resource |
| 130 |
sqs = boto3.resource('sqs') |
| 131 |
|
| 132 |
# Get the queue |
| 133 |
queue = sqs.get_queue_by_name(QueueName='test') |
| 134 |
|
| 135 |
# Process messages by printing out body and optional author name |
| 136 |
for message in queue.receive_messages(MessageAttributeNames=['Author']): |
| 137 |
# Get the custom author message attribute if it was set |
| 138 |
author_text = '' |
| 139 |
if message.message_attributes is not None: |
| 140 |
author_name = message.message_attributes.get('Author').get('StringValue') |
| 141 |
if author_name: |
| 142 |
author_text = ' ({0})'.format(author_name) |
| 143 |
|
| 144 |
# Print out the body and author (if set) |
| 145 |
print('Hello, {0}!{1}'.format(message.body, author_text)) |
| 146 |
|
| 147 |
# Let the queue know that the message is processed |
| 148 |
message.delete() |
| 149 |
|
| 150 |
Given *only* the messages that were sent in a batch with |
| 151 |
:py:meth:`SQS.Queue.send_messages` in the previous section, the above code |
| 152 |
will print out:: |
| 153 |
|
| 154 |
Hello, world! |
| 155 |
Hello, boto3! (Daniel) |
| 156 |
|
| 157 |
Reference: :py:meth:`SQS.Queue.receive_messages`, |
| 158 |
:py:meth:`SQS.Message.delete` |