对接Amazon SQS 消息相关接口简要说明

Amazon SQS 消息相关接口

因项目功能需求，对接了Amazon的SQS消息队列，封装了常用的接口，本文是对封装后接口的简要说明。

---

1.发送消息

往队列中单条或批量发送消息。

1.1.单条发送消息

/**
 * 发送消息
 *
 * @param reqSendMessageBody 消息vo
 * @return 响应信息
 * @throws SqsException
 */
SendMessageResponse sendMessage(ReqSendMessageBody reqSendMessageBody)

消息vo - ReqSendMessageBody 字段说明：

/**
 * 基本必填参数
 * 注意：
 * 1、queueUrl字段为单个发送消息接口必填参数；批次发送消息接口不填。
 * 2、id字段为批次发送消息接口必填参数（id为此批处理中用于通信结果的消息的标识符，id 在请求中必须是唯一的）；单个发送消息接口不填。
 */
private String queueUrl;
private String id;
private String messageBody;

/**
 * 基本非必填参数
 */
private Map<String, MessageAttributeValue> messageAttributes;
private Map<MessageSystemAttributeNameForSends, MessageSystemAttributeValue> messageSystemAttributes;

/**
 * 非fifo才可以设置的参数
 * 消息交付延迟时间
 */
private Integer delaySeconds;

/**
 * fifo队列需要的参数
 * messageGroupId 必填 指定消息属于特定消息组的标记，属于同一消息组的消息以 FIFO 方式处理
 * messageDeduplicationId 非必填 根据该id判断是否是重复消息 （若不填，则队列需要启用基于内容的重复消息删除，否则会抛出异常。）
 */
private String messageGroupId;
private String messageDeduplicationId;

响应信息 - SendMessageResponse 字段说明：

/**
 * messageId 消息id
 * sequenceNumber 序列号（FIFO队列中，消息组内部的序列号）
 */
private final String messageId;
private final String sequenceNumber;

注：

• 单条发送消息，没有报错抛出异常则说明发送成功。发送成功才有响应信息。
• 详见官方文档

1.2.批量发送消息

/**
 * 批量发送消息
 *
 * @param reqSendMessageBatchBody 消息vo
 * @return 响应信息
 * @throws SqsException
 */
RespSendMessageBatchBody sendMessageBatch(ReqSendMessageBatchBody reqSendMessageBatchBody)

消息vo - ReqSendMessageBatchBody 字段说明：

/**
 * 基本必填参数
 * queueUrl 必填 队列url
 * sendMessageList 必填 要发送的消息集合
 *   |—— ReqSendMessageBody 消息vo 详见上面单条发送消息接口的入参
 */
private String queueUrl;
private List<ReqSendMessageBody> sendMessageList;

响应信息 - RespSendMessageBatchBody 字段说明：

/**
 * failedList 发送失败的消息集合
 *   |—— BatchResultErrorEntry 失败的消息信息
 *         |—— id 唯一标识符
 *         |—— code 错误码
 *         |—— message 错误信息
 *         |—— senderFault 是否是消息发送者的错误
 * successfulList 发送成功的消息集合
 *   |—— SendMessageBatchResultEntry 成功的消息信息
 *         |—— id 唯一标识符
 *         |—— messageId 消息id
 *         |—— sequenceNumber 序列号（FIFO队列中，消息组内部的序列号）
 */
private List<BatchResultErrorEntry> failedList;
private List<SendMessageBatchResultEntry> successfulList;

注：

• Amazon SQS 批量发送消息接口限制1次最多发送10条消息，而封装后的接口没有限制1次最多发送的消息数量，当消息数量大于10条，接口中会循环分多次批量发送，但是会在一定程度上降低接口效率。
• 批量发送消息中的所有消息只能往同一个队列发送。
• 详见官方文档

---

2.从指定的队列检索若干条消息

从指定的队列中检索一条或多条消息（最多 10 条）。是主动查询而不是被动接收。

