Amazon Simple Notification Service
開発者ガイド (API バージョン 2010-03-31)

Amazon SNS メッセージ属性

Amazon Simple Notification Service (Amazon SNS) では、メッセージ属性を配信できます。メッセージ属性を使用すると、構造化メタデータ項目 (タイムスタンプ、地理空間データ、署名、識別子など) などを指定することができます。メッセージ属性はオプションであり、メッセージ本文とは別個のものですが、同時に送信されます。この情報は、メッセージ本文を処理してからでなくてもメッセージを処理する方法を調べるために、メッセージの受信者が使用できます。各メッセージには最大 10 個の属性を指定できます。メッセージ属性を指定するには、AWS Software Development Kit(SDK)またはクエリ API を使用します。

重要

Amazon SQS エンドポイントでメッセージ属性を使用するには、サブスクリプション属性 Raw Message DeliveryTrue に設定する必要があります。raw メッセージ配信の詳細については、「Amazon SNS ラージペイロードと raw メッセージの配信」を参照してください。

メッセージ属性は、メッセージ構造が JSON ではなく String である場合にのみ送信されます。

また、モバイルエンドポイント用のプッシュ通知メッセージを構築するためにメッセージ属性を使用することもできます。このシナリオでは、メッセージ属性は、プッシュ通知メッセージの構築のみに使用されます。属性は、Amazon SQS エンドポイントにメッセージ属性とともにメッセージを送信する場合とは異なり、エンドポイントには配信されません。

メッセージ属性を使用して、サブスクリプションフィルタポリシーでメッセージをフィルタリング可能にすることもできます。フィルタポリシーはトピックのサブスクリプションに適用します。フィルタポリシーを使用すると、サブスクリプションは、ポリシーで受け入れられた属性を持つメッセージのみを受信します。詳細については、「」を参照してください。

メッセージ属性の項目および検証

各メッセージ属性は、次の項目で構成されています。

  • 名前 – メッセージ属性名には、A-Z、a-z、0-9、下線(_)、ハイフン(-)、ピリオド(.)を使用できます。名前の先頭と末尾をピリオドにすることはできず、ピリオドを連続して使用することはできません。名前では大文字と小文字が区別され、メッセージのすべての属性名間で一意にする必要があります。名前の長さは最大 256 文字です。名前の先頭を「AWS.」や「Amazon.」(または、大文字と小文字が異なるあらゆる変化形) にすることはできません。これらのプレフィックスは Amazon Web Services で使用するために予約されているからです。

  • – サポートされるメッセージ属性のデータ型は、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) とすることができます。

  • 数値 – 数値は正または負の整数か、浮動小数点数です。数値には、整数、浮動小数点数、倍精度浮動小数点数が通常サポートするほとんどの値を包含できる十分な範囲と精度があります。数値は -109~109 までの値とすることができ、小数点以下 5 桁の精度を持ちます。先頭と末尾の 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 (必須)

トークン (タイル通知用)、トースト、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 SDK (AWS SDK for Java など) を使用できます。

コンソールを使用したメッセージ属性の適用

