Amazon Simple Queue Service
开发人员指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

使用 Amazon SQS 消息属性

Amazon SQS 提供对消息属性 的支持。消息属性可使您提供消息相关的结构化元数据项目 (如时间戳、地理空间数据、签名和标识符)。消息属性是可选的,并独立于消息正文 (但随之一起发送)。此信息可以由消息的接收方用于帮助决定如何处理消息,而不必先处理消息正文。每条消息最多可以包含 10 个属性。要指定消息属性,您可以使用 AWS 管理控制台、AWS 软件开发工具包或查询 API。

消息属性项目和验证

每个消息属性包含以下项目:

  • Name – 消息属性名称可以包含以下字符:A-Za-z0-9、下划线 (_)、连字符 (-) 和句点 (.)。名称不得以句点开头或结尾,并且不应包含连续句点。名称区分大小写,且必须在消息的所有属性名称中是唯一的。名称最多可以有 256 个字符。名称不能以 AWS.Amazon. (或任何大小写变体) 开头,因为这些前缀已预留供 Amazon Web Services 使用的。

  • 类型 – 受支持的消息属性数据类型是字符串、数字和二进制。您也可以提供有关类型的自定义信息。数据类型在内容方面具有与消息正文相同的限制。数据类型区分大小写,长度可以最多为 256 字节。想要了解更多信息,请参阅消息属性数据类型和验证部分。

  • – 用户指定的消息属性值。对于字符串数据类型,值属性在内容方面具有与消息正文相同的限制。有关更多信息,请参阅 SendMessage

名称、类型和值都不得为空或 null。此外,消息正文也不应为空或 null。消息属性的所有部分 (包括名称、类型和值) 都包含在消息大小限制中,该限制当前是 256 KB (262144 个字节)。

消息属性数据类型和验证

消息属性数据类型标识 Amazon SQS 处理消息属性值的方式。例如,如果类型是数字,则 Amazon SQS 会验证它是否为数字。

Amazon SQS 支持以下逻辑数据类型 (使用可选的自定义类型标签) :

字符串 .<自定义类型> (可选)
数字 .<自定义类型> (可选)
二进制 .<自定义类型> (可选)
  • 字符串 – 字符串是使用 UTF-8 二进制编码的 Unicode。若要获取代码值的列表,请访问 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters

  • 数字 – 数字是正或负整数或是浮点数。数字具有足够的范围和精度,以便包含整数、浮点数和双精度数通常支持的大多数可能值。数字最多可有 38 位数字精度,并且介于 10^-128 到 10^+126 之间。系统会删减开头和结尾的 0。

  • 二进制 – 二进制类型属性可以存储任何二进制数据,例如压缩数据、加密数据或图像。

  • 自定义类型 – 您可以将自定义类型标签附加到支持的数据类型 (字符串、数字、二进制) 以创建自定义数据类型。此功能类似于编程语言中的 type traits。例如,如果您的应用程序需要知道在消息中发送的数字类型,则您可以创建类似于下面这样的自定义类型:Number.byteNumber.shortNumber.intNumber.float。使用二进制数据类型的另一个示例是使用 Binary.gifBinary.png 在一个消息或批量消息中区分不同的图像文件类型。附加数据是可选的并且对于 Amazon SQS 不透明,这意味着 Amazon SQS 不会解释、验证或使用附加数据。自定义类型扩展在允许的字符方面具有与消息正文相同的限制。

通过 AWS 管理控制台使用消息属性

您可以使用 AWS 管理控制台配置消息属性。在 Amazon SQS 控制台中选中一个队列,选择 Queue Actions 下拉列表,然后选择 Send a Message。控制台需要用户输入 Base-64 编码的值以便发送二进制类型。

Message Attributes 选项卡上,为消息属性输入名称,选择类型,然后输入值。(可选) 您还可以将自定义信息附加到类型。例如,以下屏幕显示选择了 Number (数字) 类型,并添加了 byte (字节) 以进行自定义。有关支持的数据类型的自定义数据的更多信息,请参阅消息属性数据类型和验证部分。

要添加属性,请选择 Add Attribute。属性信息随后会出现在 NameTypeValues 列表中。

