Applying a subscription filter policy - Amazon Simple Notification Service
Amazon Web Services Management ConsoleAmazon CLIAmazon SDKsAmazon SNS APIAmazon CloudFormation
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Applying a subscription filter policy

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.

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

  1. Sign in to the Amazon SNS console.

  2. On the navigation panel, choose Subscriptions.

  3. Select a subscription and then choose Edit.

  4. On the Edit page, expand the Subscription filter policy section.

  5. Choose between attribute-based filtering or payload-based filtering.

  6. In the JSON editor field, provide the JSON body of your filter policy.

  7. 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 from the GitHub website.

CLI
Amazon CLI

To set subscription attributes

The following set-subscription-attributes example sets the RawMessageDelivery attribute to an SQS subscription.

aws sns set-subscription-attributes \
    --subscription-arn arn:aws:sns:us-east-1:123456789012:mytopic:f248de18-2cf6-578c-8592-b6f1eaa877dc \
    --attribute-name RawMessageDelivery \
    --attribute-value true

This command produces no output.

The following set-subscription-attributes example sets a FilterPolicy attribute to an SQS subscription.

aws sns set-subscription-attributes \
    --subscription-arn arn:aws:sns:us-east-1:123456789012:mytopic:f248de18-2cf6-578c-8592-b6f1eaa877dc \
    --attribute-name FilterPolicy \
    --attribute-value "{ \"anyMandatoryKey\": [\"any\", \"of\", \"these\"] }"

This command produces no output.

The following set-subscription-attributes example removes the FilterPolicy attribute from an SQS subscription.

aws sns set-subscription-attributes \
    --subscription-arn arn:aws:sns:us-east-1:123456789012:mytopic:f248de18-2cf6-578c-8592-b6f1eaa877dc \
    --attribute-name FilterPolicy \
    --attribute-value "{}"

This command produces no output.

Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository. 

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.sns.SnsClient;
import software.amazon.awssdk.services.sns.model.SnsException;
import java.util.ArrayList;

/**
 * Before running this Java V2 code example, set up your development
 * environment, including your credentials.
 *
 * For more information, see the following documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 */
public class UseMessageFilterPolicy {
    public static void main(String[] args) {
        final String usage = """

                Usage:    <subscriptionArn>

                Where:
                   subscriptionArn - The ARN of a subscription.

                """;

        if (args.length != 1) {
            System.out.println(usage);
            System.exit(1);
        }

        String subscriptionArn = args[0];
        SnsClient snsClient = SnsClient.builder()
                .region(Region.US_EAST_1)
                .build();

        usePolicy(snsClient, subscriptionArn);
        snsClient.close();
    }

    public static void usePolicy(SnsClient snsClient, String subscriptionArn) {
        try {
            SNSMessageFilterPolicy fp = new SNSMessageFilterPolicy();
            // Add a filter policy attribute with a single value
            fp.addAttribute("store", "example_corp");
            fp.addAttribute("event", "order_placed");

            // Add a prefix attribute
            fp.addAttributePrefix("customer_interests", "bas");

            // Add an anything-but attribute
            fp.addAttributeAnythingBut("customer_interests", "baseball");

            // Add a filter policy attribute with a list of values
            ArrayList<String> attributeValues = new ArrayList<>();
            attributeValues.add("rugby");
            attributeValues.add("soccer");
            attributeValues.add("hockey");
            fp.addAttribute("customer_interests", attributeValues);

            // Add a numeric attribute
            fp.addAttribute("price_usd", "=", 0);

            // Add a numeric attribute with a range
            fp.addAttributeRange("price_usd", ">", 0, "<=", 100);

            // Apply the filter policy attributes to an Amazon SNS subscription
            fp.apply(snsClient, subscriptionArn);

        } catch (SnsException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
    }
}
Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository. 

class SnsWrapper:
    """Encapsulates Amazon SNS topic and subscription functions."""

    def __init__(self, sns_resource):
        """
        :param sns_resource: A Boto3 Amazon SNS resource.
        """
        self.sns_resource = sns_resource


    @staticmethod
    def add_subscription_filter(subscription, attributes):
        """
        Adds a filter policy to a subscription. A filter policy is a key and a
        list of values that are allowed. When a message is published, it must have an
        attribute that passes the filter or it will not be sent to the subscription.

        :param subscription: The subscription the filter policy is attached to.
        :param attributes: A dictionary of key-value pairs that define the filter.
        """
        try:
            att_policy = {key: [value] for key, value in attributes.items()}
            subscription.set_attributes(
                AttributeName="FilterPolicy", AttributeValue=json.dumps(att_policy)
            )
            logger.info("Added filter to subscription %s.", subscription.arn)
        except ClientError:
            logger.exception(
                "Couldn't add filter to subscription %s.", subscription.arn
            )
            raise

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.

  1. Sign in to the Amazon CloudFormation console.

  2. Choose Create Stack.

  3. On the Select Template page, choose Upload a template to Amazon S3, choose the file, and choose Next.

  4. On the Specify Details page, do the following:

    1. For Stack Name, type MyFilterPolicyStack.

    2. For myHttpEndpoint, type the HTTP endpoint to be subscribed to your topic.

      Tip

      If you don't have an HTTP endpoint, create one.

  5. On the Options page, choose Next.

  6. On the Review page, choose Create.