对接Amazon SQS 队列相关接口简要说明

Amazon SQS 队列相关接口

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

---

1.创建队列

2个创建标准队列的接口，和2个创建FIFO（first in first out ：先进先出）队列的接口。
队列的很多功能需要通过属性进行配置，可以在创建队列时通过参数attributes进行配置，也可以在创建队列以后单独配置，后面会详细介绍设置队列属性的接口，以及对属性封装后的各个功能配置接口。

/**
* 2个创建标准队列的接口
* 
* @param queueName - 队列名称，必填
* @param attributes - 队列属性集合，非必填
* @param tags - 队列标签集合，非必填
* @return 队列url
*/
String createQueue(String queueName)

String createQueue(String queueName, Map<QueueAttributeNameEnum, String> attributes, Map<String, String> tags)

/**
 * 2个创建FIFO队列的接口
 * 
 * @param queueName - 队列名称，必填
 * @param delaySeconds - 延迟传递到队列的时间，非必填
 * @param attributes - 队列属性集合，非必填
 * @param tags - 队列标签集合，非必填
 * @return 队列url
*/
String createFifoQueue(String queueName, Integer delaySeconds)

String createFifoQueue(String queueName, Map<QueueAttributeNameEnum, String> attributes, Map<String, String> tags)

注：

• 队列创建以后不能在标准队列与FIFO队列之间转换（即一个标准队列不能转为FIFO队列，一个FIFO队列也不能转为标准队列），下面说明原因。
• FIFO队列的名称必须以 .fifo 结尾，否则会报错。
• 参数 - 延迟传递到队列的时间：有效值 0到 900（15分钟）之间的整数，默认 0，单位秒。
• FIFO队列不能针对队列中的每条message单独设置 delaySeconds ，FIFO队列若要设置 delaySeconds ，只能在队列参数中统一设置。

实际上在创建队列时，是通过FIFO_QUEUE属性的值来确定创建的队列是标准队列还是FIFO队列。
当FIFO_QUEUE属性的值为 true 时，创建FIFO队列。
当FIFO_QUEUE属性的值为 false ，或者不设置FIFO_QUEUE属性（默认false）时，创建标准队列。
队列创建后，无法改变FIFO_QUEUE属性的值，所以队列创建以后不能在标准队列与FIFO队列之间转换。

---

2.获取队列url

队列的url相当于一个队列的唯一标识符，队列创建成功后会返回该队列的url，后续对该队列的操作都需要队列url作为参数。

/**
 * 根据队列名称获取该队列的url
 * 
 * @param queueName - 队列名称，必填
 * @param queueOwnerAWSAccountId - AWS帐号id，非必填
 * @return 队列url
*/
String getQueueUrl(String queueName)

String getQueueUrl(String queueName, String queueOwnerAWSAccountId)

注：

• 若不存在指定名称的队列，则抛出异常提示QueueDoesNotExistException: The specified queue does not exist for this wsdl version.
• 可通过参数 queueOwnerAWSAccountId 传入AWS帐号id，查询指定的另一个AWS帐号的队列，不传则查询当前AWS帐号所属的队列。

---

3.1.设置队列属性

可通过修改队列的属性值，改变队列的配置以及开启或关闭队列的某些功能。

/**
 * 修改队列属性
 * 
 * @param queueUrl - 队列url，必填
 * @param attributes - 属性-属性值集合，必填
*/
void setQueueAttributes(String queueUrl, Map<QueueAttributeNameEnum, String> attributes)

注：

• 不是所有属性都可以修改。
• 部分属性的属性值存在有效值范围。
• 队列属性说明详见官方文档，或总结博文。

---

3.2.封装特定属性后的功能接口

以下是针对队列的特定配置、功能进行属性封装后的接口。将属性封装到接口中，调用者就只需传入属性值，而不需要再去考虑应该修改哪些属性，同时也可避免拼写错误等低级错误。

3.2.1.设置队列交付延迟时间

设置队列中所有消息延迟传递的时间长度。例如，延迟时间设置为1分钟，则消息发送到队列后1分钟内为不可用状态，对消费者不可见，1分钟后才变为可用状态，才对消费者可见。

/**
 * 设置队列交付延迟时间
 * 
 * @param queueName - 队列名称，必填
 * @param queueUrl - 队列url，必填
 * @param delaySeconds - 延迟时间（有效值：0 到 900（15分钟），单位秒），必填
*/
void setDelaySecondsByName(String queueName, Integer delaySeconds)

void setDelaySecondsByUrl(String queueUrl, Integer delaySeconds)

注：

