# Using APIs with Amazon SQS Using APIs This topic provides information about constructing Amazon SQS endpoints, making query API requests using the GET and POST methods, and using batch API actions. For detailed information about Amazon SQS [actions](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html)—including parameters, errors, examples, and [data types](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Types.html), see the [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/). To access Amazon SQS using a variety of programming languages, you can also use [AWS SDKs](https://aws.amazon.com/tools/#sdk), which contain the following automatic functionality: + Cryptographically signing your service requests + Retrying requests + Handling error responses For more information, see [Using Amazon SQS with an AWS SDK](sdk-general-information-section.md). For command line tool information, see the Amazon SQS sections in the [https://docs.aws.amazon.com/cli/latest/reference/sqs/index.html](https://docs.aws.amazon.com/cli/latest/reference/sqs/index.html) and the [https://docs.aws.amazon.com/powershell/latest/reference/](https://docs.aws.amazon.com/powershell/latest/reference/). **Amazon SQS APIs with AWS JSON protocol** Amazon SQS uses AWS JSON protocol as the transport mechanism for all Amazon SQS APIs on the specified [AWS SDK versions](sqs-json-faqs.md#json-protocol-getting-started). AWS JSON protocol provides a higher throughput, lower latency, and faster application-to-application communication. AWS JSON protocol is more efficient in serialization/deserialization of requests and responses when compared to AWS query protocol. If you still prefer to use the AWS query protocol with SQS APIs, see [What languages are supported for AWS JSON protocol used in Amazon SQS APIs?](sqs-json-faqs.md#json-protocol-supported-languages) for the AWS SDK versions that support Amazon SQS AWS query protocol. Amazon SQS uses AWS JSON protocol to communicate between AWS SDK clients (for example, Java, Python, Golang, JavaScript) and the Amazon SQS server. An HTTP request of an Amazon SQS API operation accepts JSON formatted input. The Amazon SQS operation is executed, and the execution response is sent back to the SDK client in JSON format. Compared to AWS query, AWS JSON is simpler, faster, and more efficient to transport data between client and server. + AWS JSON protocol acts as a mediator between the Amazon SQS client and server. + The server doesn’t understand the programming language in which the Amazon SQS operation is created, but it understands the AWS JSON protocol. + The AWS JSON protocol uses the serialization (convert object to JSON format) and de-serialization (convert JSON format to object) between Amazon SQS client and server. For more information about AWS JSON protocol with Amazon SQS, see [Amazon SQS AWS JSON protocol FAQs](sqs-json-faqs.md). AWS JSON protocol is available on the specified [AWS SDK version](sqs-json-faqs.md#json-protocol-getting-started). To review SDK version and release dates across language variants, see the [AWS SDKs and Tools version support matrix](https://docs.aws.amazon.com/sdkref/latest/guide/version-support-matrix.html) in the *AWS SDKs and Tools Reference Guide* # Making query API requests using AWS JSON protocol in Amazon SQS Making query API requests using AWS JSON protocol This topic explains how to construct an Amazon SQS endpoint, make POST requests, and interpret responses. **Note** AWS JSON protocol is supported for most language variants. For a full list of supported language variants, see [What languages are supported for AWS JSON protocol used in Amazon SQS APIs?](sqs-json-faqs.md#json-protocol-supported-languages). ## Constructing an endpoint To work with Amazon SQS queues, you must construct an endpoint. For information about Amazon SQS endpoints, see the following pages in the *Amazon Web Services General Reference*: + [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) + [Amazon Simple Queue Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/sqs-service) Every Amazon SQS endpoint is independent. For example, if two queues are named *MyQueue* and one has the endpoint `sqs.us-east-2.amazonaws.com` while the other has the endpoint `sqs.eu-west-2.amazonaws.com`, the two queues don't share any data with each other. The following is an example of an endpoint that makes a request to create a queue. ``` POST / HTTP/1.1 Host: sqs.us-west-2.amazonaws.com X-Amz-Target: AmazonSQS.CreateQueue X-Amz-Date: Content-Type: application/x-amz-json-1.0 Authorization: Content-Length: Connection: Keep-Alive { "QueueName":"MyQueue", "Attributes": { "VisibilityTimeout": "40" }, "tags": { "QueueType": "Production" } } ``` **Note** Queue names and queue URLs are case sensitive. The structure of *`AUTHPARAMS`* depends on the signature of the API request. For more information, see [Signing AWS API Requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) in the *Amazon Web Services General Reference*. ## Making a POST request An Amazon SQS POST request sends query parameters as a form in the body of an HTTP request. The following is an example of an HTTP header with `X-Amz-Target` set to `AmazonSQS.`, and an HTTP header with `Content-Type` set to `application/x-amz-json-1.0`. ``` POST / HTTP/1.1 Host: sqs.. X-Amz-Target: AmazonSQS.SendMessage X-Amz-Date: Content-Type: application/x-amz-json-1.0 Authorization: Content-Length: Connection: Keep-Alive { "QueueUrl": "https://sqs..///", "MessageBody": "This is a test message" } ``` This HTTP POST request sends a message to an Amazon SQS queue. **Note** Both HTTP headers `X-Amz-Target` and `Content-Type` are required. Your HTTP client might add other items to the HTTP request, according to the client's HTTP version. # Interpreting Amazon SQS JSON API responses When you send a request to Amazon SQS, it returns a JSON response with the results. The response structure depends on the API action you used. To understand the details of these responses, see: + The specific API action in the [API actions](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html) in the *Amazon Simple Queue Service API Reference* + The [Amazon SQS AWS JSON protocol FAQs](sqs-json-faqs.md) ## Successful JSON response structure If the request is successful, the main response element is `x-amzn-RequestId`, which contains the Universal Unique Identifier (UUID) of the request, as well as other appended response field(s). For example, the following [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html) response contains the `QueueUrl` field, which, in turn, contains the URL of the created queue. ``` HTTP/1.1 200 OK x-amzn-RequestId: Content-Length: Date: Content-Type: application/x-amz-json-1.0 { "QueueUrl":"https://sqs.us-east-1.amazonaws.com/111122223333/MyQueue" } ``` ## JSON error response structure If a request is unsuccessful, Amazon SQS returns the main response, including the HTTP header and the body. In the HTTP header, `x-amzn-RequestId` contains the UUID of the request. `x-amzn-query-error` contains two pieces of information: the type of error, and whether the error was a producer or consumer error. In the response body, `"__type"` indicates other error details, and `Message` indicates the error condition in a readable format. The following is an example error response in JSON format: ``` HTTP/1.1 400 Bad Request x-amzn-RequestId: 66916324-67ca-54bb-a410-3f567a7a0571 x-amzn-query-error: AWS.SimpleQueueService.NonExistentQueue;Sender Content-Length: Date: Content-Type: application/x-amz-json-1.0 { "__type": "com.amazonaws.sqs#QueueDoesNotExist", "message": "The specified queue does not exist." } ``` # Amazon SQS AWS JSON protocol FAQs This topic covers frequently asked questions about using AWS JSON protocol with Amazon SQS. ## What is AWS JSON protocol, and how does it differ from existing Amazon SQS API requests and responses? JSON is one of the most widely used and accepted wiring methods for communication between heterogeneous systems. Amazon SQS uses JSON as a medium to communicate between an AWS SDK client (for example, Java, Python, Golang, JavaScript) and Amazon SQS server. An HTTP request of an Amazon SQS API operation accepts input in the form of JSON. The Amazon SQS operation is executed and the response of execution is shared back to the SDK client in the form of JSON. Compared to AWS query, JSON is more efficient at transporting data between client and server. + Amazon SQS AWS JSON protocol acts as a mediator between Amazon SQS client and server. + The server doesn’t understand the programming language in which the Amazon SQS operation is created, but it understands the AWS JSON protocol. + The Amazon SQS AWS JSON protocol uses the serialization (convert object to JSON format) and deserialization (convert JSON format to object) between the Amazon SQS client and server. ## How do I get started with AWS JSON protocols for Amazon SQS? To get started with the latest AWS SDK version to achieve faster messaging for Amazon SQS, upgrade your AWS SDK to the specified version or any subsequent version. To learn more about SDK clients, see the Guide column in the table below. The following is a list of SDK versions across language variants for AWS JSON protocol for use with Amazon SQS APIs: | Language | SDK client repository | Required SDK client version | Guide | | --- | --- | --- | --- | | C\$1\$1 | [aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) | [1.11.98](https://github.com/aws/aws-sdk-cpp/releases/tag/1.11.198) | [AWS SDK for C\$1\$1](https://aws.amazon.com/sdk-for-cpp/) | | Golang 1.x | [aws/aws-sdk-go](https://github.com/aws/aws-sdk-go) | [v1.47.7](https://github.com/aws/aws-sdk-go/releases/tag/v1.47.7) | [AWS SDK for Go](https://aws.amazon.com/sdk-for-go/) | | Golang 2.x | [aws/aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2) | [v1.28.0](https://github.com/aws/aws-sdk-go-v2/blob/release-2023-11-09/service/sqs/CHANGELOG.md#v1270-2023-11-09) | [AWS SDK for Go V2](https://aws.github.io/aws-sdk-go-v2/docs/) | | Java 1.x | [aws/aws-sdk-java](https://github.com/aws/aws-sdk-java) | [1.12.585](https://github.com/aws/aws-sdk-java/releases/tag/1.12.585) | [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/) | | Java 2.x | [aws/aws-sdk-java-v2](https://github.com/aws/aws-sdk-java-v2) | [2.21.19](https://github.com/aws/aws-sdk-java-v2/releases/tag/2.21.19) | [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/) | | JavaScript v2.x | [aws/aws-sdk-js](https://github.com/aws/aws-sdk-js) | [JavaScript on AWS](https://aws.amazon.com/developer/language/javascript/) | | JavaScript v3.x | [aws/aws-sdk-js-v3](https://github.com/aws/aws-sdk-js-v3) | [v3.447.0](https://github.com/aws/aws-sdk-js-v3/releases/tag/v3.447.0) | [JavaScript on AWS](https://aws.amazon.com/developer/language/javascript/) | | .NET | [aws/aws-sdk-net](https://github.com/aws/aws-sdk-net) | [3.7.681.0](https://github.com/aws/aws-sdk-net/releases/tag/3.7.681.0) | [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/) | | PHP | [aws/aws-sdk-php](https://github.com/aws/aws-sdk-php) | [3.285.2](https://github.com/aws/aws-sdk-php/releases/tag/3.285.2) | [AWS SDK for PHP](https://aws.amazon.com/sdk-for-php/) | | Python-boto3 | [boto/boto3](https://github.com/boto/boto3) | [1.28.82](https://github.com/boto/boto3/releases/tag/1.28.82) | [AWS SDK for Python (Boto3)](https://aws.amazon.com/sdk-for-python/) | | Python-botocore | [boto/botocore](https://github.com/boto/botocore/) | [1.31.82](https://github.com/boto/botocore/releases/tag/1.31.82) | [AWS SDK for Python (Boto3)](https://aws.amazon.com/sdk-for-python/) | | awscli | [AWS CLI](https://github.com/aws/aws-cli) | [1.29.82](https://github.com/aws/aws-cli/releases/tag/1.29.82) | [AWSCommand Line Interface](https://aws.amazon.com/cli/) | | Ruby | [aws/aws-sdk-ruby](https://github.com/aws/aws-sdk-ruby) | [1.67.0](https://rubygems.org/gems/aws-sdk-sqs/versions/1.67.0) | [AWS SDK for Ruby](https://aws.amazon.com/sdk-for-ruby/) | ## What are the risks of enabling JSON protocol for my Amazon SQS workloads? If you are using a custom implementation of AWS SDK or a combination of custom clients and AWS SDK to interact with Amazon SQS that generates AWS Query based (aka XML-based) responses, it may be incompatible with AWS JSON protocol. If you encounter any issues, contact AWS Support. ## What if I am already on the latest AWS SDK version, but my open sourced solution does not support JSON? You must change your SDK version to the version previous to what you are using. See [How do I get started with AWS JSON protocols for Amazon SQS?](#json-protocol-getting-started) for more information. AWS SDK versions listed in [How do I get started with AWS JSON protocols for Amazon SQS?](#json-protocol-getting-started) uses JSON wire protocol for Amazon SQS APIs. If you change your AWS SDK to the previous version, your Amazon SQS APIs will use the AWS query. ## What languages are supported for AWS JSON protocol used in Amazon SQS APIs? Amazon SQS supports all language variants where AWS SDKs are generally available (GA). Currently, we don't support Kotlin, Rust, or Swift. To learn more about other language variants, see [Tools to Build on AWS](https://aws.amazon.com/developer/tools/). ## What regions are supported for AWS JSON protocol used in Amazon SQS APIs Amazon SQS supports AWS JSON protocol in all [AWS regions](https://docs.aws.amazon.com/general/latest/gr/sqs-service.html) where Amazon SQS is available. ## What latency improvements can I expect when upgrading to the specified AWS SDK versions for Amazon SQS using the AWS JSON protocol? AWS JSON protocol is more efficient at serialization and deserialization of requests and responses when compared to AWS query protocol. Based on AWS performance tests for a 5 KB message payload, JSON protocol for Amazon SQS reduces end-to-end message processing latency by up to 23%, and reduces application client side CPU and memory usage. ## Will AWS query protocol be deprecated? AWS query protocol will continue to be supported. You can continue using AWS query protocol as long as your AWS SDK version is set any previous version other that what is listed in [How do I get started with AWS JSON protocols for Amazon SQS](#json-protocol-getting-started). ## Where can I find more information about AWS JSON protocol? You can find more information about JSON protocol at [AWS JSON 1.0 protocol](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html) in the *Smithy* documentation. For more about Amazon SQS API requests using AWS JSON protocol, see [Making query API requests using AWS JSON protocol in Amazon SQS](sqs-making-api-requests-json.md). # Making query API requests using AWS query protocol in Amazon SQS Making query API requests using AWS query protocol This topic explains how to construct an Amazon SQS endpoint, make GET and POST requests, and interpret responses. ## Constructing an endpoint In order to work with Amazon SQS queues, you must construct an endpoint. For information about Amazon SQS endpoints, see the following pages in the *Amazon Web Services General Reference*: + [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#sqs_region) + [Amazon Simple Queue Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/sqs-service) Every Amazon SQS endpoint is independent. For example, if two queues are named *MyQueue* and one has the endpoint `sqs.us-east-2.amazonaws.com` while the other has the endpoint `sqs.eu-west-2.amazonaws.com`, the two queues don't share any data with each other. The following is an example of an endpoint which makes a request to create a queue. ``` https://sqs.eu-west-2.amazonaws.com/ ?Action=CreateQueue &DefaultVisibilityTimeout=40 &QueueName=MyQueue &Version=2012-11-05 &AUTHPARAMS ``` **Note** Queue names and queue URLs are case sensitive. The structure of *`AUTHPARAMS`* depends on the signature of the API request. For more information, see [Signing AWS API Requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) in the *Amazon Web Services General Reference*. ## Making a GET request An Amazon SQS GET request is structured as a URL which consists of the following: + **Endpoint** – The resource that the request is acting on (the [queue name and URL](sqs-queue-message-identifiers.md#queue-name-url)), for example: `https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue` + **Action** – The [action](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html) that you want to perform on the endpoint. A question mark (`?`) separates the endpoint from the action, for example: `?Action=SendMessage&MessageBody=Your%20Message%20Text` + **Parameters** – Any request parameters. Each parameter is separated by an ampersand (`&`), for example: `&Version=2012-11-05&AUTHPARAMS` The following is an example of a GET request that sends a message to an Amazon SQS queue. ``` https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue ?Action=SendMessage&MessageBody=Your%20message%20text &Version=2012-11-05 &AUTHPARAMS ``` **Note** Queue names and queue URLs are case sensitive. Because GET requests are URLs, you must URL-encode all parameter values. Because spaces aren't allowed in URLs, each space is URL-encoded as `%20`. The rest of the example isn't URL-encoded to make it easier to read. ## Making a POST request An Amazon SQS POST request sends query parameters as a form in the body of an HTTP request. The following is an example of an HTTP header with `Content-Type` set to `application/x-www-form-urlencoded`. ``` POST /123456789012/MyQueue HTTP/1.1 Host: sqs.us-east-2.amazonaws.com Content-Type: application/x-www-form-urlencoded ``` The header is followed by a `[form-urlencoded](https://www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2)` GET request that sends a message to an Amazon SQS queue. Each parameter is separated by an ampersand (`&`). ``` Action=SendMessage &MessageBody=Your+Message+Text &Expires=2020-10-15T12%3A00%3A00Z &Version=2012-11-05 &AUTHPARAMS ``` **Note** Only the `Content-Type` HTTP header is required. The `AUTHPARAMS` is the same as for the GET request. Your HTTP client might add other items to the HTTP request, according to the client's HTTP version. # Interpreting Amazon SQS XML API responses When you send a request to Amazon SQS, it returns an XML response containing the results of the request. To understand the structure and details of these responses, refer to the specific [API actions](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html) in the *Amazon Simple Queue Service API Reference*. ## Successful XML response structure If the request is successful, the main response element is named after the action, with `Response` appended (for example, `ActionNameResponse`). This element contains the following child elements: + **`ActionNameResult`** – Contains an action-specific element. For example, the `CreateQueueResult` element contains the `QueueUrl` element which, in turn, contains the URL of the created queue. + **`ResponseMetadata`** – Contains the `RequestId` which, in turn, contains the Universal Unique Identifier (UUID) of the request. The following is an example successful response in XML format: ``` https://sqs.us-east-2.amazonaws.com/770098461991/queue2 cb919c0a-9bce-4afe-9b48-9bdf2412bb67 ``` ## XML error response structure If a request is unsuccessful, Amazon SQS always returns the main response element `ErrorResponse`. This element contains an `Error` element and a `RequestId` element. The `Error` element contains the following child elements: + **`Type`** – Specifies whether the error was a producer or consumer error. + **`Code`** – Specifies the type of error. + **`Message`** – Specifies the error condition in a readable format. + **`Detail`** – (Optional) Specifies additional details about the error. The `RequestId` element contains the UUID of the request. The following is an example error response in XML format: ``` Sender InvalidParameterValue Value (quename_nonalpha) for parameter QueueName is invalid. Must be an alphanumeric String of 1 to 80 in length. 42d59b56-7407-4c4a-be0f-4c88daeea257 ``` # Authenticating requests for Amazon SQS Authenticating requests Authentication is the process of identifying and verifying the party that sends a request. During the first stage of authentication, AWS verifies the identity of the producer and whether the producer is [registered to use AWS](https://aws.amazon.com/) (for more information, see [Step 1: Create an AWS account and IAM user](sqs-setting-up.md#sqs-creating-aws-account)). Next, AWS abides by the following procedure: 1. The producer (sender) obtains the necessary credential. 1. The producer sends a request and the credential to the consumer (receiver). 1. The consumer uses the credential to verify whether the producer sent the request. 1. One of the following happens: + If authentication succeeds, the consumer processes the request. + If authentication fails, the consumer rejects the request and returns an error. ## Basic authentication process with HMAC-SHA When you access Amazon SQS using the Query API, you must provide the following items to authenticate your request: + The **AWS Access Key ID** that identifies your AWS account, which AWS uses to look up your Secret Access Key. + The **HMAC-SHA request signature**, calculated using your Secret Access Key (a shared secret known only to you and AWS—for more information, see [RFC2104](http://www.faqs.org/rfcs/rfc2104.html)). The [AWS SDK](https://aws.amazon.com/code/) handles the signing process; however, if you submit a query request over HTTP or HTTPS, you must include a signature in every query request. 1. Derive a Signature Version 4 Signing Key. For more information, see [Deriving the Signing Key with Java](https://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html#signature-v4-examples-java). **Note** Amazon SQS supports Signature Version 4, which provides improved SHA256-based security and performance over previous versions. When you create new applications that use Amazon SQS, use Signature Version 4. 1. Base64-encode the request signature. The following sample Java code does this: ``` package amazon.webservices.common; // Define common routines for encoding data in AWS requests. public class Encoding { /* Perform base64 encoding of input bytes. * rawData is the array of bytes to be encoded. * return is the base64-encoded string representation of rawData. */ public static String EncodeBase64(byte[] rawData) { return Base64.encodeBytes(rawData); } } ``` + The **timestamp (or expiration)** of the request. The timestamp that you use in the request must be a `dateTime` object, with [the complete date, including hours, minutes, and seconds](http://www.w3.org/TR/xmlschema-2/#dateTime). For example: `2007-01-31T23:59:59Z` Although this isn't required, we recommend providing the object using the Coordinated Universal Time (Greenwich Mean Time) time zone. **Note** Make sure that your server time is set correctly. If you specify a timestamp (rather than an expiration), the request automatically expires 15 minutes after the specified time (AWS doesn't process requests with timestamps more than 15 minutes earlier than the current time on AWS servers). If you use .NET, you must not send overly specific timestamps (because of different interpretations of how extra time precision should be dropped). In this case, you should manually construct `dateTime` objects with precision of no more than one millisecond. ## Part 1: The request from the user The following is the process you must follow to authenticate AWS requests using an HMAC-SHA request signature. ![\[Diagram describing the request from the user.\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/images/sqs-basic-authentication-process-hmac-user.png) 1. Construct a request to AWS. 1. Calculate a keyed-hash message authentication code (HMAC-SHA) signature using your Secret Access Key. 1. Include the signature and your Access Key ID in the request, and then send the request to AWS. ## Part 2: The response from AWS AWS begins the following process in response. ![\[Diagram describing the response from AWS.\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/images/sqs-basic-authentication-process-hmac-aws.png) 1. AWS uses the Access Key ID to look up your Secret Access Key. 1. AWS generates a signature from the request data and the Secret Access Key, using the same algorithm that you used to calculate the signature you sent in the request. 1. One of the following happens: + If the signature that AWS generates matches the one you send in the request, AWS considers the request to be authentic. + If the comparison fails, the request is discarded, and AWS returns an error. # Amazon SQS batch actions Batch actions Amazon SQS provides batch actions to help you reduce costs and manipulate up to 10 messages with a single action. These batch actions include: + `[SendMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)` + `[DeleteMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessageBatch.html)` + `[ChangeMessageVisibilityBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibilityBatch.html)` Using batch actions, you can perform multiple operations in a single API call, which helps optimize performance and reduce costs. You can take advantage of batch functionality using the query API or any AWS SDK that supports Amazon SQS batch actions. **Important Details** + **Message Size Limit:** The total size of all messages sent in a single `SendMessageBatch` call cannot exceed 1,048,576 bytes (1 MiB) + **Permissions:** You cannot set permissions explicitly for `SendMessageBatch`, `DeleteMessageBatch`, or `ChangeMessageVisibilityBatch`. Instead, setting permissions for `SendMessage`, `DeleteMessage`, or `ChangeMessageVisibility` sets permissions for the corresponding batch versions of the actions. + **Console Support:** The Amazon SQS console does not support batch actions. You must use the query API or an AWS SDK to perform batch operations. ## Batching message actions To further optimize costs and efficiency, consider the following best practices for batching message actions: + **Batch API Actions:** Use the [Amazon SQS batch API actions](#sqs-batch-api-actions) actions to send, receive, and delete messages, and to change the message visibility timeout for multiple messages with a single action. This reduces the number of API calls and associated costs. + **Client-Side Buffering and Long Polling:** Combine client-side buffering with request batching by using long polling together with the [ buffered asynchronous client](sqs-client-side-buffering-request-batching.md) included with the AWS SDK for Java. This approach helps to minimize the number of requests and optimizes the handling of large volumes of messages. **Note** The Amazon SQS Buffered Asynchronous Client doesn't currently support FIFO queues. # Enabling client-side buffering and request batching with Amazon SQS The [AWS SDK for Java](https://aws.amazon.com/sdkforjava/) includes `AmazonSQSBufferedAsyncClient` which accesses Amazon SQS. This client allows for simple request batching using client-side buffering. Calls made from the client are first buffered and then sent as a batch request to Amazon SQS. Client-side buffering allows up to 10 requests to be buffered and sent as a batch request, decreasing your cost of using Amazon SQS and reducing the number of sent requests. `AmazonSQSBufferedAsyncClient` buffers both synchronous and asynchronous calls. Batched requests and support for [long polling](sqs-short-and-long-polling.md) can also help increase throughput. For more information, see [Increasing throughput using horizontal scaling and action batching with Amazon SQS](sqs-throughput-horizontal-scaling-and-batching.md). Because `AmazonSQSBufferedAsyncClient` implements the same interface as `AmazonSQSAsyncClient`, migrating from `AmazonSQSAsyncClient` to `AmazonSQSBufferedAsyncClient` typically requires only minimal changes to your existing code. **Note** The Amazon SQS Buffered Asynchronous Client doesn't currently support FIFO queues. ## Using AmazonSQSBufferedAsyncClient Before you begin, complete the steps in [Setting up Amazon SQS](sqs-setting-up.md). ### AWS SDK for Java 1.x For AWS SDK for Java 1.x, you can create a new `AmazonSQSBufferedAsyncClient` based on the following example: ``` // Create the basic Amazon SQS async client final AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient(); // Create the buffered client final AmazonSQSAsync bufferedSqs = new AmazonSQSBufferedAsyncClient(sqsAsync); ``` After you create the new `AmazonSQSBufferedAsyncClient`, you can use it to send multiple requests to Amazon SQS (just as you can with `AmazonSQSAsyncClient`), for example: ``` final CreateQueueRequest createRequest = new CreateQueueRequest().withQueueName("MyQueue"); final CreateQueueResult res = bufferedSqs.createQueue(createRequest); final SendMessageRequest request = new SendMessageRequest(); final String body = "Your message text" + System.currentTimeMillis(); request.setMessageBody( body ); request.setQueueUrl(res.getQueueUrl()); final Future sendResult = bufferedSqs.sendMessageAsync(request); final ReceiveMessageRequest receiveRq = new ReceiveMessageRequest() .withMaxNumberOfMessages(1) .withQueueUrl(queueUrl); final ReceiveMessageResult rx = bufferedSqs.receiveMessage(receiveRq); ``` ### Configuring AmazonSQSBufferedAsyncClient `AmazonSQSBufferedAsyncClient` is preconfigured with settings that work for most use cases. You can further configure `AmazonSQSBufferedAsyncClient`, for example: 1. Create an instance of the `QueueBufferConfig` class with the required configuration parameters. 1. Provide the instance to the `AmazonSQSBufferedAsyncClient` constructor. ``` // Create the basic Amazon SQS async client final AmazonSQSAsync sqsAsync = new AmazonSQSAsyncClient(); final QueueBufferConfig config = new QueueBufferConfig() .withMaxInflightReceiveBatches(5) .withMaxDoneReceiveBatches(15); // Create the buffered client final AmazonSQSAsync bufferedSqs = new AmazonSQSBufferedAsyncClient(sqsAsync, config); ``` **QueueBufferConfig configuration parameters** | Parameter | Default value | Description | | --- | --- | --- | | longPoll | true | When `longPoll` is set to `true`, `AmazonSQSBufferedAsyncClient` attempts to use long polling when it consumes messages. | | longPollWaitTimeoutSeconds | 20 s | The maximum amount of time (in seconds) which a `ReceiveMessage` call blocks off on the server, waiting for messages to appear in the queue before returning with an empty receive result. When long polling is disabled, this setting has no effect. | | maxBatchOpenMs | 200 ms | The maximum amount of time (in milliseconds) that an outgoing call waits for other calls with which it batches messages of the same type. The higher the setting, the fewer batches are required to perform the same amount of work (however, the first call in a batch has to spend a longer time waiting). When you set this parameter to `0`, submitted requests don't wait for other requests, effectively disabling batching. | | maxBatchSize | 10 requests per batch | The maximum number of messages that are batched together in a single request. The higher the setting, the fewer batches are required to carry out the same number of requests. 10 requests per batch is the maximum allowed value for Amazon SQS. | | maxBatchSizeBytes | 1 MiB | The maximum size of a message batch, in bytes, that the client attempts to send to Amazon SQS. 1 MiB is the maximum allowed value for Amazon SQS. | | maxDoneReceiveBatches | 10 batches | The maximum number of receive batches that `AmazonSQSBufferedAsyncClient` prefetches and stores client-side. The higher the setting, the more receive requests can be satisfied without having to make a call to Amazon SQS (however, the more messages are prefetched, the longer they remain in the buffer, causing their own visibility timeout to expire). `0` indicates that all message pre-fetching is disabled and messages are consumed only on demand. | | maxInflightOutboundBatches | 5 batches | The maximum number of active outbound batches that can be processed at the same time. The higher the setting, the faster outbound batches can be sent (subject to quotas such as CPU or bandwidth) and the more threads are consumed by `AmazonSQSBufferedAsyncClient`. | | maxInflightReceiveBatches | 10 batches | The maximum number of active receive batches that can be processed at the same time. The higher the setting, the more messages can be received (subject to quotas such as CPU or bandwidth), and the more threads are consumed by `AmazonSQSBufferedAsyncClient`. `0` indicates that all message pre-fetching is disabled and messages are consumed only on demand. | | visibilityTimeoutSeconds | -1 | When this parameter is set to a positive, non-zero value, the visibility timeout set here overrides the visibility timeout set on the queue from which messages are consumed. `-1` indicates that the default setting is selected for the queue. You can't set visibility timeout to `0`. | ### AWS SDK for Java 2.x For AWS SDK for Java 2.x, you can create a new `SqsAsyncBatchManager` based on the following example: ``` // Create the basic Sqs Async Client SqsAsyncClient sqs = SqsAsyncClient.builder() .region(Region.US_EAST_1) .build(); // Create the batch manager SqsAsyncBatchManager sqsAsyncBatchManager = sqs.batchManager(); ``` After you create the new `SqsAsyncBatchManager`, you can use it to send multiple requests to Amazon SQS (just as you can with `SqsAsyncClient`), for example: ``` final String queueName = "MyAsyncBufferedQueue" + UUID.randomUUID(); final CreateQueueRequest request = CreateQueueRequest.builder().queueName(queueName).build(); final String queueUrl = sqs.createQueue(request).join().queueUrl(); System.out.println("Queue created: " + queueUrl); // Send messages CompletableFuture sendMessageFuture; for (int i = 0; i < 10; i++) { final int index = i; sendMessageFuture = sqsAsyncBatchManager.sendMessage( r -> r.messageBody("Message " + index).queueUrl(queueUrl)); SendMessageResponse response= sendMessageFuture.join(); System.out.println("Message " + response.messageId() + " sent!"); } // Receive messages with customized configurations CompletableFuture receiveResponseFuture = customizedBatchManager.receiveMessage( r -> r.queueUrl(queueUrl) .waitTimeSeconds(10) .visibilityTimeout(20) .maxNumberOfMessages(10) ); System.out.println("You have received " + receiveResponseFuture.join().messages().size() + " messages in total."); // Delete messages DeleteQueueRequest deleteQueueRequest = DeleteQueueRequest.builder().queueUrl(queueUrl).build(); int code = sqs.deleteQueue(deleteQueueRequest).join().sdkHttpResponse().statusCode(); System.out.println("Queue is deleted, with statusCode " + code); ``` ### Configuring SqsAsyncBatchManager `SqsAsyncBatchManager` is preconfigured with settings that work for most use cases. You can further configure `SqsAsyncBatchManager`, for example: Creating custom configuration via `SqsAsyncBatchManager.Builder`: ``` SqsAsyncBatchManager customizedBatchManager = SqsAsyncBatchManager.builder() .client(sqs) .scheduledExecutor(Executors.newScheduledThreadPool(5)) .overrideConfiguration(b -> b .maxBatchSize(10) .sendRequestFrequency(Duration.ofMillis(200)) .receiveMessageMinWaitDuration(Duration.ofSeconds(10)) .receiveMessageVisibilityTimeout(Duration.ofSeconds(20)) .receiveMessageAttributeNames(Collections.singletonList("*")) .receiveMessageSystemAttributeNames(Collections.singletonList(MessageSystemAttributeName.ALL))) .build(); ``` **`BatchOverrideConfiguration` parameters** | Parameter | Default value | Description | | --- | --- | --- | | maxBatchSize | 10 requests per batch | The maximum number of messages that are batched together in a single request. The higher the setting, the fewer batches are required to carry out the same number of requests. The maximum allowed value for Amazon SQS is 10 requests per batch. | | sendRequestFrequency | 200 ms | The maximum amount of time (in milliseconds) that an outgoing call waits for other calls with which it batches messages of the same type. The higher the setting, the fewer batches are required to perform the same amount of work (however, the first call in a batch has to spend a longer time waiting). When you set this parameter to `0`, submitted requests don't wait for other requests, effectively disabling batching. | | receiveMessageVisibilityTimeout | -1 | When this parameter is set to a positive, non-zero value, the visibility timeout set here overrides the visibility timeout set on the queue from which messages are consumed. `1` indicates that the default setting is selected for the queue. You can't set visibility timeout to `0`. | | receiveMessageMinWaitDuration | 50 ms | The minimal amount of time (in milliseconds) that a `receiveMessage` call waits for available messages to be fetched. The higher the setting, the fewer batches are required to carry out the same number of request. | # Increasing throughput using horizontal scaling and action batching with Amazon SQS Amazon SQS supports high-throughput messaging. For details on throughput limits, refer to [Amazon SQS message quotas](quotas-messages.md). To maximize throughput: + [Scale](#horizontal-scaling) producers and consumers horizontally by adding more instances of each. + Use [action batching](#request-batching) to send or receive multiple messages in a single request, reducing API call overhead. ## Horizontal scaling Because you access Amazon SQS through an HTTP request-response protocol, the *request latency* (the interval between initiating a request and receiving a response) limits the throughput that you can achieve from a single thread using a single connection. For example, if the latency from an Amazon EC2-based client to Amazon SQS in the same region averages 20 ms, the maximum throughput from a single thread over a single connection averages 50 TPS. *Horizontal scaling* involves increasing the number of message producers (which make `[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)` requests) and consumers (which make `[ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)` and `[DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)` requests) in order to increase your overall queue throughput. You can scale horizontally in three ways: + Increase the number of threads per client + Add more clients + Increase the number of threads per client and add more clients When you add more clients, you achieve essentially linear gains in queue throughput. For example, if you double the number of clients, you also double the throughput. ## Action batching *Batching* performs more work during each round trip to the service (for example, when you send multiple messages with a single `SendMessageBatch` request). The Amazon SQS batch actions are `[SendMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)`, `[DeleteMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessageBatch.html)`, and `[ChangeMessageVisibilityBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibilityBatch.html)`. To take advantage of batching without changing your producers or consumers, you can use the [Amazon SQS Buffered Asynchronous Client](sqs-client-side-buffering-request-batching.md). **Note** Because `[ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)` can process 10 messages at a time, there is no `ReceiveMessageBatch` action. Batching distributes the latency of the batch action over the multiple messages in a batch request, rather than accept the entire latency for a single message (for example, a `[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)` request). Because each round trip carries more work, batch requests make more efficient use of threads and connections, improving throughput. You can combine batching with horizontal scaling to provide throughput with fewer threads, connections, and requests than individual message requests. You can use batched Amazon SQS actions to send, receive, or delete up to 10 messages at a time. Because Amazon SQS charges by the request, batching can substantially reduce your costs. Batching can introduce some complexity for your application (for example, you application must accumulate messages before sending them, or it sometimes must wait longer for a response). However, batching can be still effective in the following cases: + Your application generates many messages in a short time, so the delay is never very long. + A message consumer fetches messages from a queue at its discretion, unlike typical message producers that need to send messages in response to events they don't control. **Important** A batch request might succeed even though individual messages in the batch failed. After a batch request, always check for individual message failures and retry the action if necessary. ## Working Java example for single-operation and batch requests ### Prerequisites Add the `aws-java-sdk-sqs.jar`, `aws-java-sdk-ec2.jar`, and `commons-logging.jar` packages to your Java build class path. The following example shows these dependencies in a Maven project `pom.xml` file. ``` com.amazonaws aws-java-sdk-sqs LATEST com.amazonaws aws-java-sdk-ec2 LATEST commons-logging commons-logging LATEST ``` ### SimpleProducerConsumer.java The following Java code example implements a simple producer-consumer pattern. The main thread spawns a number of producer and consumer threads that process 1 KB messages for a specified time. This example includes producers and consumers that make single-operation requests and those that make batch requests. ``` /* * Copyright 2010-2024 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. * A copy of the License is located at * * https://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either * express or implied. See the License for the specific language governing * permissions and limitations under the License. * */ import com.amazonaws.AmazonClientException; import com.amazonaws.ClientConfiguration; import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.*; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import java.math.BigInteger; import java.util.ArrayList; import java.util.List; import java.util.Random; import java.util.Scanner; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicInteger; /** * Start a specified number of producer and consumer threads, and produce-consume * for the least of the specified duration and 1 hour. Some messages can be left * in the queue because producers and consumers might not be in exact balance. */ public class SimpleProducerConsumer { // The maximum runtime of the program. private final static int MAX_RUNTIME_MINUTES = 60; private final static Log log = LogFactory.getLog(SimpleProducerConsumer.class); public static void main(String[] args) throws InterruptedException { final Scanner input = new Scanner(System.in); System.out.print("Enter the queue name: "); final String queueName = input.nextLine(); System.out.print("Enter the number of producers: "); final int producerCount = input.nextInt(); System.out.print("Enter the number of consumers: "); final int consumerCount = input.nextInt(); System.out.print("Enter the number of messages per batch: "); final int batchSize = input.nextInt(); System.out.print("Enter the message size in bytes: "); final int messageSizeByte = input.nextInt(); System.out.print("Enter the run time in minutes: "); final int runTimeMinutes = input.nextInt(); /* * Create a new instance of the builder with all defaults (credentials * and region) set automatically. For more information, see Creating * Service Clients in the AWS SDK for Java Developer Guide. */ final ClientConfiguration clientConfiguration = new ClientConfiguration() .withMaxConnections(producerCount + consumerCount); final AmazonSQS sqsClient = AmazonSQSClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build(); final String queueUrl = sqsClient .getQueueUrl(new GetQueueUrlRequest(queueName)).getQueueUrl(); // The flag used to stop producer, consumer, and monitor threads. final AtomicBoolean stop = new AtomicBoolean(false); // Start the producers. final AtomicInteger producedCount = new AtomicInteger(); final Thread[] producers = new Thread[producerCount]; for (int i = 0; i < producerCount; i++) { if (batchSize == 1) { producers[i] = new Producer(sqsClient, queueUrl, messageSizeByte, producedCount, stop); } else { producers[i] = new BatchProducer(sqsClient, queueUrl, batchSize, messageSizeByte, producedCount, stop); } producers[i].start(); } // Start the consumers. final AtomicInteger consumedCount = new AtomicInteger(); final Thread[] consumers = new Thread[consumerCount]; for (int i = 0; i < consumerCount; i++) { if (batchSize == 1) { consumers[i] = new Consumer(sqsClient, queueUrl, consumedCount, stop); } else { consumers[i] = new BatchConsumer(sqsClient, queueUrl, batchSize, consumedCount, stop); } consumers[i].start(); } // Start the monitor thread. final Thread monitor = new Monitor(producedCount, consumedCount, stop); monitor.start(); // Wait for the specified amount of time then stop. Thread.sleep(TimeUnit.MINUTES.toMillis(Math.min(runTimeMinutes, MAX_RUNTIME_MINUTES))); stop.set(true); // Join all threads. for (int i = 0; i < producerCount; i++) { producers[i].join(); } for (int i = 0; i < consumerCount; i++) { consumers[i].join(); } monitor.interrupt(); monitor.join(); } private static String makeRandomString(int sizeByte) { final byte[] bs = new byte[(int) Math.ceil(sizeByte * 5 / 8)]; new Random().nextBytes(bs); bs[0] = (byte) ((bs[0] | 64) & 127); return new BigInteger(bs).toString(32); } /** * The producer thread uses {@code SendMessage} * to send messages until it is stopped. */ private static class Producer extends Thread { final AmazonSQS sqsClient; final String queueUrl; final AtomicInteger producedCount; final AtomicBoolean stop; final String theMessage; Producer(AmazonSQS sqsQueueBuffer, String queueUrl, int messageSizeByte, AtomicInteger producedCount, AtomicBoolean stop) { this.sqsClient = sqsQueueBuffer; this.queueUrl = queueUrl; this.producedCount = producedCount; this.stop = stop; this.theMessage = makeRandomString(messageSizeByte); } /* * The producedCount object tracks the number of messages produced by * all producer threads. If there is an error, the program exits the * run() method. */ public void run() { try { while (!stop.get()) { sqsClient.sendMessage(new SendMessageRequest(queueUrl, theMessage)); producedCount.incrementAndGet(); } } catch (AmazonClientException e) { /* * By default, AmazonSQSClient retries calls 3 times before * failing. If this unlikely condition occurs, stop. */ log.error("Producer: " + e.getMessage()); System.exit(1); } } } /** * The producer thread uses {@code SendMessageBatch} * to send messages until it is stopped. */ private static class BatchProducer extends Thread { final AmazonSQS sqsClient; final String queueUrl; final int batchSize; final AtomicInteger producedCount; final AtomicBoolean stop; final String theMessage; BatchProducer(AmazonSQS sqsQueueBuffer, String queueUrl, int batchSize, int messageSizeByte, AtomicInteger producedCount, AtomicBoolean stop) { this.sqsClient = sqsQueueBuffer; this.queueUrl = queueUrl; this.batchSize = batchSize; this.producedCount = producedCount; this.stop = stop; this.theMessage = makeRandomString(messageSizeByte); } public void run() { try { while (!stop.get()) { final SendMessageBatchRequest batchRequest = new SendMessageBatchRequest().withQueueUrl(queueUrl); final List entries = new ArrayList(); for (int i = 0; i < batchSize; i++) entries.add(new SendMessageBatchRequestEntry() .withId(Integer.toString(i)) .withMessageBody(theMessage)); batchRequest.setEntries(entries); final SendMessageBatchResult batchResult = sqsClient.sendMessageBatch(batchRequest); producedCount.addAndGet(batchResult.getSuccessful().size()); /* * Because SendMessageBatch can return successfully, but * individual batch items fail, retry the failed batch items. */ if (!batchResult.getFailed().isEmpty()) { log.warn("Producer: retrying sending " + batchResult.getFailed().size() + " messages"); for (int i = 0, n = batchResult.getFailed().size(); i < n; i++) { sqsClient.sendMessage(new SendMessageRequest(queueUrl, theMessage)); producedCount.incrementAndGet(); } } } } catch (AmazonClientException e) { /* * By default, AmazonSQSClient retries calls 3 times before * failing. If this unlikely condition occurs, stop. */ log.error("BatchProducer: " + e.getMessage()); System.exit(1); } } } /** * The consumer thread uses {@code ReceiveMessage} and {@code DeleteMessage} * to consume messages until it is stopped. */ private static class Consumer extends Thread { final AmazonSQS sqsClient; final String queueUrl; final AtomicInteger consumedCount; final AtomicBoolean stop; Consumer(AmazonSQS sqsClient, String queueUrl, AtomicInteger consumedCount, AtomicBoolean stop) { this.sqsClient = sqsClient; this.queueUrl = queueUrl; this.consumedCount = consumedCount; this.stop = stop; } /* * Each consumer thread receives and deletes messages until the main * thread stops the consumer thread. The consumedCount object tracks the * number of messages that are consumed by all consumer threads, and the * count is logged periodically. */ public void run() { try { while (!stop.get()) { try { final ReceiveMessageResult result = sqsClient .receiveMessage(new ReceiveMessageRequest(queueUrl)); if (!result.getMessages().isEmpty()) { final Message m = result.getMessages().get(0); sqsClient.deleteMessage(new DeleteMessageRequest(queueUrl, m.getReceiptHandle())); consumedCount.incrementAndGet(); } } catch (AmazonClientException e) { log.error(e.getMessage()); } } } catch (AmazonClientException e) { /* * By default, AmazonSQSClient retries calls 3 times before * failing. If this unlikely condition occurs, stop. */ log.error("Consumer: " + e.getMessage()); System.exit(1); } } } /** * The consumer thread uses {@code ReceiveMessage} and {@code * DeleteMessageBatch} to consume messages until it is stopped. */ private static class BatchConsumer extends Thread { final AmazonSQS sqsClient; final String queueUrl; final int batchSize; final AtomicInteger consumedCount; final AtomicBoolean stop; BatchConsumer(AmazonSQS sqsClient, String queueUrl, int batchSize, AtomicInteger consumedCount, AtomicBoolean stop) { this.sqsClient = sqsClient; this.queueUrl = queueUrl; this.batchSize = batchSize; this.consumedCount = consumedCount; this.stop = stop; } public void run() { try { while (!stop.get()) { final ReceiveMessageResult result = sqsClient .receiveMessage(new ReceiveMessageRequest(queueUrl) .withMaxNumberOfMessages(batchSize)); if (!result.getMessages().isEmpty()) { final List messages = result.getMessages(); final DeleteMessageBatchRequest batchRequest = new DeleteMessageBatchRequest() .withQueueUrl(queueUrl); final List entries = new ArrayList(); for (int i = 0, n = messages.size(); i < n; i++) entries.add(new DeleteMessageBatchRequestEntry() .withId(Integer.toString(i)) .withReceiptHandle(messages.get(i) .getReceiptHandle())); batchRequest.setEntries(entries); final DeleteMessageBatchResult batchResult = sqsClient .deleteMessageBatch(batchRequest); consumedCount.addAndGet(batchResult.getSuccessful().size()); /* * Because DeleteMessageBatch can return successfully, * but individual batch items fail, retry the failed * batch items. */ if (!batchResult.getFailed().isEmpty()) { final int n = batchResult.getFailed().size(); log.warn("Producer: retrying deleting " + n + " messages"); for (BatchResultErrorEntry e : batchResult .getFailed()) { sqsClient.deleteMessage( new DeleteMessageRequest(queueUrl, messages.get(Integer .parseInt(e.getId())) .getReceiptHandle())); consumedCount.incrementAndGet(); } } } } } catch (AmazonClientException e) { /* * By default, AmazonSQSClient retries calls 3 times before * failing. If this unlikely condition occurs, stop. */ log.error("BatchConsumer: " + e.getMessage()); System.exit(1); } } } /** * This thread prints every second the number of messages produced and * consumed so far. */ private static class Monitor extends Thread { private final AtomicInteger producedCount; private final AtomicInteger consumedCount; private final AtomicBoolean stop; Monitor(AtomicInteger producedCount, AtomicInteger consumedCount, AtomicBoolean stop) { this.producedCount = producedCount; this.consumedCount = consumedCount; this.stop = stop; } public void run() { try { while (!stop.get()) { Thread.sleep(1000); log.info("produced messages = " + producedCount.get() + ", consumed messages = " + consumedCount.get()); } } catch (InterruptedException e) { // Allow the thread to exit. } } } } ``` ### Monitoring volume metrics from the example run Amazon SQS automatically generates volume metrics for sent, received, and deleted messages. You can access those metrics and others through the **Monitoring** tab for your queue or on the [CloudWatch console](https://console.aws.amazon.com/cloudwatch/home). **Note** The metrics can take up to 15 minutes after the queue starts to become available. # Using Amazon SQS with an AWS SDK Working with AWS SDKs AWS software development kits (SDKs) are available for many popular programming languages. Each SDK provides an API, code examples, and documentation that make it easier for developers to build applications in their preferred language. | SDK documentation | Code examples | | --- | --- | | [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp) | [AWS SDK for C\$1\$1 code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp) | | [AWS CLI](https://docs.aws.amazon.com/cli) | [AWS CLI code examples](https://docs.aws.amazon.com/code-library/latest/ug/cli_2_code_examples.html) | | [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go) | [AWS SDK for Go code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2) | | [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java) | [AWS SDK for Java code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2) | | [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript) | [AWS SDK for JavaScript code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3) | | [AWS SDK for Kotlin](https://docs.aws.amazon.com/sdk-for-kotlin) | [AWS SDK for Kotlin code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin) | | [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net) | [AWS SDK for .NET code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3) | | [AWS SDK for PHP](https://docs.aws.amazon.com/sdk-for-php) | [AWS SDK for PHP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php) | | [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell) | [AWS Tools for PowerShell code examples](https://docs.aws.amazon.com/code-library/latest/ug/powershell_5_code_examples.html) | | [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk) | [AWS SDK for Python (Boto3) code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python) | | [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby) | [AWS SDK for Ruby code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby) | | [AWS SDK for Rust](https://docs.aws.amazon.com/sdk-for-rust) | [AWS SDK for Rust code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1) | | [AWS SDK for SAP ABAP](https://docs.aws.amazon.com/sdk-for-sapabap) | [AWS SDK for SAP ABAP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap) | | [AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift) | [AWS SDK for Swift code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) | **Example availability** Can't find what you need? Request a code example by using the **Provide feedback** link at the bottom of this page.