Debian Codegraph @

docs/source/guide/sqs.rst

raw
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`