Menerapkan kebijakan filter langganan di Amazon SNS

Pemfilteran pesan di Amazon SNS memungkinkan Anda mengirimkan pesan secara selektif ke pelanggan berdasarkan kebijakan filter. Kebijakan ini menentukan kondisi yang harus dipenuhi pesan agar dikirimkan ke langganan. Meskipun pengiriman pesan mentah adalah opsi yang dapat memengaruhi pemrosesan pesan, filter langganan tidak diperlukan untuk berfungsi.

Anda dapat menerapkan kebijakan filter ke SNS langganan Amazon menggunakan SNS konsol Amazon. Atau, untuk menerapkan kebijakan secara terprogram, Anda dapat menggunakan Amazon SNSAPI, AWS Command Line Interface (AWS CLI), atau apa pun AWS SDK yang mendukung Amazon. SNS Anda juga bisa menggunakan AWS CloudFormation.

Mengaktifkan Pengiriman Pesan Mentah

Pengiriman pesan mentah memastikan bahwa muatan pesan dikirimkan apa adanya kepada pelanggan tanpa pengkodean atau transformasi tambahan. Ini dapat berguna ketika pelanggan memerlukan format pesan asli untuk diproses. Namun, pengiriman pesan mentah tidak terkait langsung dengan fungsionalitas filter berlangganan.

Menerapkan Filter Berlangganan

Untuk menerapkan filter pesan ke langganan, Anda menentukan kebijakan filter menggunakan JSON sintaks. Kebijakan ini menetapkan kondisi yang harus dipenuhi pesan untuk dikirimkan ke langganan. Filter dapat didasarkan pada atribut pesan, seperti atribut pesan, struktur pesan, atau bahkan konten pesan.

Hubungan antara Pengiriman Pesan Mentah dan Filter Berlangganan

Meskipun mengaktifkan pengiriman pesan mentah dapat memengaruhi cara pesan dikirim dan diproses oleh pelanggan, ini bukan prasyarat untuk menggunakan filter berlangganan. Namun, dalam skenario di mana pelanggan memerlukan format pesan asli tanpa modifikasi apa pun, mengaktifkan pengiriman pesan mentah mungkin bermanfaat bersama filter berlangganan.

Pertimbangan untuk Penyaringan Efektif

Saat menerapkan pemfilteran pesan, pertimbangkan persyaratan spesifik aplikasi dan pelanggan Anda. Tentukan kebijakan filter yang secara akurat sesuai dengan kriteria pengiriman pesan untuk memastikan distribusi pesan yang efisien dan ditargetkan.

penting

AWS Layanan seperti IAM dan Amazon SNS menggunakan model komputasi terdistribusi yang disebut konsistensi akhirnya. Penambahan atau perubahan kebijakan filter langganan memerlukan hingga 15 menit untuk diterapkan sepenuhnya.

AWS Management Console

1. Masuk ke SNSkonsol Amazon.

2. Di panel navigasi, pilih Berlangganan.

3. Pilih langganan dan kemudian pilih Edit.

4. Pada halaman Edit, perluas bagian Kebijakan filter Langganan.

5. Pilih antara pemfilteran berbasis atribut atau pemfilteran berbasis muatan.

6. Di bidang JSONeditor, berikan JSONisi kebijakan filter Anda.

7. Pilih Simpan perubahan.

   Amazon SNS menerapkan kebijakan filter Anda ke langganan.

AWS CLI

Untuk menerapkan kebijakan filter dengan AWS Command Line Interface (AWS CLI), gunakan set-subscription-attributesperintah, seperti yang ditunjukkan pada contoh berikut. Untuk opsi --attribute-name, tentukan FilterPolicy. Untuk--attribute-value, tentukan JSONkebijakan Anda.

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

Untuk memberikan valid JSON bagi kebijakan Anda, lampirkan nama dan nilai atribut dalam tanda kutip ganda. Anda juga harus menyertakan seluruh argumen kebijakan dalam tanda kutip. Untuk menghindari tanda kutip lolos, Anda dapat menggunakan tanda kutip tunggal untuk melampirkan kebijakan dan tanda kutip ganda untuk melampirkan JSON nama dan nilai, seperti yang ditunjukkan pada contoh di atas.

