
SNS
***


boto.sns
========

boto.sns.connect_to_region(region_name, **kw_params)

   Given a valid region name, return a
   "boto.sns.connection.SNSConnection".

   Type :
      str

   Parameters:
      **region_name** -- The name of the region to connect to.

   Return type:
      "boto.sns.connection.SNSConnection" or "None"

   Returns:
      A connection to the given region, or None if an invalid region
      name is given

boto.sns.regions()

   Get all available regions for the SNS service.

   Return type:
      list

   Returns:
      A list of "boto.regioninfo.RegionInfo" instances

class class boto.sns.SNSConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, debug=0, https_connection_factory=None, region=None, path='/', security_token=None, validate_certs=True, profile_name=None)

   Amazon Simple Notification Service Amazon Simple Notification
   Service (Amazon SNS) is a web service that enables you to build
   distributed web-enabled applications. Applications can use Amazon
   SNS to easily push real-time notification messages to interested
   subscribers over multiple delivery protocols. For more information
   about this product see >>`http://aws.amazon.com/sns`_<<. For
   detailed information about Amazon SNS features and their associated
   API calls, see the >>`Amazon SNS Developer Guide`_<<.

   We also provide SDKs that enable you to access Amazon SNS from your
   preferred programming language. The SDKs contain functionality that
   automatically takes care of tasks such as: cryptographically
   signing your service requests, retrying requests, and handling
   error responses. For a list of available SDKs, go to >>`Tools for
   Amazon Web Services`_<<.

   APIVersion = '2010-03-31'

   DefaultRegionEndpoint = 'sns.us-east-1.amazonaws.com'

   DefaultRegionName = 'us-east-1'

   add_permission(topic, label, account_ids, actions)

      Adds a statement to a topic's access control policy, granting
      access for the specified AWS accounts to the specified actions.

      Parameters:
         * **topic** (*string*) -- The ARN of the topic.

         * **label** (*string*) -- A unique identifier for the new
           policy statement.

         * **account_ids** (*list of strings*) -- The AWS account ids
           of the users who will be give access to the specified
           actions.

         * **actions** (*list of strings*) -- The actions you want to
           allow for each of the specified principal(s).

   confirm_subscription(topic, token, authenticate_on_unsubscribe=False)

      Get properties of a Topic

      Parameters:
         * **topic** (*string*) -- The ARN of the new topic.

         * **token** (*string*) -- Short-lived token sent to and
           endpoint during the Subscribe operation.

         * **authenticate_on_unsubscribe** (*bool*) -- Optional
           parameter indicating that you wish to disable
           unauthenticated unsubscription of the subscription.

   create_platform_application(name=None, platform=None, attributes=None)

      The *CreatePlatformApplication* action creates a platform
      application object for one of the supported push notification
      services, such as APNS and GCM, to which devices and mobile apps
      may register. You must specify PlatformPrincipal and
      PlatformCredential attributes when using the
      *CreatePlatformApplication* action. The PlatformPrincipal is
      received from the notification service. For APNS/APNS_SANDBOX,
      PlatformPrincipal is "SSL certificate". For GCM,
      PlatformPrincipal is not applicable. For ADM, PlatformPrincipal
      is "client id". The PlatformCredential is also received from the
      notification service. For APNS/APNS_SANDBOX, PlatformCredential
      is "private key". For GCM, PlatformCredential is "API key". For
      ADM, PlatformCredential is "client secret". The
      PlatformApplicationArn that is returned when using
      *CreatePlatformApplication* is then used as an attribute for the
      *CreatePlatformEndpoint* action. For more information, see
      >>`Using Amazon SNS Mobile Push Notifications`_<<.

      Parameters:
         * **name** (*string*) -- Application names must be made up of
           only uppercase and lowercase ASCII letters, numbers,
           underscores, hyphens, and periods, and must be between 1
           and 256 characters long.

         * **platform** (*string*) -- The following platforms are
           supported: ADM (Amazon Device Messaging), APNS (Apple Push
           Notification Service), APNS_SANDBOX, and GCM (Google Cloud
           Messaging).

         * **attributes** (*map*) -- For a list of attributes, see
           >>`SetPlatformApplicationAttributes`_<<

   create_platform_endpoint(platform_application_arn=None, token=None, custom_user_data=None, attributes=None)

      The *CreatePlatformEndpoint* creates an endpoint for a device
      and mobile app on one of the supported push notification
      services, such as GCM and APNS. *CreatePlatformEndpoint*
      requires the PlatformApplicationArn that is returned from
      *CreatePlatformApplication*. The EndpointArn that is returned
      when using *CreatePlatformEndpoint* can then be used by the
      *Publish* action to send a message to a mobile app or by the
      *Subscribe* action for subscription to a topic. For more
      information, see >>`Using Amazon SNS Mobile Push
      Notifications`_<<.

      Parameters:
         * **platform_application_arn** (*string*) --
           PlatformApplicationArn returned from
           CreatePlatformApplication is used to create a an endpoint.

         * **token** (*string*) -- Unique identifier created by the
           notification service for an app on a device. The specific
           name for Token will vary, depending on which notification
           service is being used. For example, when using APNS as the
           notification service, you need the device token.
           Alternatively, when using GCM or ADM, the device token
           equivalent is called the registration ID.

         * **custom_user_data** (*string*) -- Arbitrary user data to
           associate with the endpoint. SNS does not use this data.
           The data must be in UTF-8 format and less than 2KB.

         * **attributes** (*map*) -- For a list of attributes, see
           >>`SetEndpointAttributes`_<<.

   create_topic(topic)

      Create a new Topic.

      Parameters:
         **topic** (*string*) -- The name of the new topic.

   delete_endpoint(endpoint_arn=None)

      The *DeleteEndpoint* action, which is idempotent, deletes the
      endpoint from SNS. For more information, see >>`Using Amazon SNS
      Mobile Push Notifications`_<<.

      Parameters:
         **endpoint_arn** (*string*) -- EndpointArn of endpoint to
         delete.

   delete_platform_application(platform_application_arn=None)

      The *DeletePlatformApplication* action deletes a platform
      application object for one of the supported push notification
      services, such as APNS and GCM. For more information, see
      >>`Using Amazon SNS Mobile Push Notifications`_<<.

      Parameters:
         **platform_application_arn** (*string*) --
         PlatformApplicationArn of platform application object to
         delete.

   delete_topic(topic)

      Delete an existing topic

      Parameters:
         **topic** (*string*) -- The ARN of the topic

   get_all_subscriptions(next_token=None)

      Get list of all subscriptions.

      Parameters:
         **next_token** (*string*) -- Token returned by the previous
         call to this method.

   get_all_subscriptions_by_topic(topic, next_token=None)

      Get list of all subscriptions to a specific topic.

      Parameters:
         * **topic** (*string*) -- The ARN of the topic for which you
           wish to find subscriptions.

         * **next_token** (*string*) -- Token returned by the previous
           call to this method.

   get_all_topics(next_token=None)

      Parameters:
         **next_token** (*string*) -- Token returned by the previous
         call to this method.

   get_endpoint_attributes(endpoint_arn=None)

      The *GetEndpointAttributes* retrieves the endpoint attributes
      for a device on one of the supported push notification services,
      such as GCM and APNS. For more information, see >>`Using Amazon
      SNS Mobile Push Notifications`_<<.

      Parameters:
         **endpoint_arn** (*string*) -- EndpointArn for
         GetEndpointAttributes input.

   get_platform_application_attributes(platform_application_arn=None)

      The *GetPlatformApplicationAttributes* action retrieves the
      attributes of the platform application object for the supported
      push notification services, such as APNS and GCM. For more
      information, see >>`Using Amazon SNS Mobile Push
      Notifications`_<<.

      Parameters:
         **platform_application_arn** (*string*) --
         PlatformApplicationArn for
         GetPlatformApplicationAttributesInput.

   get_topic_attributes(topic)

      Get attributes of a Topic

      Parameters:
         **topic** (*string*) -- The ARN of the topic.

   list_endpoints_by_platform_application(platform_application_arn=None, next_token=None)

      The *ListEndpointsByPlatformApplication* action lists the
      endpoints and endpoint attributes for devices in a supported
      push notification service, such as GCM and APNS. The results for
      *ListEndpointsByPlatformApplication* are paginated and return a
      limited list of endpoints, up to 100. If additional records are
      available after the first page results, then a NextToken string
      will be returned. To receive the next page, you call
      *ListEndpointsByPlatformApplication* again using the NextToken
      string received from the previous call. When there are no more
      records to return, NextToken will be null. For more information,
      see >>`Using Amazon SNS Mobile Push Notifications`_<<.

      Parameters:
         * **platform_application_arn** (*string*) --
           PlatformApplicationArn for
           ListEndpointsByPlatformApplicationInput action.

         * **next_token** (*string*) -- NextToken string is used when
           calling ListEndpointsByPlatformApplication action to
           retrieve additional records that are available after the
           first page results.

   list_platform_applications(next_token=None)

      The *ListPlatformApplications* action lists the platform
      application objects for the supported push notification
      services, such as APNS and GCM. The results for
      *ListPlatformApplications* are paginated and return a limited
      list of applications, up to 100. If additional records are
      available after the first page results, then a NextToken string
      will be returned. To receive the next page, you call
      *ListPlatformApplications* using the NextToken string received
      from the previous call. When there are no more records to
      return, NextToken will be null. For more information, see
      >>`Using Amazon SNS Mobile Push Notifications`_<<.

      Parameters:
         **next_token** (*string*) -- NextToken string is used when
         calling ListPlatformApplications action to retrieve
         additional records that are available after the first page
         results.

   publish(topic=None, message=None, subject=None, target_arn=None, message_structure=None)

      Get properties of a Topic

      Parameters:
         * **topic** (*string*) -- The ARN of the new topic.

         * **message** (*string*) -- The message you want to send to
           the topic. Messages must be UTF-8 encoded strings and be at
           most 4KB in size.

         * **message_structure** (*string*) -- Optional parameter. If
           left as "None", plain text will be sent. If set to "json",
           your message should be a JSON string that matches the
           structure described at
           http://docs.aws.amazon.com/sns/latest/dg/PublishTopic.html
           #sns-message-formatting-by-protocol

         * **subject** (*string*) -- Optional parameter to be used as
           the "Subject" line of the email notifications.

         * **target_arn** (*string*) -- Optional parameter for either
           TopicArn or EndpointArn, but not both.

   remove_permission(topic, label)

      Removes a statement from a topic's access control policy.

      Parameters:
         * **topic** (*string*) -- The ARN of the topic.

         * **label** (*string*) -- A unique identifier for the policy
           statement to be removed.

   set_endpoint_attributes(endpoint_arn=None, attributes=None)

      The *SetEndpointAttributes* action sets the attributes for an
      endpoint for a device on one of the supported push notification
      services, such as GCM and APNS. For more information, see
      >>`Using Amazon SNS Mobile Push Notifications`_<<.

      Parameters:
         * **endpoint_arn** (*string*) -- EndpointArn used for
           SetEndpointAttributes action.

         * **attributes** (*map*) --

      A map of the endpoint attributes. Attributes in this map include
      the
         following:

      * *CustomUserData* -- arbitrary user data to associate with the
           endpoint. SNS does not use this data. The data must be in
           UTF-8 format and less than 2KB.

      * *Enabled* -- flag that enables/disables delivery to the
        endpoint.
           Message Processor will set this to false when a
           notification service indicates to SNS that the endpoint is
           invalid. Users can set it back to true, typically after
           updating Token.

      * *Token* -- device token, also referred to as a registration
        id, for
           an app and mobile device. This is returned from the
           notification service when an app and mobile device are
           registered with the notification service.

   set_platform_application_attributes(platform_application_arn=None, attributes=None)

      The *SetPlatformApplicationAttributes* action sets the
      attributes of the platform application object for the supported
      push notification services, such as APNS and GCM. For more
      information, see >>`Using Amazon SNS Mobile Push
      Notifications`_<<.

      Parameters:
         * **platform_application_arn** (*string*) --
           PlatformApplicationArn for SetPlatformApplicationAttributes
           action.

         * **attributes** (*map*) --

      A map of the platform application attributes. Attributes in this
      map
         include the following:

      * *PlatformCredential* -- The credential received from the
        notification
           service. For APNS/APNS_SANDBOX, PlatformCredential is
           "private key". For GCM, PlatformCredential is "API key".
           For ADM, PlatformCredential is "client secret".

      * *PlatformPrincipal* -- The principal received from the
        notification
           service. For APNS/APNS_SANDBOX, PlatformPrincipal is "SSL
           certificate". For GCM, PlatformPrincipal is not applicable.
           For ADM, PlatformPrincipal is "client id".

      * *EventEndpointCreated* -- Topic ARN to which EndpointCreated
        event
           notifications should be sent.

      * *EventEndpointDeleted* -- Topic ARN to which EndpointDeleted
        event
           notifications should be sent.

      * *EventEndpointUpdated* -- Topic ARN to which EndpointUpdate
        event
           notifications should be sent.

      * *EventDeliveryFailure* -- Topic ARN to which DeliveryFailure
        event
           notifications should be sent upon Direct Publish delivery
           failure (permanent) to one of the application's endpoints.

   set_topic_attributes(topic, attr_name, attr_value)

      Get attributes of a Topic

      Parameters:
         * **topic** (*string*) -- The ARN of the topic.

         * **attr_name** (*string*) -- The name of the attribute you
           want to set. Only a subset of the topic's attributes are
           mutable. Valid values: Policy | DisplayName

         * **attr_value** (*string*) -- The new value for the
           attribute.

   subscribe(topic, protocol, endpoint)

      Subscribe to a Topic.

      Parameters:
         * **topic** (*string*) -- The ARN of the new topic.

         * **protocol** (*string*) -- The protocol used to communicate
           with the subscriber.  Current choices are: email|email-
           json|http|https|sqs|sms|application

         * **endpoint** (*string*) --

           The location of the endpoint for the subscriber. * For
           email, this would be a valid email address * For email-
           json, this would be a valid email address * For http, this
           would be a URL beginning with http * For https, this would
           be a URL beginning with https * For sqs, this would be the
           ARN of an SQS Queue * For sms, this would be a phone number
           of an

              SMS-enabled device

           * For application, the endpoint is the EndpointArn of a
             mobile app and device.

   subscribe_sqs_queue(topic, queue)

      Subscribe an SQS queue to a topic.

      This is convenience method that handles most of the complexity
      involved in using an SQS queue as an endpoint for an SNS topic.
      To achieve this the following operations are performed:

      * The correct ARN is constructed for the SQS queue and that ARN
        is then subscribed to the topic.

      * A JSON policy document is contructed that grants permission to
        the SNS topic to send messages to the SQS queue.

      * This JSON policy is then associated with the SQS queue using
        the queue's set_attribute method.  If the queue already has a
        policy associated with it, this process will add a Statement
        to that policy.  If no policy exists, a new policy will be
        created.

      Parameters:
         * **topic** (*string*) -- The ARN of the new topic.

         * **queue** (*A boto Queue object*) -- The queue you wish to
           subscribe to the SNS Topic.

   unsubscribe(subscription)

      Allows endpoint owner to delete subscription. Confirmation
      message will be delivered.

      Parameters:
         **subscription** (*string*) -- The ARN of the subscription to
         be deleted.
