本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 搭配 使用 Amazon SQS 的自動請求批次處理 AWS SDK for Java 2.x Amazon SQS 的 Automatic Request Batching API 是一個高階程式庫，提供有效的方法來批次處理和緩衝 SQS 操作的請求。透過使用批次處理 API，您可以減少對 SQS 的請求數量，從而提高輸送量並將成本降至最低。 由於批次 API 方法符合`[SqsAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/SqsAsyncClient.html)`方法 —`sendMessage`、`changeMessageVisibility``deleteMessage`、、 `receiveMessage`— 您可以使用批次 API 做為插入式取代，且變更最少。 本主題概述如何設定和使用適用於 Amazon SQS 的自動請求批次 API。 ## 檢查先決條件 您需要使用適用於 Java 的 SDK *2.x 2.28.0 *版或更新版本，才能存取批次處理 API。Maven `pom.xml`應至少包含下列元素。 ``` software.amazon.awssdk bom 2.28.231 pom import software.amazon.awssdk sqs ``` 1 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) ## 建立批次管理工具 [SqsAsyncBatchManager](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html) 介面會實作自動請求批次處理 API。您可以用幾種方式建立管理員的執行個體。 ### 使用 的預設組態 `SqsAsyncClient` 建立批次管理工具最簡單的方法是在現有的 [SqsAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/SqsAsyncClient.html) 執行個體上呼叫`batchManager`原廠方法。簡單方法會顯示在下列程式碼片段中。 ``` SqsAsyncClient asyncClient = SqsAsyncClient.create(); SqsAsyncBatchManager sqsAsyncBatchManager = asyncClient.batchManager(); ``` 當您使用此方法時，`SqsAsyncBatchManager`執行個體會使用 [覆寫 的組態設定 `SqsAsyncBatchManager`](#sqs-auto-batch-config-settings)區段中資料表中顯示的預設值。此外，`SqsAsyncBatchManager`執行個體會使用其建立來源`ExecutorService``SqsAsyncClient`執行個體的 。 ### 使用 自訂組態 `SqsAsyncBatchManager.Builder` 如需更進階的使用案例，您可以使用 自訂批次管理工具[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.Builder.html)。透過使用此方法來建立`SqsAsyncBatchManager`執行個體，您可以微調批次處理行為。下列程式碼片段示範如何使用建置器來自訂批次處理行為。 ``` SqsAsyncBatchManager batchManager = SqsAsyncBatchManager.builder() .client(SqsAsyncClient.create()) .scheduledExecutor(Executors.newScheduledThreadPool(5)) .overrideConfiguration(b -> b .receiveMessageMinWaitDuration(Duration.ofSeconds(10)) .receiveMessageVisibilityTimeout(Duration.ofSeconds(1)) .receiveMessageAttributeNames(Collections.singletonList("*")) .receiveMessageSystemAttributeNames(Collections.singletonList(MessageSystemAttributeName.ALL))) .build(); ``` 使用此方法時，您可以調整 [覆寫 的組態設定 `SqsAsyncBatchManager`](#sqs-auto-batch-config-settings)區段中資料表中顯示之`BatchOverrideConfiguration`物件的設定。您也可以使用此方法[https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html)為批次管理員提供自訂 。 ## 傳送訊息 若要使用批次管理工具傳送訊息，請使用 `[SqsAsyncBatchManager\$1sendMessage](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#sendMessage(software.amazon.awssdk.services.sqs.model.SendMessageRequest))`方法。軟體開發套件會緩衝請求，並在達到 `maxBatchSize`或 `sendRequestFrequency`值時以批次方式傳送請求。 下列範例顯示緊接另一個`sendMessage`請求的請求。在此情況下，軟體開發套件會以單一批次傳送兩個訊息。 ``` // Sending the first message CompletableFuture futureOne = sqsAsyncBatchManager.sendMessage(r -> r.messageBody("One").queueUrl("queue")); // Sending the second message CompletableFuture futureTwo = sqsAsyncBatchManager.sendMessage(r -> r.messageBody("Two").queueUrl("queue")); // Waiting for both futures to complete and retrieving the responses SendMessageResponse messageOne = futureOne.join(); SendMessageResponse messageTwo = futureTwo.join(); ``` ## 變更訊息可見性逾時 您可以使用 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#changeMessageVisibility(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#changeMessageVisibility(java.util.function.Consumer))方法變更批次中訊息的可見性逾時。軟體開發套件會緩衝請求，並在達到 `maxBatchSize`或 `sendRequestFrequency`值時以批次方式傳送請求。 下列範例顯示如何呼叫 `changeMessageVisibility`方法。 ``` CompletableFuture futureOne = sqsAsyncBatchManager.changeMessageVisibility(r -> r.receiptHandle("receiptHandle") .queueUrl("queue")); ChangeMessageVisibilityResponse response = futureOne.join(); ``` ## 刪除訊息 您可以使用 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#deleteMessage(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#deleteMessage(java.util.function.Consumer))方法刪除批次中的訊息。軟體開發套件會緩衝請求，並在達到 `maxBatchSize`或 `sendRequestFrequency`值時以批次方式傳送請求。 下列範例示範如何呼叫 `deleteMessage`方法。 ``` CompletableFuture futureOne = sqsAsyncBatchManager.deleteMessage(r -> r.receiptHandle("receiptHandle") .queueUrl("queue")); DeleteMessageResponse response = futureOne.join(); ``` ## 接收訊息 ### 使用預設設定 當您在應用程式中輪詢 `[SqsAsyncBatchManager\$1receiveMessage](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/SqsAsyncBatchManager.html#receiveMessage(java.util.function.Consumer))`方法時，批次管理工具會從其內部緩衝區擷取訊息，開發套件會在背景自動更新。 下列範例顯示如何呼叫 `receiveMessage`方法。 ``` CompletableFuture responseFuture = sqsAsyncBatchManager.receiveMessage(r -> r.queueUrl("queueUrl")); ``` ### 使用自訂設定 如果您想要進一步自訂請求，例如設定自訂等待時間並指定要擷取的訊息數量，您可以自訂請求，如下列範例所示。 ``` CompletableFuture response = sqsAsyncBatchManager.receiveMessage(r -> r.queueUrl("queueUrl") .waitTimeSeconds(5) .visibilityTimeout(20)); ``` **注意** 如果您`receiveMessage`使用包含下列任何參數`[ReceiveMessageRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/model/ReceiveMessageRequest.html)`的 呼叫 ，軟體開發套件會略過批次管理工具並傳送一般非同步`receiveMessage`請求： `messageAttributeNames` `messageSystemAttributeNames` `messageSystemAttributeNamesWithStrings` `overrideConfiguration` ## 覆寫 的組態設定 `SqsAsyncBatchManager` 您可以在建立`SqsAsyncBatchManager`執行個體時調整下列設定。下列設定清單可在 上取得[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/BatchOverrideConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/batchmanager/BatchOverrideConfiguration.Builder.html)。 | 設定 | Description | 預設值 | | --- | --- | --- | | maxBatchSize | 每個 SendMessageBatchRequest、 ChangeMessageVisibilityBatchRequest或 每個批次的請求數量上限DeleteMessageBatchRequest。最大值為 10。 | 10 | | sendRequestFrequency | 傳送批次之前的時間，除非之前`maxBatchSize`已到達。較高的值可能會減少請求，但會增加延遲。 | 200 毫秒 | | receiveMessageVisibilityTimeout | 訊息的可見性逾時。如果取消設定，則會使用佇列的預設值。 | 佇列的預設 | | receiveMessageMinWaitDuration | receiveMessage 請求的最短等待時間。避免將 設定為 0 以防止 CPU 浪費。 | 50 毫秒 | | receiveMessageSystemAttributeNames | 要請求receiveMessage呼叫[的系統屬性名稱](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sqs/model/MessageSystemAttributeName.html)清單。 | 無 | | receiveMessageAttributeNames | 要請求receiveMessage呼叫的[屬性名稱](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-attributes)清單。 | 無 |