您还可以使用控制台查看有关收到的消息的消息属性的信息。在控制台中选择一个队列,然后从 Queue Actions 下拉列表中选择 View/Delete Messages。在消息列表中选择 Message Details 可查看信息。例如,您可以查看消息属性大小和 MD5 消息摘要。

利用 AWS 软件开发工具包来使用消息属性

AWS 软件开发工具包提供了多种语言的 API,以便将消息属性用于 Amazon SQS。本节包括一些 Java 示例,用于演示如何使用消息属性。这些示例可以与 适用于 Java 的开发工具包 中的 SimpleQueueServiceSample.java 示例集成。最新的 适用于 Java 的开发工具包 会自动计算 MessageBody 和 MessageAttributes 校验和并将其与 Amazon SQS 返回的数据进行比较。有关 适用于 Java 的开发工具包 的更多信息,请参阅适用于 Java 的 AWS 开发工具包入门

以下三个 Java 示例演示如何使用 MessageAttributeValue 方法设置消息属性的 StringNumberBinary 参数:

字符串

Copy
Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("attributeName", new MessageAttributeValue().withDataType("String").withStringValue("string-value-attribute-value"));

数字

Copy
Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("attributeName", new MessageAttributeValue().withDataType("Number").withStringValue("230.000000000000000001"));

二进制

Copy
Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("attributeName", new MessageAttributeValue().withDataType("Binary").withBinaryValue(ByteBuffer.wrap(new byte[10])));

以下三个示例演示如何将可选的自定义类型用于消息属性:

字符串 – 自定义

Copy
Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("AccountId", new MessageAttributeValue().withDataType("String.AccountId").withStringValue("000123456"));

数字 – 自定义

Copy
// NOTE Because the type is a number, the result in the receive message call will be 123456. Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("AccountId", new MessageAttributeValue().withDataType("Number.AccountId").withStringValue("000123456"));

二进制 – 自定义

Copy
Map<String, MessageAttributeValue> messageAttributes = new HashMap<>(); messageAttributes.put("PhoneIcon", new MessageAttributeValue().withDataType("Binary.JPEG").withBinaryValue(ByteBuffer.wrap(new byte[10])));

要使用前面的消息属性示例之一发送消息,您的代码应类似于以下内容:

Copy
SendMessageRequest request = new SendMessageRequest(); request.withMessageBody("A test message body."); request.withQueueUrl("MyQueueUrlStringHere"); request.withMessageAttributes(messageAttributes); sqs.sendMessage(request);

通过 Amazon SQS 查询 API 使用消息属性

要使用查询 API 指定消息属性,请调用 SendMessageSendMessageBatchReceiveMessage 操作。

此示例的查询 API 请求类似于以下内容:

您如何构造 AUTHPARAMS 取决于您签署 API 请求的方式。有关签名版本 4 中的 AUTHPARAMS 的信息,请参阅已签名的签名版本 4 请求示例

Copy
POST http://sqs.us-east-2.amazonaws.com/123456789012/MyQueue ... ?Action=SendMessage &MessageBody=This+is+a+test+message &MessageAttribute.1.Name=test_attribute_name_1 &MessageAttribute.1.Value.StringValue=test_attribute_value_1 &MessageAttribute.1.Value.DataType=String &MessageAttribute.2.Name=test_attribute_name_2 &MessageAttribute.2.Value.StringValue=test_attribute_value_2 &MessageAttribute.2.Value.DataType=String &Version=2012-11-05 &Expires=2014-05-05T22%3A52%3A43PST &AUTHPARAMS

注意

队列名称和队列 URL 区分大小写。

查询 API 响应应类似于以下内容:

Copy
HTTP/1.1 200 OK ... <SendMessageResponse> <SendMessageResult> <MD5OfMessageBody> fafb00f5732ab283681e124bf8747ed1 </MD5OfMessageBody> <MD5OfMessageAttributes> 3ae8f24a165a8cedc005670c81a27295 </MD5OfMessageAttributes> <MessageId> 5fea7756-0ea4-451a-a703-a558b933e274 </MessageId> </SendMessageResult> <ResponseMetadata> <RequestId> 27daac76-34dd-47df-bd01-1f6e873584a0 </RequestId> </ResponseMetadata> </SendMessageResponse>