• 若创建队列时没有设置，则初始默认为0秒。
• setDelaySecondsByName接口其实是对setDelaySecondsByUrl接口进行了一层封装，首先要通过queueName获取queueUrl，所以setDelaySecondsByUrl接口的效率更高。

3.2.2.设置队列的消息保留周期

设置队列中消息的保留周期。例如，保留周期设置为60秒，则60秒后消息自动删除。

/**
 * 设置队列的消息保留周期
 * 
 * @param queueUrl - 队列url，必填
 * @param retentionPeriod - 消息保留周期（有效值：60（1分钟）到 1209600（14天），默认值345600（4天），单位秒），非必填
*/
void setMessageRetentionPeriod(String queueUrl, Integer retentionPeriod)

注：

• 若创建队列时没有设置，则初始默认为4天。

3.2.3.设置队列的等待消息到达的时长

设置获取消息请求的等待时间。若值为0，则请求为短轮询；若值大于0，则开启长轮询。

/**
 * 设置队列的等待消息到达的时长
 * 
 * @param queueUrl - 队列url，必填
 * @param waitTimeSeconds - 等待消息到达的时长（有效值：0 到 20，默认0，单位秒），非必填
*/
void setReceiveMessageWaitTimeSeconds(String queueUrl, Integer waitTimeSeconds)

注：

• 若创建队列时没有设置，则初始默认为0秒（短轮询）。
• 队列的配置优先级低于获取消息ReceiveMessage接口的WaitTimeSeconds参数。
• 长轮询与短轮询详见官方文档。

3.2.4.设置队列中消息可见性超时时长

队列级别的消息可见性超时时长，以秒为单位。一条消息被某一消费者接收后，在可见性超时时间之内，这条消息对其他消费者不可见。

/**
 * 设置队列中消息可见性超时时长
 * 
 * @param queueUrl - 队列url，必填
 * @param timeoutSeconds- 可见性超时时长（有效值：0 到 43200，单位秒，默认30），非必填
*/
void setVisibilityTimeout(String queueUrl, Integer timeoutSeconds)

注：

• 若调用消息接口changeMessageVisibility修改某条消息的可见性超时时长，修改会立即生效，但是若消息被消费者接收后没有删除，则该消息下一次被消费者接收时，可见性超时时长将恢复为原始值。

3.2.5.为源队列配置死信队列

若为源队列配置了死信队列，则源队列中无法成功处理（使用）的消息将会移入死信队列。

/**
 * 为源队列配置死信队列
 * 
 * @param queueName - 队列名称，必填
 * @param queueUrl - 队列url，必填
 * @param maxReceiveCount - 消息最大接收次数，非必填
*/
void deployDeadLetterQueueByName(String sourceQueueName, String deadLetterQueueName, Integer maxReceiveCount)

void deployDeadLetterQueueByUrl(String sourceQueueUrl, String deadLetterQueueUrl, Integer maxReceiveCount)

注：

• 源队列与死信队列的类型必须一致：标准源队列的死信队列必须是标准队列，FIFO源队列的死信队列必须是FIFO队列。
• 参数 - maxReceiveCount 消息最大接收次数（不传参则默认为5），消息超过最大接收次数且未被删除，则将消息从源队列移至死信队列。
• 源队列与死信队列的关系为多对一，即一个源队列只能有一个死信队列，一个死信队列可以被多个源队列配置。

3.2.6.启用（消息组 级别）基于内容的重复数据删除

*仅适用于FIFO（先进先出）队列
与标准队列不同，FIFO队列不会引入重复消息，“消息组级别”即判断消息是否重复的范围为同属于一个消息组的所有消息。
启用基于内容的重复数据删除。这会指示 Amazon SQS 使用 SHA-256 哈希值来生成消息重复数据删除 ID，使用消息的正文而不是消息的属性。

/**
 * 启用（消息组 级别）基于内容的重复数据删除功能
 * 
 * @param queueUrl - 队列url，必填
*/
void enableContentBasedDeduplication4MessageGroup(String queueUrl)

注：

• 详见官方文档

3.2.7.启用（队列 级别）基于内容的重复数据删除

*仅适用于FIFO（先进先出）队列
与标准队列不同，FIFO队列不会引入重复消息，“队列级别”即判断消息是否重复的范围为同属于一个队列的所有消息。
启用基于内容的重复数据删除。这会指示 Amazon SQS 使用 SHA-256 哈希值来生成消息重复数据删除 ID，使用消息的正文而不是消息的属性。