/**
 * 从指定的队列检索若干条消息(最少1条，最多10条)
 *
 * @param reqReceiveMessageBody 请求vo
 * @return 响应信息
 * @throws SqsException
 */
public ReceiveMessageResponse receiveMessage(ReqReceiveMessageBody reqReceiveMessageBody)

请求vo - ReqReceiveMessageBody 字段说明：

/**
 * 基本必填参数
 * queueUrl - 队列url
 */
private String queueUrl;

/**
 * 基本非必填参数
 * maxNumberOfMessages - 要返回的最大消息数，1-10条，默认1
 * attributeNames - 需要与每条消息一起返回的属性列表
 * messageAttributeNames - 消息属性的名称列表
 * visibilityTimeout - 消息被检索后对其他消费者的可见性超时时长
 * waitTimeSeconds - 调用在返回之前等待消息到达队列的持续时间
 */
private Integer maxNumberOfMessages;
private List<QueueAttributeName> attributeNames;
private List<String> messageAttributeNames;
private Integer visibilityTimeout;
private Integer waitTimeSeconds;

/**
 * 仅用于fifo队列
 * receiveRequestAttemptId - 用于发起重复检索的token
 */
private String receiveRequestAttemptId;

响应信息 - ReceiveMessageResponse 字段说明：

/**
 * messages 返回的消息集合
 *   |—— Message 一条消息实体
 *         |—— messageId - 消息唯一标识符
 *         |—— body - 消息的内容
 *         |—— attributes - 与每条消息一起返回的属性列表
 *         |—— messageAttributes - 每个消息属性由 Name、 Type 和 Value 组成
 *         |—— receiptHandle - 收据句柄，一种标识符。每次收到消息时都会返回一个新的收据句柄
 */
 private final List<Message> messages;

注：

• receiveMessage实际返回的消息数量可能少于参数maxNumberOfMessages的值，但是永远不会多于参数maxNumberOfMessages的值。
• 参数 receiveRequestAttemptId 的具体用法：发起receiveMessage请求后可能由于网络问题没有得到响应，可以通过receiveRequestAttemptId 发起相同请求检索相同消息，即使这些消息的可见性超时时长尚未过期。
• receiptHandle - 响应信息中的消息接收句柄，用于接收消息后对消息执行删除、更改可见性超时时长等操作。
• 详见官方文档

---

3.删除消息

将消息从队列中删除。

3.1.单条删除消息

/**
 * 删除消息
 *
 * @param queueUrl - 队列url
 * @param receiptHandle - 接收消息的句柄
 * @throws SqsException
 */
void deleteMessage(String queueUrl, String receiptHandle)

请求参数说明：

/**
 * queueUrl - 队列url，必填
 * receiptHandle - 检索消息获得的句柄，必填。
 */
String queueUrl;
String receiptHandle;

注：

• 没有报错抛出异常则说明删除成功。
• 通过句柄 receiptHandle 删除，而不通过消息唯一标识符 messageId 删除。是为了防止当前消费者正在处理消息时，该消息被别的消费者通过 messageId 删除。由于消费者每次检索消息都会生成新的 receiptHandle，所以也无法通过历史检索消息时获得的 receiptHandle 删除消息。
• 详见官方文档

3.2.批量删除消息

/**
 * 批量删除消息
 *
 * @param queueUrl          队列url
 * @param deleteMessageList 要删除的消息集合
 * @return 响应信息
 * @throws SqsException
 */
RespDeleteMessageBatchBody deleteMessageBatch(String queueUrl, List<ReqDeleteMessageBatchBody> deleteMessageList)

请求参数说明：

/**
 * queueUrl - 队列url，必填
 * deleteMessageList - 要删除的消息集合，必填且不为空
 */
String queueUrl;
List<ReqDeleteMessageBatchBody> deleteMessageList;
  |—— ReqDeleteMessageBatchBody - 要删除的消息实体
        |—— id - 批处理需要的唯一标识符，用于传达结果
        |—— receiptHandle - 检索消息获得的句柄

