Applying a subscription filter policy in Amazon SNS
Message filtering in Amazon SNS allows you to selectively deliver messages to subscribers based on filter policies. These policies define conditions that messages must meet to be delivered to a subscription. While raw message delivery is an option that can affect message processing, it is not required for subscription filters to work.
You can apply a filter policy to an Amazon SNS subscription using the Amazon SNS console. Or, to apply policies programmatically, you can use the Amazon SNS API, the Amazon Command Line Interface (Amazon CLI), or any Amazon SDK that supports Amazon SNS. You can also use Amazon CloudFormation.
Enabling Raw Message Delivery
Raw message delivery ensures that message payloads are delivered as-is to subscribers without any additional encoding or transformation. This can be useful when subscribers require the original message format for processing. However, raw message delivery is not directly related to the functionality of subscription filters.
Applying Subscription Filters
To apply message filters to a subscription, you define a filter policy using JSON syntax. This policy specifies the conditions that a message must meet to be delivered to the subscription. Filters can be based on message attributes, such as message attributes, message structure, or even message content.
Relationship between Raw Message Delivery and Subscription Filters
While enabling raw message delivery can affect how messages are delivered and processed by subscribers, it is not a prerequisite for using subscription filters. However, in scenarios where subscribers require the original message format without any modifications, enabling raw message delivery might be beneficial alongside subscription filters.
Considerations for Effective Filtering
When implementing message filtering, consider the specific requirements of your application and subscribers. Define filter policies that accurately match the criteria for message delivery to ensure efficient and targeted message distribution.
Important
Amazon services such as IAM and Amazon SNS use a distributed computing model called eventual consistency. Additions or changes to a subscription filter policy require up to 15 minutes to fully take effect.
Amazon Web Services Management Console
Sign in to the Amazon SNS console
. -
On the navigation panel, choose Subscriptions.
-
Select a subscription and then choose Edit.
-
On the Edit page, expand the Subscription filter policy section.
-
Choose between attribute-based filtering or payload-based filtering.
-
In the JSON editor field, provide the JSON body of your filter policy.
-
Choose Save changes.
Amazon SNS applies your filter policy to the subscription.
Amazon CLI
To apply a filter policy with the Amazon Command Line Interface (Amazon CLI), use the set-subscription-attributes
command, as shown in the
following example. For the --attribute-name
option, specify
FilterPolicy
. For --attribute-value
, specify your
JSON policy.
$
aws sns set-subscription-attributes --subscription-arn
arn:aws-cn:sns: ...
--attribute-name FilterPolicy --attribute-value'{"store":["example_corp"],"event":["order_placed"]}'
To provide valid JSON for your policy, enclose the attribute names and values in double quotes. You must also enclose the entire policy argument in quotes. To avoid escaping quotes, you can use single quotes to enclose the policy and double quotes to enclose the JSON names and values, as shown in the above example.
If you want to switch from attribute-based (default) to payload-based message
filtering, you can use the set-subscription-attributes command as well. For the
--attribute-name
option, specify FilterPolicyScope
. For
--attribute-value
, specify MessageBody
.
$
aws sns set-subscription-attributes --subscription-arn arn:aws-cn:sns: ... --attribute-name FilterPolicyScope --attribute-value MessageBody
To verify that your filter policy was applied, use the
get-subscription-attributes
command. The attributes in the terminal
output should show your filter policy for the FilterPolicy
key, as shown in
the following example:
$
aws sns get-subscription-attributes --subscription-arn arn:aws-cn:sns: ...
{
"Attributes": {
"Endpoint": "endpoint . . .",
"Protocol": "https",
"RawMessageDelivery": "false",
"EffectiveDeliveryPolicy": "delivery policy . . .",
"ConfirmationWasAuthenticated": "true",
"FilterPolicy": "{\"store\": [\"example_corp\"], \"event\": [\"order_placed\"]}",
"FilterPolicyScope": "MessageAttributes",
"Owner": "111122223333",
"SubscriptionArn": "arn:aws-cn:sns: . . .",
"TopicArn": "arn:aws-cn:sns: . . ."
}
}
Amazon SDKs
The following code examples show how to use SetSubscriptionAttributes
.
Important
If you are using the SDK for Java 2.x example, the class
SNSMessageFilterPolicy
is not available out of the box. For
instructions on how to install this class, see the example
Amazon SNS API
To apply a filter policy with the Amazon SNS API, make a request to the SetSubscriptionAttributes
action. Set the
AttributeName
parameter to FilterPolicy
, and set the
AttributeValue
parameter to your filter policy JSON.
If you want to switch from attribute-based (default) to payload-based message
filtering, you can use the SetSubscriptionAttributes
action as well. Set the
AttributeName
parameter to FilterPolicyScope
, and set the
AttributeValue
parameter to MessageBody
.
Amazon CloudFormation
To apply a filter policy using Amazon CloudFormation, use a JSON or YAML template to create a Amazon CloudFormation
stack. For more information, see the FilterPolicy
property of the
AWS::SNS::Subscription
resource in the
Amazon CloudFormation User Guide and the example Amazon CloudFormation template
-
Sign in to the Amazon CloudFormation console
. -
Choose Create Stack.
-
On the Select Template page, choose Upload a template to Amazon S3, choose the file, and choose Next.
-
On the Specify Details page, do the following:
-
For Stack Name, type
MyFilterPolicyStack
. -
For myHttpEndpoint, type the HTTP endpoint to be subscribed to your topic.
Tip
If you don't have an HTTP endpoint, create one.
-
-
On the Options page, choose Next.
-
On the Review page, choose Create.