使用 SendMessageBatch 时,需要为批处理中的每个消息指定消息属性。

此示例的查询 API 请求类似于以下内容:

Copy
POST http://sqs.us-east-2.amazonaws.com/123456789012/MyQueue ... ?Action=SendMessageBatch &SendMessageBatchRequestEntry.1.Id=test_msg_001 &SendMessageBatchRequestEntry.1.MessageBody=test%20message%20body%201 &SendMessageBatchRequestEntry.2.Id=test_msg_002 &SendMessageBatchRequestEntry.2.MessageBody=test%20message%20body%202 &SendMessageBatchRequestEntry.2.DelaySeconds=60 &SendMessageBatchRequestEntry.2.MessageAttribute.1.Name=test_attribute_name_1 &SendMessageBatchRequestEntry.2.MessageAttribute.1.Value.StringValue=test_attribute_value_1 &SendMessageBatchRequestEntry.2.MessageAttribute.1.Value.DataType=String &Version=2012-11-05 &Expires=2014-05-05T22%3A52%3A43PST &AUTHPARAMS

查询 API 响应应类似于以下内容:

Copy
HTTP/1.1 200 OK ... <SendMessageBatchResponse> <SendMessageBatchResult> <SendMessageBatchResultEntry> <Id>test_msg_001</Id> <MessageId>0a5231c7-8bff-4955-be2e-8dc7c50a25fa</MessageId> <MD5OfMessageBody>0e024d309850c78cba5eabbeff7cae71</MD5OfMessageBody> </SendMessageBatchResultEntry> <SendMessageBatchResultEntry> <Id>test_msg_002</Id> <MessageId>15ee1ed3-87e7-40c1-bdaa-2e49968ea7e9</MessageId> <MD5OfMessageBody>7fb8146a82f95e0af155278f406862c2</MD5OfMessageBody> <MD5OfMessageAttributes>295c5fa15a51aae6884d1d7c1d99ca50</MD5OfMessageAttributes> </SendMessageBatchResultEntry> </SendMessageBatchResult> <ResponseMetadata> <RequestId>ca1ad5d0-8271-408b-8d0f-1351bf547e74</RequestId> </ResponseMetadata> </SendMessageBatchResponse>

MD5 消息摘要计算

如果您要为 Amazon SQS 消息属性计算 MD5 消息摘要,但使用的是不支持 Amazon SQS 消息属性 MD5 消息摘要的查询 API 或 AWS 软件开发工具包之一,则必须使用有关算法的以下信息计算消息属性的 MD5 消息摘要。

注意

当前,AWS SDK for Java 对于 Amazon SQS 消息属性支持 MD5 消息摘要。这可在 MessageMD5ChecksumHandler 类中获得。如果您使用 适用于 Java 的开发工具包,则无需使用以下信息。

为 Amazon SQS 消息属性计算 MD5 消息摘要的算法的宏观步骤是:

  1. 按名称的升序对所有消息属性进行排序。

  2. 将每个属性的各个部分 (名称、类型和值) 进行编码并存入缓冲区。

  3. 计算整个缓冲区的消息摘要。

对单个 Amazon SQS 消息属性编码:

  1. 对名称编码 (名称长度 [4 字节] + 名称的 UTF-8 字节)。

  2. 对类型编码 (类型长度 [4 字节] + 类型的 UTF-8 字节)。

  3. 对值的传输类型 (字符串或二进制) 编码 [1 个字节]。

    1. 对于字符串 传输类型,编码为 1。

    2. 对于二进制 传输类型,编码为 2。

    注意

    字符串和数字逻辑数据类型使用字符串 传输类型。二进制逻辑数据类型使用二进制 传输类型。

  4. 对属性值编码。

    1. 对于字符串 传输类型,对属性值编码 (长度 [4 字节] + 值的 UTF-8 字节)。

    2. 对于二进制 传输类型,对属性值编码 (长度 [4 字节] + 直接使用原始字节)。

下图演示单个消息属性的 MD5 消息摘要的编码: