class AWS::SNS::Topic

Attributes

arn[R]

@return [String] The topic ARN.

Public Class Methods

new(arn, options = {}) click to toggle source

@param [String] arn The topic ARN.

Calls superclass method AWS::Core::Model::new
# File lib/aws/sns/topic.rb, line 25
def initialize arn, options = {}
  @arn = arn
  super
end

Public Instance Methods

==(other)
Alias for: eql?
confirm_subscription(token, options = {}) click to toggle source

Verifies an endpoint owner’s intent to receive messages by validating the token sent to the endpoint by an earlier Subscribe action. If the token is valid, the action creates a new subscription.

@param [String] token Short-lived token sent to an endpoint

during the {#subscribe} action.

@param [Hash] options Additional options for confirming the

subscription.

@option options [Boolean] :authenticate_on_unsubscribe

Indicates that you want to disable unauthenticated
unsubsciption of the subscription.

@return [Subscription] The newly created subscription.

# File lib/aws/sns/topic.rb, line 135
def confirm_subscription token, options = {}

  options[:authenticate_on_unsubscribe] = 'true' if
    options[:authenticate_on_unsubscribe]

  confirm_opts = options.merge(:token => token, :topic_arn => arn)
  resp = client.confirm_subscription(confirm_opts)
  Subscription.new(
    resp[:subscription_arn],
    :topic_arn => arn,
    :config => config)

end
delete() click to toggle source

Deletes the topic. @return [nil]

# File lib/aws/sns/topic.rb, line 285
def delete
  client.delete_topic(:topic_arn => arn)
  nil
end
delivery_policy_json() click to toggle source

@return [nil,String<JSON>] The delivery policy JSON string.

# File lib/aws/sns/topic.rb, line 209
def delivery_policy_json
  to_h[:delivery_policy_json]
end
display_name() click to toggle source

@return [String] Returns the human-readable name used in

the "From" field for notifications to email and email-json
endpoints.  If you have not set the display name the topic
{#name} will be used/returned instead.
# File lib/aws/sns/topic.rb, line 159
def display_name
  to_h[:display_name]
end
display_name=(display_name) click to toggle source

@param [String] display_name Sets the human-readable name used in

the "From" field for notifications to email and email-json
endpoints.

@return [String] Returns the display_name as passed.

# File lib/aws/sns/topic.rb, line 167
def display_name= display_name
  set_attribute('DisplayName', display_name)
  display_name
end
effective_delivery_policy_json() click to toggle source

@return [String<JSON>] The effective delivery policy JSON string.

into account system defaults.
# File lib/aws/sns/topic.rb, line 215
def effective_delivery_policy_json
  to_h[:effective_delivery_policy_json]
end
eql?(other) click to toggle source

@return [Boolean] Returns true if compared to another {Topic}

with the same ARN.
# File lib/aws/sns/topic.rb, line 320
def eql? other
  other.kind_of?(Topic) and other.arn == arn
end
Also aliased as: ==
name() click to toggle source

The topic name.

If you have not set a display name (see {#display_name=}) then this is used as the “From” field for notifications to email and email-json endpoints. @return [String] Returns the topic name.

# File lib/aws/sns/topic.rb, line 39
def name
  arn.split(/:/)[-1]
end
num_subscriptions_confirmed() click to toggle source

@return [Integer] Returns number of confirmed topic subscriptions.

# File lib/aws/sns/topic.rb, line 178
def num_subscriptions_confirmed
  to_h[:num_subscriptions_confirmed]
end
num_subscriptions_deleted() click to toggle source

@return [Integer] Returns number of deleted topic subscriptions.

# File lib/aws/sns/topic.rb, line 188
def num_subscriptions_deleted
  to_h[:num_subscriptions_deleted]
end
num_subscriptions_pending() click to toggle source

@return [Integer] Returns number of pending topic subscriptions.

# File lib/aws/sns/topic.rb, line 183
def num_subscriptions_pending
  to_h[:num_subscriptions_pending]
end
owner() click to toggle source

@return [String] The topic owner’s ID.

# File lib/aws/sns/topic.rb, line 173
def owner
  to_h[:owner]
end
policy() click to toggle source

@return [Policy] The topic’s {Policy}.

# File lib/aws/sns/topic.rb, line 193
def policy
  to_h[:policy]
end
policy=(policy) click to toggle source

Sets the topic’s policy. @param [String,Policy] policy A JSON policy string, a {Policy} object

or any other object that responds to #to_json with a valid
policy.

@return [nil]

# File lib/aws/sns/topic.rb, line 202
def policy= policy
  policy_json = policy.is_a?(String) ? policy : policy.to_json
  set_attribute('Policy', policy_json)
  nil
end
publish(default_message, options = {}) click to toggle source

Publishes a message to this SNS topic.

topic.publish('a short message')

You can pass a subject that is used when sending the message to email endpoints:

topic.publish('message', :subject => 'SNS message subject')

If you would like to pass a different message to various protocols (endpoint types) you can pass those as options:

topic.publish('default message',
  :http => "message sent to http endpoints",
  :https => "message sent to https endpoints",
  :email => "message sent to email endpoints")

The full list of acceptable protocols are listed below. The default message is sent to endpoints who’s protocol was not listed.

@param [String] default_message The message you want to send to the

topic.  Messages must be UTF-8 encoded strings at most 8 KB in size
(8192 bytes, not 8192 characters).

@param [Hash] options @option options [String] :subject Used as the “Subject” line when

the message is delivered to email endpoints. Will also  be
included in the standard JSON messages delivered to other endpoints.
* must be ASCII text that begins with a letter, number or
  punctuation mark
* must not include line breaks or control characters
* and must be less than 100 characters long

@option options [String] :http - Message to use when sending to an

HTTP endpoint.

@option options [String] :https - Message to use when sending to an

HTTPS endpoint.

@option options [String] :email - Message to use when sending to an

email endpoint.

@option options [String] :email_json - Message to use when sending

to an email json endpoint.

@option options [String] :sqs - Message to use when sending to an

SQS endpoint.

@return [String] Returns the ID of the message that was sent.

# File lib/aws/sns/topic.rb, line 261
def publish default_message, options = {}

  message = { :default => default_message }

  [:http, :https, :email, :email_json, :sqs].each do |protocol|
    if options[protocol]
      message[protocol.to_s.gsub(/_/, '-')] = options[protocol]
    end
  end

  publish_opts = {}
  publish_opts[:message] = message.to_json
  publish_opts[:message_structure] = 'json'
  publish_opts[:subject] = options[:subject] if options[:subject]
  publish_opts[:topic_arn] = arn

  response = client.publish(publish_opts)

  response[:message_id]

end
subscribe(endpoint, options = {}) click to toggle source

Causes the given ‘endpoint` to receive messages published to this topic.

## Subscribing to SQS Queues

If you subscribe to an SQS queue (with a {SQS::Queue} object} then a policy will be added/updated to the queue that will permit this topic to send it messages. Some important notes:

  • If you subscribe with a queue by ARN then you must change the policy yourself.

  • If you do not want the policy modified then pass ‘:update_policy` as false or just pass the queue’s arn

    topic.subscribe(queue.arn)
    topic.subscribe(queue, :update_policy => false)
    

@example Using a url string to set the endpoint (http and https)

topic.subscribe('http://example.com/messages')
topic.subscribe('https://example.com/messages')

@example Using a uri object to set the endpoint (http and https)

topic.subscribe(URI.parse('http://example.com/messages'))
topic.subscribe(URI.parse('https://example.com/messages'))

@example Email address as endpoint

topic.subscribe('nobody@example.com')

@example Email address as a JSON endpoint

# send messages encoded as json object to the given email address
topic.subscribe('nobody@example.com', :json => true)

@example SQS Queue (by arn)

# you must manage the queue policy yourself to allow the
# the topic to send messages (policy action 'sqs:SendMessage')
topic.subscribe('arn:aws:sqs:us-west-2:123456789123:AQueue')

@example SQS Queue (by Queue object)

# the queue policy will be added/updated to allow the topic
# to send it messages
topic.subscribe(AWS::SQS.new.queues.first)

@param [mixed] endpoint The endpoint that should receive

messages that are published to this topic.  Valid values
for `endpoint` include:

* URI object
* http and https URI strings
* email address
* {SQS::Queue}
* SQS queue ARN
* phone number of an SMS-enabled device

@param [Hash] options @option options [Boolean] :json (false) @return [Subscription,nil] Returns a subscription when possible.

If the subscription requires confirmation first, then `nil` is
returned instead.
# File lib/aws/sns/topic.rb, line 108
def subscribe endpoint, options = {}
  subscribe_opts = endpoint_opts(endpoint, options).merge(:topic_arn => arn)
  resp = client.subscribe(subscribe_opts)
  if arn = resp[:subscription_arn] and arn =~ /^arn:/
    Subscription.new(arn, :config => config)
  else
    nil
  end
end
subscriptions() click to toggle source

@return [TopicSubscriptionCollection] Returns a collection that

represents all of the subscriptions for this topic.
# File lib/aws/sns/topic.rb, line 151
def subscriptions
  TopicSubscriptionCollection.new(self)
end
to_h() click to toggle source

@return [Hash] Returns a hash of attributes about this topic,

including:

* `:arn`
* `:name`
* `:owner`
* `:display_name`
* `:policy`
* `:num_subscriptions_confirmed`
* `:num_subscriptions_pending`
* `:num_subscriptions_deleted`
# File lib/aws/sns/topic.rb, line 302
def to_h
  attributes = client.get_topic_attributes(:topic_arn => arn).attributes
  {
    :arn => arn,
    :name => name,
    :owner => attributes['Owner'],
    :display_name => attributes['DisplayName'] || name,
    :policy => parse_policy(attributes['Policy']),
    :num_subscriptions_confirmed => attributes['SubscriptionsConfirmed'].to_i,
    :num_subscriptions_pending => attributes['SubscriptionsPending'].to_i,
    :num_subscriptions_deleted => attributes['SubscriptionsDeleted'].to_i,
    :delivery_policy_json => attributes['DeliveryPolicy'],
    :effective_delivery_policy_json => attributes['EffectiveDeliveryPolicy'],
  }
end

Protected Instance Methods

endpoint_opts(endpoint, opts = {}) click to toggle source

@api private

# File lib/aws/sns/topic.rb, line 363
def endpoint_opts(endpoint, opts = {})

  case
  when endpoint.is_a?(SQS::Queue)

    # auto add a policy to the queue to allow the topic
    # to send the queue messages
    unless opts[:update_policy] == false
      policy = endpoint.policy || SQS::Policy.new
      policy.allow(
        :principal => :any,
        :actions => [:send_message],
        :resources => [endpoint]
      ).where(:source_arn).is(arn)
      endpoint.policy = policy
    end

    { :protocol => 'sqs', :endpoint => endpoint.arn }

  when endpoint =~ /^arn:/
    raise ArgumentError, "expected a queue ARN" unless
      endpoint =~ /^arn:aws(.*?):sqs:/
    { :protocol => "sqs", :endpoint => endpoint }
  when endpoint.kind_of?(URI)
    { :protocol => endpoint.scheme,
      :endpoint => endpoint.to_s }
  when endpoint =~ /^(https?):/
    { :protocol => $1, :endpoint => endpoint }
  when endpoint.include?("@")
    { :protocol => opts[:json] ? "email-json" : "email",
      :endpoint => endpoint }
  when endpoint.gsub(/\D/,'') =~ /\d{11,15}/
    { :protocol => "sms", :endpoint => endpoint.gsub(/\D/,'') }
  else
    raise ArgumentError, "could not determine protocol for '#{endpoint}'"
  end
end
parse_policy(policy_json) click to toggle source
# File lib/aws/sns/topic.rb, line 331
def parse_policy policy_json
  if policy_json
    policy = SNS::Policy.from_json(policy_json)
    policy.extend(PolicyProxy)
    policy.topic = self
    policy
  else
    nil
  end
end
set_attribute(name, value) click to toggle source

@api private

# File lib/aws/sns/topic.rb, line 344
def set_attribute name, value
  client.send(:set_topic_attributes, {
    :topic_arn => arn,
    :attribute_name => name,
    :attribute_value => value,
  })
end
update_delivery_policy(policy_json) click to toggle source
# File lib/aws/sns/topic.rb, line 326
def update_delivery_policy policy_json
  set_attribute('DeliveryPolicy', policy_json)
end