Amazon SNS コンソールを使用して属性を持つメッセージを発行するには、以下のステップを完了します。

  1. AWS マネジメントコンソールにサインインした後、Amazon SNS コンソール (https://console.aws.amazon.com/sns/v2/home) を開きます。

  2. ナビゲーションペインで、[Topics] を選択します。[トピック] ページには、選択したリージョンのすべての Amazon SNS トピックが表示されます。

  3. トピックがない場合は、[Create a new topic] を選択し、[Topic name] の値を指定します。トピックを使用して SMS メッセージを送信する場合は、[Display name] の値を指定します。次に、[Create topic] を選択します。

  4. 1 つ以上のトピックがある場合は、メッセージを発行するトピックを選択します。次に、[Publish to topic] を選択します。

  5. [Publish a message] ページで、[Subject] および [Message] を指定します。

  6. [Message Attributes] で、キー、属性値、および値を指定します。たとえば、以下のエントリによって customer_interests という属性が作成されます。属性タイプは String.Array で、値は値の配列です。

    
                            Amazon SNS コンソールのメッセージ属性。

    属性の型は StringString.Array、または Number であり、Amazon SNS はそのサブスクリプションにメッセージを送信する前に、存在する場合はサブスクリプションのフィルタポリシーに対してメッセージ属性を評価します。

    留意点

    属性の型が String.Array である場合は、配列を角括弧 ([ ]) で囲みます。配列内で、値の文字列を二重引用符内で囲みます。数字またはキーワード truefalsenull を引用符で囲む必要はありません。

AWS CLI を使用したメッセージ属性の適用

AWS CLI を使用して属性と共にメッセージを発行するには、以下の例のように、--message-attributes パラメータを指定して publish コマンドを使用します。

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

AWS SDKs を使用したメッセージ属性の適用

以下の例では、AWS SDK で提供されている Amazon SNS クライアントを使用してメッセージ属性を適用する方法について説明します。

AWS SDK for JavaAWS SDK for .NET
AWS SDK for Java

AWS SDK for Java を使用して属性と共にメッセージを発行するには、AmazonSNS クライアントの publish メソッドを使用します。引数として PublishRequest オブジェクトを指定します。PublishRequest オブジェクトを初期化する場合、型が Map<String,MessageAttributeValue> のマップを受け入れる、その withMessageAttributes メソッドを使用します。

属性とともにメッセージを発行するプロセスを簡素化するには、次のクラス例をアプリケーションに追加し、必要に応じて変更します。

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 void addAttribute(String attributeName, Number attributeValue) { MessageAttributeValue messageAttributeValue = new MessageAttributeValue() .withDataType("Number") .withStringValue(attributeValue.toString()); 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、または Number のデータ型を持つ属性を追加できます。メッセージを発行する準備ができたら、publish メソッドを使用し、AmazonSNS クライアントおよびトピック ARN を提供します。

次のコードサンプルでは、SNSMessage クラスの例を初期化して使用する方法を示します。

// Initialize example message class SNSMessage message = new SNSMessage(messageBody); // Add message attribute with string value message.addAttribute("store", "example_corp"); message.addAttribute("event", "order_placed"); // Add message attribute with a list of string values ArrayList<String> interestsValues = new ArrayList<String>(); interestsValues.add("soccer"); interestsValues.add("rugby"); interestsValues.add("hockey"); message.addAttribute("customer_interests", interestsValues); // Add message attribute with number value message.addAttribute("price_usd", 1000); // 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<Boolean>(); encryptedVal.add(false); message.addAttribute("encrypted", encryptedVal); // Publish message message.publish(snsClient, topicArn);
AWS SDK for .NET

AWS SDK for .NET を使用して属性と共にメッセージを発行するには、AmazonSimpleNotificationServiceClient クライアントの Publish メソッドを使用します。引数として PublishRequest オブジェクトを指定します。PublishRequest オブジェクトを初期化する場合、型が Map<String,MessageAttributeValue> のディクショナリを受け入れる、その MessageAttributes メソッドを使用します。

属性とともにメッセージを発行するプロセスを簡素化するには、次のクラス例をアプリケーションに追加し、必要に応じて変更します。

using System; using System.Collections.Generic; using Amazon.SimpleNotificationService; using Amazon.SimpleNotificationService.Model; namespace SNSCreatePlatformEndpoint { class SNSMessage { private String message; private Dictionary<String, MessageAttributeValue> messageAttributes; public SNSMessage(String message) { this.message = message; messageAttributes = new Dictionary<string, MessageAttributeValue>(); } public string Message { get => this.message; set => this.message = value; } public void AddAttribute(String attributeName, String attributeValue) { messageAttributes[attributeName] = new MessageAttributeValue { DataType = "String", StringValue = attributeValue }; } public void AddAttribute(String attributeName, float attributeValue) { messageAttributes[attributeName] = new MessageAttributeValue { DataType = "Number", StringValue = attributeValue.ToString()}; } public void AddAttribute(String attributeName, int attributeValue) { messageAttributes[attributeName] = new MessageAttributeValue { DataType = "Number", StringValue = attributeValue.ToString() }; } public void AddAttribute(String attributeName, List<String> attributeValue) { String valueString = "[\"" + String.Join("\", \"", attributeValue.ToArray()) + "\"]"; messageAttributes[attributeName] = new MessageAttributeValue { DataType = "String.Array", StringValue = valueString }; } public void AddAttribute(String attributeName, List<float> attributeValue) { String valueString = "[" + String.Join(", ", attributeValue.ToArray()) + "]"; messageAttributes[attributeName] = new MessageAttributeValue { DataType = "String.Array", StringValue = valueString }; } public void AddAttribute(String attributeName, List<int> attributeValue) { String valueString = "[" + String.Join(", ", attributeValue.ToArray()) + "]"; messageAttributes[attributeName] = new MessageAttributeValue { DataType = "String.Array", StringValue = valueString }; } public void AddAttribute(String attributeName, List<Boolean> attributeValue) { String valueString = "[" + String.Join(", ", attributeValue.ToArray()) + "]"; messageAttributes[attributeName] = new MessageAttributeValue { DataType = "String.Array", StringValue = valueString }; } public String Publish(AmazonSimpleNotificationServiceClient snsClient, String topicArn) { PublishRequest request = new PublishRequest { TopicArn = topicArn, MessageAttributes = messageAttributes, Message = message }; PublishResponse result = snsClient.Publish(request); return result.MessageId; } } }

このクラスでは、ディクショナリとして MessageAttributes フィールドを保存します。過負荷になっている AddAttribute メソッドを使用して、メッセージに属性を追加します。これらのメソッドでは、StringString.Array、または Number のデータ型を持つ属性を追加できます。メッセージを発行する準備ができたら、publish メソッドを使用し、AmazonSimpleNotificationServiceClient クライアントおよびトピック ARN を提供します。

次のコードサンプルでは、SNSMessage クラスの例を初期化して使用する方法を示します。

AmazonSimpleNotificationServiceClient snsClient = new AmazonSimpleNotificationServiceClient(Amazon.RegionEndpoint.USWest2); // Initialize example message class SNSMessage message = new SNSMessage(messageBody); // Add message attribute with string value message.AddAttribute("store", "example_corp"); message.AddAttribute("event", "order_placed"); // Add message attribute with a list of string values List<String> interestsValues = new List<String>(); interestsValues.Add("soccer"); interestsValues.Add("rugby"); interestsValues.Add("hockey"); message.AddAttribute("customer_interests", interestsValues); // Add message attribute with number value message.AddAttribute("price_usd", 1000); // 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. List<Boolean> encryptedVal = new List<Boolean>(); encryptedVal.Add(false); message.AddAttribute("encrypted", encryptedVal); // Publish message message.Publish(snsClient, topicArn);

Amazon SNS API を使用したメッセージ属性の適用

Amazon SNS API を使用して属性と共にメッセージを発行するには、Publish アクションへのリクエストを発行し、MessageAttributes パラメータを使用します。