/**
 * 启用（队列 级别）基于内容的重复数据删除功能
 * 
 * @param queueUrl - 队列url，必填
*/
void enableContentBasedDeduplication4Queue(String queueUrl)

注：

• 详见官方文档

3.2.8.禁用基于内容的重复数据删除

*仅适用于FIFO（先进先出）队列
禁用基于内容的重复数据删除。Amazon SQS 将不会使用 SHA-256 哈希值对消息正文生成消息重复数据删除 ID。

/**
 * 禁用基于内容的重复数据删除
 * 
 * @param queueUrl - 队列url，必填
*/
void disableContentBasedDeduplication(String queueUrl)

注：

• 详见官方文档

3.2.9.启用FIFO队列高吞吐量

*仅适用于FIFO（先进先出）队列
FIFO 队列的高吞吐量支持每个 API 每秒更高数量的请求。想要增加 FIFO 队列的高吞吐量请求数，可以增加使用的消息组数。每个消息组每秒支持 300 个请求。

/**
 * 启用FIFO队列高吞吐量
 * 
 * @param queueUrl - 队列url，必填
*/
void enableHighThroughput(String queueUrl)

注：

• 详见官方文档

3.2.10.禁用FIFO队列高吞吐量

*仅适用于FIFO（先进先出）队列

/**
 * 禁用FIFO队列高吞吐量
 * 
 * @param queueUrl - 队列url，必填
*/
void disableHighThroughput(String queueUrl)

注：

• 详见官方文档

3.2.11.启用队列服务端加密功能

Amazon SQS 默认提供传输中加密。另外我们还可以启用服务器端加密(SSE)，这意味着 SQS 将会加密 SQS 服务器上的所有静态客户数据。服务器端加密 (SSE) 会在 Amazon SQS 收到消息后立即对其进行加密。消息以加密形式存储，并且 Amazon SQS 仅在将消息发送给授权使用者时对其进行解密。

/**
 * 启用队列服务端加密功能
 * 
 * @param queueUrl - 队列url，必填
 * @param queueName - 队列名称，必填
 * @param kmsMasterKeyId - kms主密钥别名，前2个接口使用默认值，后2个接口必填
 * @param kmsDataKeyReusePeriodSeconds - 数据密钥重用周期，前2个接口使用默认值，后2个接口必填
*/
void enableServerSideEncryptionByName(String queueName)

void enableServerSideEncryptionByUrl(String queueUrl)

void enableServerSideEncryptionByName(String queueName, String kmsMasterKeyId, Integer kmsDataKeyReusePeriodSeconds)

void enableServerSideEncryptionByUrl(String queueUrl, String kmsMasterKeyId, Integer kmsDataKeyReusePeriodSeconds)

注：

• kmsMasterKeyId - kms主密钥别名，Amazon SQS 或自定义 CMK 的 AWS 托管客户主密钥 (CMK) 的 ID，默认值：alias/aws/sqs。可自定义，例如：alias/MyAlias。空字符串表示禁用加密服务，null为非法参数值。
• kmsDataKeyReusePeriodSeconds - 再次调用 AWS KMS 之前，Amazon SQS 可以重复使用数据密钥来加密或解密消息的时间长度（有效值：60（1 分钟）到 86400（24 小时），单位秒，默认值：300（5 分钟））。较短的时间段可提供更好的安全性，但会导致对 KMS 的更多调用，这可能会在免费套餐之后产生费用。
• 详见官方文档

3.2.12.禁用队列服务端加密功能

不使用服务端加密功能，不影响传输中加密。

/**
 * 禁用队列服务端加密功能
 * 
 * @param queueUrl - 队列url，必填
 * @param queueName - 队列名称，必填
*/
void disableServerSideEncryptionByName(String queueName)

void disableServerSideEncryptionByUrl(String queueUrl)

注：

• 详见官方文档

---

4.查询当前区域中的队列列表

/**
 * 查询当前区域中的队列列表
 * 
 * @param maxResults - 最大返回数量，非必填
 * @param queueNamePrefix - 队列名称前缀，非必填
 * @return 队列url集合
*/
List<String> listQueues()

List<String> listQueues(Integer maxResults, String queueNamePrefix)

注：

• 参数 maxResults - 最大返回数量，默认值为1000，最大值也为1000。

---

5.获取队列属性集合

获取指定队列的指定属性的属性值。

/**
 * 获取队列属性集合
 * 
 * @param queueUrl - 队列url，必填
 * @param attributeNames - 想要返回的属性的集合，非必填
 * @return 响应体
*/
GetQueueAttributesResponse getQueueAttributes(String queueUrl, List<QueueAttributeNameEnum> attributeNames)