响应信息 - RespDeleteMessageBatchBody 字段说明：

/**
 * failedList 删除失败的消息集合
 *   |—— BatchResultErrorEntry 失败的消息信息
 *         |—— id 唯一标识符
 *         |—— code 错误码
 *         |—— message 错误信息
 *         |—— senderFault 是否是消息发送者的错误
 * successfulList 删除成功的消息集合
 *   |—— DeleteMessageBatchResultEntry 成功的消息信息
 *         |—— id 唯一标识符
 */
private List<BatchResultErrorEntry> failedList;
private List<DeleteMessageBatchResultEntry> successfulList;

注：

• Amazon SQS 批量删除消息接口限制1次最多删除10条消息，而封装后的接口没有限制1次最多删除的消息数量，当消息数量大于10条，接口中会循环分多次批量删除，但是会在一定程度上降低接口效率。
• 详见官方文档

---

4.更改消息可见性超时时长

单条或批量将队列中指定消息的可见性超时时长更改为新值。

4.1.单条更改消息可见性超时时长

/**
 * 更改消息可见性
 *
 * @param queueUrl          队列url
 * @param receiptHandle     接收消息receiveMessage接口响应信息中的receiptHandle
 * @param visibilityTimeout 消息可见性超时时长的新值（以秒为单位）。值范围：0到43200。最长：12 小时。
 * @throws SqsException
 */
void changeMessageVisibility(String queueUrl, String receiptHandle, Integer visibilityTimeout)

请求参数说明：

/**
 * queueUrl - 队列url，必填
 * receiptHandle - 句柄，必填
 * visibilityTimeout - 消息可见性超时时长新值，非必填，默认值30
 */
String queueUrl;
String receiptHandle;
Integer visibilityTimeout;

注：

• 没有报错抛出异常则说明更改可见性超时时长成功。
• 更改消息的可见性超时时长后，若下一次消息被检索后没有被删除，则消息的可见性超时时长恢复原始值。
• 详见官方文档

4.2.批量更改消息可见性超时时长

/**
 * 批量更改消息可见性超时时长
 *
 * @param queueUrl                    队列url
 * @param changeMessageVisibilityList 要更改消息可见性超时时长的消息集合
 * @return 响应信息
 * @throws SqsException
 */
RespChangeMessageVisibilityBatchBody changeMessageVisibilityBatch(String queueUrl, List<ReqChangeMessageVisibilityBatchBody> changeMessageVisibilityList)

请求参数说明：

/**
 * queueUrl - 队列url，必填
 * changeMessageVisibilityList- 要更改可见性超时时长的消息集合，必填且不为空
 */
String queueUrl;
List<ReqChangeMessageVisibilityBatchBody> changeMessageVisibilityList;
  |—— ReqChangeMessageVisibilityBatchBody- 要更改可见性超时时长的消息实体
        |—— id - 批处理需要的唯一标识符，用于传达结果
        |—— receiptHandle - 检索消息获得的句柄
        |—— visibilityTimeout - 可见性超时时长新值

响应信息 - 字段说明：

/**
 * failedList 更改失败的消息集合
 *   |—— BatchResultErrorEntry 失败的消息信息
 *         |—— id 唯一标识符
 *         |—— code 错误码
 *         |—— message 错误信息
 *         |—— senderFault 是否是消息发送者的错误
 * successfulList 更改成功的消息集合
 *   |—— ChangeMessageVisibilityBatchResultEntry 成功的消息信息
 *         |—— id 唯一标识符
 */
private List<BatchResultErrorEntry> failedList;
private List<ChangeMessageVisibilityBatchResultEntry> successfulList;

注：

• Amazon SQS 批量更改消息可见性超时时长接口限制1次最多更改10条消息，而封装后的接口没有限制1次最多更改的消息数量，当消息数量大于10条，接口中会循环分多次批量更改，但是会在一定程度上降低接口效率。
• 详见官方文档