本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 Java 的 Amazon SNS 擴充用戶端程式庫
<a name="extended-client-library-java"></a>

## 先決條件
<a name="prereqs-sns-extended-client-library"></a>

下列是使用[適用於 Java 的 Amazon SNS 擴充用戶端程式庫](https://github.com/awslabs/amazon-sns-java-extended-client-lib)的先決條件：
+  AWS 開發套件。本頁面上的範例使用 AWS Java 開發套件。若要安裝和設定 SDK，請參閱《 *適用於 Java 的 AWS SDK 開發人員指南*》中的[設定適用於 Java 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-install.html)。
+  AWS 帳戶 具有適當登入資料的 。若要建立 AWS 帳戶，請導覽至 [AWS 首頁](https://aws.amazon.com/)，然後選擇**建立 AWS 帳戶**。遵循指示。

  如需登入資料的相關資訊，請參閱《 *適用於 Java 的 AWS SDK 開發人員指南*》中的[設定 AWS 登入資料和開發區域](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-credentials.html)。
+ Java 8 或更高版本。
+ 適用於 Java 的 Amazon SNS 擴充用戶端程式庫 (也可從 [Maven](https://maven.apache.org/) 取得)。

## 設定訊息儲存
<a name="large-message-configure-storage"></a>

Amazon SNS 延伸用戶端程式庫使用適用於 的承載卸載 Java 通用程式庫 AWS 進行訊息儲存和擷取。您可以配置以下 Amazon S3 [訊息儲存選項](https://github.com/awslabs/amazon-sns-java-extended-client-lib/blob/main/src/main/java/software/amazon/sns/SNSExtendedClientConfiguration.java)：
+ **自訂訊息大小閾值** – 承載和屬性超過此大小的訊息會自動存放在 Amazon S3 中。
+ **`alwaysThroughS3` flag** – 將此值設定為 `true`，強制將所有訊息承載儲存在 Amazon S3 中。例如：

  ```
  SNSExtendedClientConfiguration snsExtendedClientConfiguration = new
  SNSExtendedClientConfiguration() .withPayloadSupportEnabled(s3Client, BUCKET_NAME).withAlwaysThroughS3(true);
  ```
+ **自訂 KMS 金鑰** – 用於 Amazon S3 儲存貯體中伺服器端加密的金鑰。
+ **儲存貯體名稱** – 用於存放訊息承載的 Amazon S3 儲存貯體名稱。

## 範例：將訊息發布到 Amazon SNS，其中儲存在 Amazon S3 中的有效酬載
<a name="example-s3-large-payloads"></a>

以下程式碼範例顯示做法：
+ 建立範例主題和佇列。
+ 訂閱佇列以接收來自主題的訊息。
+ 發布測試訊息。

訊息酬載儲存在 Amazon S3 中，並發布對該訊息的參考。Amazon SQS 延伸用戶端是用來接收訊息。

**適用於 Java 1.x 的 SDK**  
 GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/java/example_code/sns#code-examples)中設定和執行。
若要發布大型訊息，請使用適用於 Java 的 Amazon SNS 擴充用戶端程式庫。您傳送的訊息會參考包含實際訊息內容的 Amazon S3 物件。  

```
import com.amazon.sqs.javamessaging.AmazonSQSExtendedClient;
import com.amazon.sqs.javamessaging.ExtendedClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.sns.AmazonSNS;
import com.amazonaws.services.sns.AmazonSNSClientBuilder;
import com.amazonaws.services.sns.model.CreateTopicRequest;
import com.amazonaws.services.sns.model.PublishRequest;
import com.amazonaws.services.sns.model.SetSubscriptionAttributesRequest;
import com.amazonaws.services.sns.util.Topics;
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.CreateQueueRequest;
import com.amazonaws.services.sqs.model.ReceiveMessageResult;
import software.amazon.sns.AmazonSNSExtendedClient;
import software.amazon.sns.SNSExtendedClientConfiguration;

public class Example {

        public static void main(String[] args) {
                final String BUCKET_NAME = "extended-client-bucket";
                final String TOPIC_NAME = "extended-client-topic";
                final String QUEUE_NAME = "extended-client-queue";
                final Regions region = Regions.DEFAULT_REGION;

                // Message threshold controls the maximum message size that will be allowed to
                // be published
                // through SNS using the extended client. Payload of messages exceeding this
                // value will be stored in
                // S3. The default value of this parameter is 256 KB which is the maximum
                // message size in SNS (and SQS).
                final int EXTENDED_STORAGE_MESSAGE_SIZE_THRESHOLD = 32;

                // Initialize SNS, SQS and S3 clients
                final AmazonSNS snsClient = AmazonSNSClientBuilder.standard().withRegion(region).build();
                final AmazonSQS sqsClient = AmazonSQSClientBuilder.standard().withRegion(region).build();
                final AmazonS3 s3Client = AmazonS3ClientBuilder.standard().withRegion(region).build();

                // Create bucket, topic, queue and subscription
                s3Client.createBucket(BUCKET_NAME);
                final String topicArn = snsClient.createTopic(
                                new CreateTopicRequest().withName(TOPIC_NAME)).getTopicArn();
                final String queueUrl = sqsClient.createQueue(
                                new CreateQueueRequest().withQueueName(QUEUE_NAME)).getQueueUrl();
                final String subscriptionArn = Topics.subscribeQueue(
                                snsClient, sqsClient, topicArn, queueUrl);

                // To read message content stored in S3 transparently through SQS extended
                // client,
                // set the RawMessageDelivery subscription attribute to TRUE
                final SetSubscriptionAttributesRequest subscriptionAttributesRequest = new SetSubscriptionAttributesRequest();
                subscriptionAttributesRequest.setSubscriptionArn(subscriptionArn);
                subscriptionAttributesRequest.setAttributeName("RawMessageDelivery");
                subscriptionAttributesRequest.setAttributeValue("TRUE");
                snsClient.setSubscriptionAttributes(subscriptionAttributesRequest);

                // Initialize SNS extended client
                // PayloadSizeThreshold triggers message content storage in S3 when the
                // threshold is exceeded
                // To store all messages content in S3, use AlwaysThroughS3 flag
                final SNSExtendedClientConfiguration snsExtendedClientConfiguration = new SNSExtendedClientConfiguration()
                                .withPayloadSupportEnabled(s3Client, BUCKET_NAME)
                                .withPayloadSizeThreshold(EXTENDED_STORAGE_MESSAGE_SIZE_THRESHOLD);
                final AmazonSNSExtendedClient snsExtendedClient = new AmazonSNSExtendedClient(snsClient,
                                snsExtendedClientConfiguration);

                // Publish message via SNS with storage in S3
                final String message = "This message is stored in S3 as it exceeds the threshold of 32 bytes set above.";
                snsExtendedClient.publish(topicArn, message);

                // Initialize SQS extended client
                final ExtendedClientConfiguration sqsExtendedClientConfiguration = new ExtendedClientConfiguration()
                                .withPayloadSupportEnabled(s3Client, BUCKET_NAME);
                final AmazonSQSExtendedClient sqsExtendedClient = new AmazonSQSExtendedClient(sqsClient,
                                sqsExtendedClientConfiguration);

                // Read the message from the queue
                final ReceiveMessageResult result = sqsExtendedClient.receiveMessage(queueUrl);
                System.out.println("Received message is " + result.getMessages().get(0).getBody());
        }
}
```

## 其他端點通訊協定
<a name="large-payloads-other-protocols"></a>

Amazon SNS 和 Amazon SQS 函式庫都使用 [AWS的酬載卸載 Java 通用程式庫](https://github.com/awslabs/payload-offloading-java-common-lib-for-aws)，以使用 Amazon S3 存放和擷取訊息酬載。任何啟用 Java 的端點 (例如，在 Java 中實作的 HTTPS 端點) 都可以使用相同的庫來解除參照消息內容。

無法使用適用於 的承載卸載 Java 通用程式庫的端點仍然 AWS 可以發佈訊息，其中包含存放在 Amazon S3 中的承載。以下是上述代碼範例發布的 Amazon S3 參考範例：

```
[
  "software.amazon.payloadoffloading.PayloadS3Pointer",
  {
    "s3BucketName": "extended-client-bucket",
    "s3Key": "xxxx-xxxxx-xxxxx-xxxxxx"
  }
]
```