注：

• 参数 attributeNames - 想要返回的属性的集合，不传或传空集时默认获取所有属性。
• 响应体中的 attributes 为获取到的属性-属性值Map，类型为Map<String, String>。

---

6.查询指定死信队列的源队列集合

源队列与死信队列的关系为多对一，即一个源队列只能有一个死信队列，一个死信队列可以被多个源队列配置。该接口查询的就是配置了指定死信队列的所有源队列。

/**
 * 查询指定死信队列的源队列集合
 * 
 * @param queueUrl - 死信队列url，必填
 * @param maxResults - 最大返回数量，非必填
 * @param nextToken - 翻页参数，非必填
 * @return 响应体
*/
ListDeadLetterSourceQueuesResponse listDeadLetterSourceQueues(String queueUrl, Integer maxResults, String nextToken)

注：

• 参数 maxResults - 最大返回数量，默认值为1000，最大值也为1000。
• 参数 nextToken - 从当前接口的响应体中获取，用于翻页查询下一页。
• 响应体中的 queueUrls 为源队列url集合。
• 响应体中的 nextToken 为查询下一页的翻页参数。

---

7.给队列添加标签和值

向队列中添加标签，以帮助组织和识别队列，标签没有任何语义含义。

/**
 * 给队列添加标签和值
 * 
 * @param queueUrl - 队列url，必填
 * @param tags - 标签Map，必填且不为空
*/
void tagQueue(String queueUrl, Map<String, String> tags)

注：

• 建议队列的标签数量不超过 50 个。
• 标签区分大小写。
• 相同的新标签将覆盖现有的标签。

---

8.查询队列标签集合

/**
 * 查询队列标签集合
 * 
 * @param queueUrl - 队列url，必填
 * @return 响应体
*/
ListQueueTagsResponse listQueueTags(String queueUrl)

注：

• 响应体中的 tags 为获取到的标签-标签值Map，类型为Map<String, String>。

---

9.删除队列中指定的标签

/**
 * 删除队列中指定的标签
 * 
 * @param queueUrl - 队列url，必填
 * @param tagKeys - 要删除的标签的key的集合，必填且不为空
 * @return 队列url
*/
void untagQueue(String queueUrl, List<String> tagKeys)

注：

• 若队列中存在参数 tagKeys 中的标签，则删除对应标签；若队列中不存在参数 tagKeys 中的标签，则跳过，接口不会报错。

---

10.添加权限

为特定主体向队列添加权限 。这允许共享对队列的访问。创建队列时，队列的所有者对队列具有完全控制访问权限。只有队列的所有者可以授予或拒绝对队列的权限。

/**
 * 添加权限
 * 
 * @param queueUrl - 队列url，必填
 * @param actions - 客户端希望对指定主体允许的操作，必填
 * @param label - 正在添加的权限的唯一标识，必填
 * @param awsAccountIds - 被授予权限的委托人的 AWS 账号，必填
*/
void addPermission(String queueUrl, List<String> actions, String label, List<String> awsAccountIds)

注：

• 参数 actions - 有效值：任何操作的名称或*。
• 参数 label - 最多80个字符，允许的字符包括字母数字字符、连字符-和下划线_。例如：AliceSendMessage。
• 参数 awsAccountIds - 委托人必须拥有 AWS 账户，但不需要注册 Amazon SQS。
• 详见官方文档

---

11.删除权限

撤销队列策略中与指定Label参数匹配的任何权限。只有队列的所有者才能从中删除权限，跨账户权限不适用于此操作。

/**
 * 删除权限
 * 
 * @param queueUrl - 队列url，必填
 * @param label - 要删除的权限的标识，必填
*/
void removePermission(String queueUrl, String label)

注：

• 参数 label - 这是使用AddPermission操作添加的标签。
• 详见官方文档

---

12.清空队列

删除指定队列中的消息。

/**
 * 清空队列
 * 
 * @param queueUrl - 队列url，必填
*/
void purgeQueue(String queueUrl)

注：

• 详见官方文档

---

13.删除队列

删除指定的队列。

/**
 * 删除队列
 * 
 * @param queueUrl - 队列url，必填
*/
void deleteQueue(String queueUrl)

注：

• 删除队列时，队列中的任何消息都不再可用。
• 删除队列时，删除过程最多需要 60 秒。您在 60 秒内发送的涉及该队列的请求可能会成功。例如， 请求可能成功，但 60 秒后队列和您发送的消息不再存在。
• 删除队列时，必须等待至少 60 秒才能创建同名队列。
• 详见官方文档