Aplicar uma política de filtro de assinatura no Amazon SNS

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

A filtragem de mensagens no Amazon SNS permite que você entregue mensagens seletivamente aos assinantes com base nas políticas de filtro. Essas políticas definem as condições que as mensagens devem atender para serem entregues a uma assinatura. Embora a entrega de mensagens brutas seja uma opção que possa afetar o processamento de mensagens, ela não é necessária para que os filtros de assinatura funcionem.

É possível aplicar uma política de filtro a uma assinatura do Amazon SNS usando o console do Amazon SNS. Ou, para aplicar políticas de forma programática, você pode usar a API do Amazon SNS, AWS Command Line Interface o AWS CLI() ou AWS qualquer SDK compatível com o Amazon SNS. Você também pode usar AWS CloudFormation.

Habilitação da entrega de mensagens brutas

A entrega de mensagens brutas garante que as cargas úteis de mensagens sejam entregues como estão aos assinantes, sem qualquer codificação ou transformação adicional. Isso pode ser útil quando os assinantes precisam do formato original da mensagem para processamento. No entanto, a entrega de mensagens brutas não está diretamente relacionada à funcionalidade dos filtros de assinatura.

Aplicação de filtros de assinatura

Para aplicar filtros de mensagens a uma assinatura, você define uma política de filtro usando a sintaxe JSON. Essa política especifica as condições que uma mensagem deve atender para ser entregue à assinatura. Os filtros podem ser baseados em atributos da mensagem, como atributos da mensagem, estrutura da mensagem ou até mesmo conteúdo da mensagem.

Relação entre entrega de mensagens brutas e filtros de assinatura

Embora a ativação da entrega de mensagens brutas possa afetar a forma como as mensagens são entregues e processadas pelos assinantes, não é um pré-requisito para o uso de filtros de assinatura. No entanto, em cenários em que os assinantes exigem o formato original da mensagem sem nenhuma modificação, habilitar a entrega de mensagens brutas pode ser benéfico junto com os filtros de assinatura.

Considerações para uma filtragem eficaz

Ao implementar a filtragem de mensagens, considere os requisitos específicos do seu aplicativo e dos assinantes. Defina políticas de filtro que correspondam com precisão aos critérios de entrega de mensagens para garantir uma distribuição eficiente e direcionada de mensagens.

AWS Management Console

AWS CLI

Para aplicar uma política de filtro com o AWS Command Line Interface (AWS CLI), use o set-subscription-attributescomando, conforme mostrado no exemplo a seguir. Para a opção --attribute-name, especifique FilterPolicy. Em --attribute-value, especifique sua política JSON.

$ aws sns set-subscription-attributes --subscription-arn arn:aws:sns: ... --attribute-name FilterPolicy --attribute-value '{"store":["example_corp"],"event":["order_placed"]}'

Para fornecer JSON válido para sua política, coloque os nomes e valores dos atributos entre aspas duplas. Também é necessário colocar o argumento completo da política entre aspas. Para evitar aspas de escape, você pode usar aspas simples para colocar a política e aspas duplas para os nomes e valores de JSON, como mostrado no exemplo.

Se você quiser alternar da filtragem de mensagens baseada em atributos (padrão) para a baseada em carga, você também pode usar o comando. set-subscription-attributes Para a opção --attribute-name, especifique FilterPolicyScope. Em --attribute-value, especifique MessageBody.

$ aws sns set-subscription-attributes --subscription-arn arn:aws:sns: ... --attribute-name FilterPolicyScope --attribute-value MessageBody

Para verificar se a política de filtro foi aplicada, use o comando get-subscription-attributes. Os atributos na saída do terminal devem mostrar a política de filtro para a chave FilterPolicy, conforme mostrado no exemplo a seguir:

$ aws sns get-subscription-attributes --subscription-arn arn:aws: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:sns: . . .", 
        "TopicArn": "arn:aws:sns: . . ."
    }
}

AWS SDKs

Os exemplos de código a seguir mostram como usar o SetSubscriptionAttributes.

CLI

AWS CLI

Para definir atributos de assinatura

O exemplo set-subscription-attributes a seguir define o atributo RawMessageDelivery para uma assinatura do SQS.

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

Este comando não produz saída.

O exemplo set-subscription-attributes a seguir define um atributo FilterPolicy para uma assinatura do SQS.

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\"] }"

Este comando não produz saída.

O exemplo set-subscription-attributes a seguir remove o atributo FilterPolicy de uma assinatura do SQS.

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 "{}"

Este comando não produz saída.

• Para obter detalhes da API, consulte SetSubscriptionAttributesem Referência de AWS CLI Comandos.

Java

SDK para Java 2.x

nota

Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no Repositório de exemplos de código da AWS.

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);
        }
    }
}

• Para obter detalhes da API, consulte SetSubscriptionAttributesa Referência AWS SDK for Java 2.x da API.

Python

SDK para Python (Boto3)

nota

Tem mais sobre GitHub. Encontre o exemplo completo e saiba como configurar e executar no Repositório de exemplos de código da AWS.

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

• Para obter detalhes da API, consulte a SetSubscriptionAttributesReferência da API AWS SDK for Python (Boto3).

anchoranchoranchor

• CLI
• Java
• Python

AWS CLI

Para definir atributos de assinatura

O exemplo set-subscription-attributes a seguir define o atributo RawMessageDelivery para uma assinatura do SQS.

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

Este comando não produz saída.

O exemplo set-subscription-attributes a seguir define um atributo FilterPolicy para uma assinatura do SQS.

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\"] }"

Este comando não produz saída.

O exemplo set-subscription-attributes a seguir remove o atributo FilterPolicy de uma assinatura do SQS.

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 "{}"

Este comando não produz saída.

• Para obter detalhes da API, consulte SetSubscriptionAttributesem Referência de AWS CLI Comandos.

API do Amazon SNS

Para aplicar um política de filtro com a API do Amazon SNS, faça uma solicitação para a ação SetSubscriptionAttributes. Defina o parâmetro AttributeName como FilterPolicy e defina o parâmetro AttributeValue para a política de filtro JSON.

Se você quiser mudar da filtragem baseada em atributos (padrão) para a filtragem baseada em carga útil, também poderá usar a ação SetSubscriptionAttributes. Defina o parâmetro AttributeName como FilterPolicyScope e defina o parâmetro AttributeValue como MessageBody.

AWS CloudFormation

Para aplicar uma política de filtro usando AWS CloudFormation, use um modelo JSON ou YAML para criar uma AWS CloudFormation pilha. Para obter mais informações, consulte a FilterPolicypropriedade do AWS::SNS::Subscription recurso no Guia do AWS CloudFormation usuário e no AWS CloudFormation modelo de exemplo.