Amazon Simple Notification Service
开发人员指南 (API Version 2010-03-31)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

使用 Amazon SNS 消息属性

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

重要

要对 Amazon SQS 终端节点使用消息属性,必须将订阅属性 Raw Message Delivery 设置为 True。有关原始消息传递的详细信息,请参阅 附录:大型负载和原始消息传输

您还可以使用消息属性,帮助构造移动终端节点的推送通知消息。在这种情况下,消息属性仅用于帮助构造和推送通知消息。这些属性不会被传递到终端节点,就像在发送带有消息属性的消息到 Amazon SQS 终端节点时一样。

您还可以使用消息属性来让消息变为可通过订阅筛选策略进行筛选。可以将筛选策略应用于主题订阅。应用了筛选策略后,订阅将只接收具有策略接受的属性的消息。有关更多信息,请参阅 使用 Amazon SNS 筛选消息

消息属性项目和验证

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

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

  • Type – 受支持的消息属性数据类型有 StringString.ArrayNumberBinary。数据类型在内容方面具有与消息正文相同的限制。数据类型区分大小写,长度最多可以为 256 字节。想要了解更多信息,请参阅消息属性数据类型和验证部分。

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

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

消息属性数据类型和验证

消息属性数据类型指示 Amazon SNS 处理消息属性值的方式。举例来说,如果类型是数字,则 Amazon SNS 会验证它是否为数字。

Amazon SNS 支持以下逻辑数据类型:

  • 字符串 – 字符串是使用 UTF-8 二进制编码的 Unicode。若要获取代码值的列表,请访问 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters

  • String.Array – 格式为字符串的阵列,可以包含多个值。这些值可以是字符串、数字或关键字 truefalsenull

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

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

为移动推送通知预留的消息属性

下表列出了可用于构造推送通知消息的移动推送通知服务的预留消息属性:

推送通知服务 预留的消息属性 允许的值

Baidu

AWS.SNS.MOBILE.BAIDU.DeployStatus(可选)

AWS.SNS.MOBILE.BAIDU.MessageType(可选)

AWS.SNS.MOBILE.BAIDU.MessageKey(可选)

1 - 开发环境。2 - 生产环境。(默认值 1)

0 - 应用程序内消息。1 - 警报通知。(默认值 1)

短消息标识符,可附加到您的消息

MPNS

AWS.SNS.MOBILE.MPNS.Type(必需

AWS.SNS.MOBILE.MPNS.NotificationClass(必需

令牌(用于磁贴通知),toast,raw

实时,优先级,常规

WNS

AWS.SNS.MOBILE.WNS.Type(必需

AWS.SNS.MOBILE.WNS.CachePolicy(可选)

AWS.SNS.MOBILE.WNS.Group(可选)

AWS.SNS.MOBILE.WNS.Match(可选)

AWS.SNS.MOBILE.WNS.SuppressPopup(可选)

AWS.SNS.MOBILE.WNS.Tag(可选)

X-WNS-Type 相同

X-WNS-Cache-Policy 相同

X-WNS-Group 相同

X-WNS-Match 相同

X-WNS-SuppressPopup 相同

X-WNS-Tag 相同

有关与 Baidu 一起使用消息属性的更多信息,请参阅使用消息属性来构造消息

应用消息属性

您可以使用 Amazon SNS API、AWS Command Line Interface (AWS CLI) 或任何支持 Amazon SNS 的 AWS 软件开发工具包 (如 AWS SDK for Java) 来发布带有属性的消息。

通过 AWS CLI 应用消息属性

要使用 AWS CLI 发布带有属性的消息,请使用 publish 命令以及参数 --message-attributes,如以下示例所示:

Copy
$ aws sns publish --topic-arn topic-arn --message “message” --message-attributes '{"store":{"DataType":"String","StringValue":"example_corp"}'

通过 AWS SDK for Java 应用消息属性

要使用 AWS SDK for Java 发布带属性的消息,请使用 AmazonSNS 客户端的 publish 方法。提供 PublishRequest 对象作为参数。当您初始化 PublishRequest 对象时,使用其 withMessageAttributes 方法,这将接受 Map<String,MessageAttributeValue> 类型的映射。

为了简化发布带属性的消息的过程,您可以向应用程序添加以下示例类并根据需要修改它:

Copy
import com.amazonaws.services.sns.*; import com.amazonaws.services.sns.model.MessageAttributeValue; import com.amazonaws.services.sns.model.PublishRequest; import com.amazonaws.services.sns.model.PublishResult; import java.util.ArrayList; import java.util.HashMap; import java.util.Map; import java.util.stream.Collectors; public class SNSMessage { public String message; public Map<String, MessageAttributeValue> messageAttributes; public SNSMessage(String message) { this.message = message; messageAttributes = new HashMap<>(); } public void setMessage(String message) { this.message = message; } public String getMessage() { return message; } public void addAttribute(String attributeName, String attributeValue) { MessageAttributeValue messageAttributeValue = new MessageAttributeValue() .withDataType("String") .withStringValue(attributeValue); messageAttributes.put(attributeName, messageAttributeValue); } public void addAttribute(String attributeName, ArrayList<?> attributeValues) { String valuesString, delimiter = ", ", prefix = "[", suffix = "]"; if (attributeValues.get(0).getClass() == String.class) { delimiter = "\", \""; prefix = "[\""; suffix = "\"]"; } valuesString = attributeValues .stream() .map(value -> value.toString()) .collect(Collectors.joining(delimiter, prefix, suffix)); MessageAttributeValue messageAttributeValue = new MessageAttributeValue() .withDataType("String.Array") .withStringValue(valuesString); messageAttributes.put(attributeName, messageAttributeValue); } public String publish(AmazonSNS snsClient, String topicArn) { PublishRequest request = new PublishRequest(topicArn, message) .withMessageAttributes(messageAttributes); PublishResult result = snsClient.publish(request); return result.getMessageId(); } }

该类存储 messageAttributes 字段作为映射。您可以使用重载 addAttribute 方法将属性添加到消息。这些方法可以添加数据类型为 StringString.Array 的属性。当您准备发布消息时,请使用 publish 方法,并提供一个 AmazonSNS 客户端和主题 ARN。

下面的代码演示如何初始化和使用示例 SNSMessage 类:

Copy
// Initialize example message class SNSMessage message = new SNSMessage(messageBody); // Add message attribute with single value message.addAttribute("store", "example_corp"); message.addAttribute("event", "order_placed"); // Add message attribute with a list of values ArrayList<String> interestsValues = new ArrayList<>(); interestsValues.add("soccer"); interestsValues.add("rugby"); interestsValues.add("hockey"); message.addAttribute("customer_interests", interestsValues); // Add boolean attribute for filtering with subscription filter policies. // SNSMessage will apply a String.Array data type to this attribute, // which makes it eligible for evaluating with a filter policy. ArrayList<Boolean> encryptedVal = new ArrayList<>(); encrypted.add(false); message.addAttribute("encrypted", encryptedVal); // Publish message message.publish(snsClient, topicArn);

通过 Amazon SNS API 应用消息属性

要使用 Amazon SNS API 发布带有属性的消息,请发出 Publish 操作请求,并使用 MessageAttributes 参数。