community.aws.sns_topic 模块 – 管理 AWS SNS 主题和订阅

注意

此模块是 community.aws 集合 (版本 9.0.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.aws。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在剧本中使用它，请指定：community.aws.sns_topic。

community.aws 1.0.0 中的新增功能

概要

• community.aws.sns_topic 模块允许您创建、删除和管理 AWS SNS 主题的订阅。

要求

执行此模块的主机需要以下要求。

• python >= 3.6

• boto3 >= 1.28.0

• botocore >= 1.31.0

参数

参数	注释
access_key 别名：aws_access_key_id, aws_access_key, ec2_access_key 字符串	AWS 访问密钥 ID。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 还可以按优先级递减顺序使用 AWS_ACCESS_KEY_ID、AWS_ACCESS_KEY 或 EC2_ACCESS_KEY 环境变量。 aws_access_key 和 profile 选项是互斥的。 为了与 AWS botocore SDK 保持一致，在 5.1.0 版本中添加了 aws_access_key_id 别名。 ec2_access_key 别名已弃用，并将在 2024-12-01 之后的一个版本中移除。 EC2_ACCESS_KEY 环境变量的支持已弃用，并将在 2024-12-01 之后的一个版本中移除。
aws_ca_bundle 路径	验证 SSL 证书时要使用的 CA 证书包的位置。 还可以使用 AWS_CA_BUNDLE 环境变量。
aws_config 字典	用于修改 botocore 配置的字典。 参数可在 AWS 文档中找到 https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config。
content_based_deduplication 字符串 community.aws 5.3.0 中新增	是否为此主题启用基于内容的重复数据删除。 除非 topic_type=fifo，否则将忽略。 默认为 disabled。 选项 "disabled" "enabled"
debug_botocore_endpoint_logs 布尔值	使用 botocore.endpoint 日志记录器来解析在任务期间进行的唯一（而不是总计）"resource:action" API 调用，并将集合输出到任务结果中的 resource_actions 密钥。使用 aws_resource_action 回调将输出到剧本期间进行的总列表。 还可以使用 ANSIBLE_DEBUG_BOTOCORE_LOGS 环境变量。 选项 false ← (默认) true
delivery_policy 字典	应用于 SNS 主题的传递策略。
http 字典	HTTP(S) 消息的传递策略。 有关更多信息，请参阅 https://docs.aws.amazon.com/sns/latest/dg/sns-message-delivery-retries.html。
defaultHealthyRetryPolicy 字典 / 必需	HTTP(S) 消息的重试策略。
backoffFunction 字符串 / 必需	重试之间回退的函数。 选项 "arithmetic" "exponential" "geometric" "linear"
maxDelayTarget 整数 / 必需	重试的最大延迟。
minDelayTarget 整数 / 必需	重试的最小延迟。
numMaxDelayRetries 整数 / 必需	使用最大延迟之间重试的次数。
numMinDelayRetries 整数 / 必需	仅使用最小延迟之间的重试次数。
numNoDelayRetries 整数 / 必需	立即执行的重试次数。
numRetries 整数 / 必需	重试的总次数。
defaultThrottlePolicy 字典	限制发送到订阅的消息速率。
maxReceivesPerSecond 整数 / 必需	每个订阅每秒的最大投递数。
disableSubscriptionOverrides 布尔值	即使订阅有自己的策略，也应用此策略于所有订阅。 选项 false true
display_name 字符串	主题的显示名称。
endpoint_url 别名：ec2_url, aws_endpoint_url, s3_url 字符串	连接到非默认AWS端点的URL。虽然这可以用于连接到其他与AWS兼容的服务，但amazon.aws和community.aws集合只针对AWS进行了测试。 也可以使用AWS_URL或EC2_URL环境变量，优先级依次递减。 ec2_url和s3_url别名已弃用，将在2024-12-01之后的一个版本中删除。 EC2_URL环境变量的支持已弃用，将在2024-12-01之后的一个版本中删除。
name 字符串 / 必需	要管理的SNS主题的名称或ARN。
policy 字典	应用于SNS主题的策略。 策略主体可以是YAML或JSON。 某些用例需要此项，例如使用S3存储桶通知。
profile 别名：aws_profile 字符串	用于身份验证的命名AWS配置文件。 有关命名配置文件的更多信息，请参阅AWS文档 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html。 也可以使用AWS_PROFILE环境变量。 profile选项与aws_access_key、aws_secret_key和security_token选项互斥。
purge_subscriptions 布尔值	是否清除此处未列出的任何订阅。注意：AWS不允许您清除任何“待确认”订阅，因此如果存在任何将被清除的订阅，则会静默跳过它们。这意味着有人稍后可以回来确认订阅。抱歉。请责备亚马逊。 选项 false true ← (默认)
purge_tags 布尔值	如果purge_tags=true且tags已设置，则将从资源中清除现有标签，以完全匹配tags参数定义的内容。 如果没有设置tags参数，则即使purge_tags=True，也不会修改标签。 以aws:开头的标签键由Amazon保留，不能修改。因此，在purge_tags参数中将忽略它们。有关更多信息，请参阅Amazon文档 https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions。 选项 false true ← (默认)
region 别名：aws_region, ec2_region 字符串	要使用的AWS区域。 对于IAM、Route53和CloudFront等全局服务，将忽略region。 也可以使用AWS_REGION或EC2_REGION环境变量。 有关更多信息，请参阅Amazon AWS文档 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region。 ec2_region别名已弃用，将在2024-12-01之后的一个版本中删除。 EC2_REGION环境变量的支持已弃用，将在2024-12-01之后的一个版本中删除。
secret_key 别名：aws_secret_access_key, aws_secret_key, ec2_secret_key 字符串	AWS密钥访问密钥。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以使用AWS_SECRET_ACCESS_KEY、AWS_SECRET_KEY或EC2_SECRET_KEY环境变量，优先级依次递减。 secret_key和profile选项互斥。 为了与AWS botocore SDK保持一致，在5.1.0版本中添加了aws_secret_access_key别名。 ec2_secret_key别名已弃用，将在2024-12-01之后的一个版本中删除。 EC2_SECRET_KEY环境变量的支持已弃用，将在2024-12-01之后的一个版本中删除。
session_token 别名：aws_session_token, security_token, aws_security_token, access_token 字符串	与临时凭据一起使用的AWS STS会话令牌。 有关访问令牌的更多信息，请参阅 AWS 文档 https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys。 也可以使用AWS_SESSION_TOKEN、AWS_SECURITY_TOKEN或EC2_SECURITY_TOKEN环境变量，优先级依次递减。 security_token和profile选项互斥。 在3.2.0版本中添加了aws_session_token和session_token别名，在6.0.0版本中将参数名称从security_token重命名为session_token。 security_token、aws_security_token和access_token别名已弃用，将在2024-12-01之后的一个版本中删除。 EC2_SECRET_KEY和AWS_SECURITY_TOKEN环境变量的支持已弃用，将在2024-12-01之后的一个版本中删除。
state 字符串	创建或销毁SNS主题。 选项 "absent" "present" ← (默认)
subscriptions 列表 / 元素=字典	应用于主题的订阅列表。请注意，AWS要求确认订阅，因此您需要确认任何新的订阅。 默认： []
attributes 字符串 在community.aws 4.1.0中添加	订阅的属性。仅支持用于SQS端点的RawMessageDelievery。 默认： {}
endpoint 字符串 / 必需	订阅的端点。
protocol 字符串 / 必需	订阅的协议。
tags 别名：resource_tags 字典	表示要应用于资源的标签的字典。 如果没有设置tags参数，则不会修改标签。
topic_type 字符串 在community.aws 2.0.0中添加	应创建的主题类型。对于FIFO（先进先出）而言是Standard。 某些区域（包括GovCloud区域）不支持FIFO主题。如果区域不支持FIFO主题，请使用默认值“standard”或省略此选项。 选项 "standard" ← (默认) "fifo"
validate_certs 布尔值	设置为false时，将不会验证与AWS API通信的SSL证书。 强烈建议不要设置validate_certs=false，作为替代方案，可以考虑设置aws_ca_bundle。 选项 false true ← (默认)

注释

注意

• 在5.3.0版本中添加了对tags和purge_tags的支持。

• 警告：对于模块，环境变量和配置文件是从Ansible“主机”上下文读取的，而不是从“控制器”上下文读取的。因此，可能需要将文件显式复制到“主机”。对于查找和连接插件，环境变量和配置文件是从Ansible“控制器”上下文读取的，而不是从“主机”上下文读取的。

• Ansible使用的AWS SDK (boto3)也可能从其在Ansible“主机”上下文中的配置文件（通常为~/.aws/credentials）读取凭据和其他设置（如区域）的默认值。有关更多信息，请参阅 https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html。

示例

- name: Create alarm SNS topic
  community.aws.sns_topic:
    name: "alarms"
    state: present
    display_name: "alarm SNS topic"
    delivery_policy:
      http:
        defaultHealthyRetryPolicy:
          minDelayTarget: 2
          maxDelayTarget: 4
          numRetries: 9
          numMaxDelayRetries: 5
          numMinDelayRetries: 2
          numNoDelayRetries: 2
          backoffFunction: "linear"
        disableSubscriptionOverrides: true
        defaultThrottlePolicy:
          maxReceivesPerSecond: 10
    subscriptions:
      - endpoint: "[email protected]"
        protocol: "email"
      - endpoint: "my_mobile_number"
        protocol: "sms"

- name: Create a topic permitting S3 bucket notifications
  community.aws.sns_topic:
    name: "S3Notifications"
    state: present
    display_name: "S3 notifications SNS topic"
    policy:
      Id: s3-topic-policy
      Version: 2012-10-17
      Statement:
        - Sid: Statement-id
          Effect: Allow
          Resource: "arn:aws:sns:*:*:S3Notifications"
          Principal:
            Service: s3.amazonaws.com
          Action: sns:Publish
          Condition:
            ArnLike:
              aws:SourceArn: "arn:aws:s3:*:*:SomeBucket"

- name: Example deleting a topic
  community.aws.sns_topic:
    name: "ExampleTopic"
    state: absent

返回值

此处记录了常见的返回值 此处，以下是此模块特有的字段

键	描述
sns_arn 字符串	您正在修改的主题的ARN 返回：始终 示例： "arn:aws:sns:us-east-2:123456789012:my_topic_name"
sns_topic 复杂	sns主题详细信息的字典 返回：始终
attributes_set 列表 / 元素=字符串	在此运行期间设置的属性列表 返回：始终 示例： []
check_mode 布尔值	检查模式是否开启 返回：始终 示例： false
content_based_deduplication 字符串 community.aws 5.3.0 中新增	是否设置了content_based_deduplication 返回：始终 示例： "disabled"
delivery_policy 字符串	SNS主题的投递策略 返回：当主题由此AWS帐户拥有时 示例： "{\"http\":{\"defaultHealthyRetryPolicy\":{\"minDelayTarget\":20,\"maxDelayTarget\":20,\"numRetries\":3,\"numMaxDelayRetries\":0, \"numNoDelayRetries\":0,\"numMinDelayRetries\":0,\"backoffFunction\":\"linear\"},\"disableSubscriptionOverrides\":false}}\n"
display_name 字符串	SNS主题显示名称 返回：当主题由此AWS帐户拥有时 示例： "我的 主题 名称"
name 字符串	主题名称 返回：始终 示例： "ansible-test-dummy-topic"
所有者 字符串	拥有该主题的AWS账户 返回：当主题由此AWS帐户拥有时 示例： "123456789012"
policy 字符串	SNS主题策略 返回：当主题由此AWS帐户拥有时 示例： "{\"Version\":\"2012-10-17\",\"Id\":\"SomePolicyId\",\"Statement\":[{\"Sid\":\"ANewSid\",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::123456789012:root\"}, \"Action\":\"sns:Subscribe\",\"Resource\":\"arn:aws:sns:us-east-2:123456789012:ansible-test-dummy-topic\",\"Condition\":{\"StringEquals\":{\"sns:Protocol\":\"email\"}}}]}\n"
state 字符串	主题是否存在 返回：始终 示例： "present"
subscriptions 列表 / 元素=字符串	此AWS账户中主题的订阅者列表 返回：始终 示例： []
subscriptions_added 列表 / 元素=字符串	本次运行中添加的订阅者列表 返回：始终 示例： []
subscriptions_confirmed 字符串	已确认订阅的数量 返回：当主题由此AWS帐户拥有时 示例： "0"
subscriptions_deleted 字符串	已删除订阅的数量 返回：当主题由此AWS帐户拥有时 示例： "0"
subscriptions_existing 列表 / 元素=字符串	现有订阅列表 返回：始终 示例： []
subscriptions_new 列表 / 元素=字符串	新的订阅列表 返回：始终 示例： []
subscriptions_pending 字符串	待处理订阅的数量 返回：当主题由此AWS帐户拥有时 示例： "0"
subscriptions_purge 布尔值	是否设置了purge_subscriptions 返回：始终 示例： true
topic_arn 字符串	SNS主题的ARN（等同于sns_arn） 返回：当主题由此AWS帐户拥有时 示例： "arn:aws:sns:us-east-2:123456789012:ansible-test-dummy-topic"
topic_created 布尔值	主题是否已创建 返回：始终 示例： false
topic_deleted 布尔值	主题是否已删除 返回：始终 示例： false

作者

• Joel Thompson (@joelthompson)

• Fernando Jose Pando (@nand0p)

• Will Thames (@willthames)

相关链接

• 问题追踪器
• 代码仓库
• 沟通