Jika Anda ingin beralih dari pemfilteran pesan berbasis atribut (default) ke pemfilteran pesan berbasis muatan, Anda juga dapat menggunakan perintah tersebut. set-subscription-attributes Untuk opsi --attribute-name, tentukan FilterPolicyScope. Untuk --attribute-value, tentukan MessageBody.

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

Untuk memverifikasi bahwa kebijakan filter diterapkan, gunakan perintah get-subscription-attributes. Atribut dalam output terminal harus menunjukkan kebijakan filter Anda untuk kunci FilterPolicy, seperti yang ditunjukkan dalam contoh berikut:

$ 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

Contoh kode berikut menunjukkan cara menggunakanSetSubscriptionAttributes.

penting

Jika Anda menggunakan contoh SDK untuk Java 2.x, kelas tidak SNSMessageFilterPolicy tersedia di luar kotak. Untuk petunjuk tentang cara menginstal kelas ini, lihat contoh dari situs GitHub web.

CLI

AWS CLI

Untuk mengatur atribut langganan

set-subscription-attributesContoh berikut menetapkan RawMessageDelivery atribut ke SQS langganan.

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

Perintah ini tidak menghasilkan output.

set-subscription-attributesContoh berikut menetapkan FilterPolicy atribut ke SQS langganan.

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

Perintah ini tidak menghasilkan output.

set-subscription-attributesContoh berikut menghapus FilterPolicy atribut dari SQS langganan.

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

Perintah ini tidak menghasilkan output.

• Untuk API detailnya, lihat SetSubscriptionAttributesdi Referensi AWS CLI Perintah.

Java

SDKuntuk Java 2.x

catatan

Ada lebih banyak tentang GitHub. Temukan contoh lengkapnya dan pelajari cara pengaturan dan menjalankannya di Repositori Contoh Kode 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);
        }
    }
}

• Untuk API detailnya, lihat SetSubscriptionAttributesdi AWS SDK for Java 2.x APIReferensi.

Python

SDKuntuk Python (Boto3)

catatan

Ada lebih banyak tentang GitHub. Temukan contoh lengkapnya dan pelajari cara pengaturan dan menjalankannya di Repositori Contoh Kode 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

• Untuk API detailnya, lihat SetSubscriptionAttributes AWSSDKReferensi Python (Boto3). API

Amazon SNS API

Untuk menerapkan kebijakan filter dengan Amazon SNSAPI, buat permintaan untuk SetSubscriptionAttributestindakan tersebut. Setel AttributeName parameter keFilterPolicy, dan setel AttributeValue parameter ke kebijakan filter AndaJSON.

Jika Anda ingin beralih dari pemfilteran pesan berbasis atribut (default) ke pemfilteran pesan berbasis muatan, Anda juga dapat menggunakan tindakan tersebut. SetSubscriptionAttributes Atur AttributeName parameter keFilterPolicyScope, dan atur AttributeValue parameternya keMessageBody.

AWS CloudFormation

Untuk menerapkan kebijakan filter menggunakan AWS CloudFormation, gunakan YAML templat JSON atau untuk membuat AWS CloudFormation tumpukan. Untuk informasi selengkapnya, lihat FilterPolicyproperti AWS::SNS::Subscription sumber daya di Panduan AWS CloudFormation Pengguna dan AWS CloudFormation templat contoh.

1. Masuk ke konsol AWS CloudFormation tersebut.

2. Pilih Buat Tumpukan.

3. Pada halaman Pilihan Templat, pilih Unggah templat ke Amazon S3, pilih templat file, dan pilih Selanjutnya.

4. Di halaman Tentukan Detail, lakukan hal berikut:

   1. Untuk Nama Tumpukan, ketik MyFilterPolicyStack.

   2. Untuk myHttpEndpoint, ketik HTTP titik akhir untuk berlangganan topik Anda.

      Tip

      Jika Anda tidak memiliki HTTP titik akhir, buat satu.

5. Pada halaman Opsi, pilih Selanjutnya.

6. Di halaman Tinjau, pilih Buat.