Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Appliquer une politique de filtrage des abonnements sur Amazon SNS

Le filtrage des messages sur Amazon vous SNS permet de distribuer des messages de manière sélective aux abonnés en fonction des politiques de filtrage. Ces politiques définissent les conditions que les messages doivent remplir pour être livrés dans le cadre d'un abonnement. Bien que la livraison de messages bruts soit une option susceptible d'affecter le traitement des messages, elle n'est pas obligatoire pour que les filtres d'abonnement fonctionnent.

Vous pouvez appliquer une politique de filtrage à un SNS abonnement Amazon à l'aide de la SNS console Amazon. Ou, pour appliquer des politiques par programmation, vous pouvez utiliser Amazon SNSAPI, le AWS Command Line Interface (AWS CLI) ou tout autre AWS SDK outil compatible avec Amazon. SNS Vous pouvez également utiliser AWS CloudFormation.

Activation de la livraison de messages bruts

La livraison de messages bruts garantit que les charges utiles des messages sont livrées telles quelles aux abonnés, sans aucun codage ni transformation supplémentaire. Cela peut être utile lorsque les abonnés ont besoin du format de message d'origine pour le traitement. Cependant, la livraison de messages bruts n'est pas directement liée à la fonctionnalité des filtres d'abonnement.

Appliquer des filtres d'abonnement

Pour appliquer des filtres de messages à un abonnement, vous devez définir une politique de filtrage à l'aide de JSON la syntaxe. Cette politique précise les conditions qu'un message doit remplir pour être délivré dans le cadre de l'abonnement. Les filtres peuvent être basés sur les attributs du message, tels que les attributs du message, la structure du message ou même le contenu du message.

Relation entre la livraison de messages bruts et les filtres d'abonnement

Bien que l'activation de la livraison de messages bruts puisse affecter la manière dont les messages sont distribués et traités par les abonnés, elle n'est pas une condition préalable à l'utilisation de filtres d'abonnement. Toutefois, dans les scénarios où les abonnés ont besoin du format de message d'origine sans aucune modification, l'activation de la livraison des messages bruts peut être avantageuse parallèlement aux filtres d'abonnement.

Considérations relatives à un filtrage efficace

Lors de la mise en œuvre du filtrage des messages, tenez compte des exigences spécifiques de votre application et de vos abonnés. Définissez des politiques de filtrage qui correspondent exactement aux critères de diffusion des messages afin de garantir une distribution efficace et ciblée des messages.

AWS Management Console

AWS CLI

Pour appliquer une politique de filtrage avec le AWS Command Line Interface (AWS CLI), utilisez la set-subscription-attributescommande, comme indiqué dans l'exemple suivant. Pour l'option --attribute-name, spécifiez FilterPolicy. Pour--attribute-value, spécifiez votre JSONpolitique.

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

Pour que votre politique JSON soit valide, placez les noms et les valeurs des attributs entre guillemets. Vous devez également placer la totalité de l'argument de la politique entre guillemets. Pour éviter d'échapper aux guillemets, vous pouvez utiliser des guillemets simples pour encadrer la politique et des guillemets doubles pour placer les JSON noms et les valeurs, comme indiqué dans l'exemple ci-dessus.

Si vous souhaitez passer du filtrage des messages basé sur les attributs (par défaut) au filtrage des messages basé sur la charge utile, vous pouvez également utiliser la set-subscription-attributescommande. Pour l'option --attribute-name, spécifiez FilterPolicyScope. Pour --attribute-value, spécifiez MessageBody.

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

Pour vérifier que votre politique de filtre a été appliquée, utilisez la commande get-subscription-attributes. Les attributs dans la sortie du terminal doivent afficher votre politique de filtre pour la clé FilterPolicy, comme illustré dans l'exemple suivant:

$ 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

Les exemples de code suivants montrent comment utiliserSetSubscriptionAttributes.

CLI

AWS CLI

Pour définir des attributs d'abonnement

L'set-subscription-attributesexemple suivant définit l'RawMessageDeliveryattribut sur un SQS abonnement.

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

Cette commande ne produit aucun résultat.

L'set-subscription-attributesexemple suivant définit un FilterPolicy attribut pour un SQS abonnement.

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

Cette commande ne produit aucun résultat.

L'set-subscription-attributesexemple suivant supprime l'FilterPolicyattribut d'un SQS abonnement.

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

Cette commande ne produit aucun résultat.

• Pour API plus de détails, voir SetSubscriptionAttributesla section Référence des AWS CLI commandes.

Java

SDKpour Java 2.x

Note

Il y en a plus à ce sujet GitHub. Trouvez l'exemple complet et découvrez comment le configurer et l'exécuter dans le référentiel d'exemples de code 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);
        }
    }
}

• Pour API plus de détails, voir SetSubscriptionAttributesla section AWS SDK for Java 2.x APIRéférence.

Python

SDKpour Python (Boto3)

Note

Il y en a plus à ce sujet GitHub. Trouvez l'exemple complet et découvrez comment le configurer et l'exécuter dans le référentiel d'exemples de code 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

• Pour API plus de détails, reportez-vous SetSubscriptionAttributesà la section AWS SDKrelative à la référence Python (Boto3). API

Amazon SNS API

Pour appliquer une politique de filtrage auprès d'Amazon SNSAPI, envoyez une demande à l'SetSubscriptionAttributesaction. Définissez le AttributeName paramètre sur FilterPolicy et réglez le AttributeValue paramètre sur votre politique de filtrageJSON.

Si vous souhaitez passer du filtrage des messages basé sur les attributs (par défaut) au filtrage des messages basé sur la charge utile, vous pouvez également utiliser l'action SetSubscriptionAttributes. Définissez le paramètre AttributeName sur FilterPolicyScope, puis le paramètre AttributeValue sur MessageBody.

AWS CloudFormation

Pour appliquer une politique de filtrage à l'aide d'un YAML modèle JSON ou AWS CloudFormation, utilisez un modèle ou pour créer une AWS CloudFormation pile. Pour plus d'informations, consultez la FilterPolicypropriété de la AWS::SNS::Subscription ressource dans le guide de AWS CloudFormation l'utilisateur et l'exemple de AWS CloudFormation modèle.