Class: AWS::SNS::Topic

Inherits:
Object
  • Object
show all
Includes:
Core::Model, HasDeliveryPolicy
Defined in:
lib/aws/sns/topic.rb

Defined Under Namespace

Modules: PolicyProxy

Instance Attribute Summary collapse

Attributes included from Core::Model

#config

Instance Method Summary collapse

Methods included from HasDeliveryPolicy

#delivery_policy, #delivery_policy=, #effective_delivery_policy

Methods included from Core::Model

#client, #config_prefix, #inspect

Constructor Details

#initialize(arn, options = {}) ⇒ Topic 



25
26
27
28
 
# File 'lib/aws/sns/topic.rb', line 25

def initialize arn, options = {}
  @arn = arn
  super
end

Instance Attribute Details

#arn ⇒ String (readonly) 



31
32
33
 
# File 'lib/aws/sns/topic.rb', line 31

def arn
  @arn
end

Instance Method Details

#confirm_subscription(token, options = {}) ⇒ Subscription

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.



135
136
137
138
139
140
141
142
143
144
145
146
147
 
# 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 ⇒ nil

Deletes the topic.



285
286
287
288
 
# File 'lib/aws/sns/topic.rb', line 285

def delete
  client.delete_topic(:topic_arn => arn)
  nil
end

#delivery_policy_json ⇒ nil, String<JSON> 



209
210
211
 
# File 'lib/aws/sns/topic.rb', line 209

def delivery_policy_json
  to_h[:delivery_policy_json]
end

#display_name ⇒ String 



159
160
161
 
# File 'lib/aws/sns/topic.rb', line 159

def display_name
  to_h[:display_name]
end

#display_name=(display_name) ⇒ String 



167
168
169
170
 
# 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 ⇒ String<JSON> 



215
216
217
 
# File 'lib/aws/sns/topic.rb', line 215

def effective_delivery_policy_json
  to_h[:effective_delivery_policy_json]
end

#eql?(other) ⇒ Boolean Also known as: == 



320
321
322
 
# File 'lib/aws/sns/topic.rb', line 320

def eql? other
  other.kind_of?(Topic) and other.arn == arn
end

#name ⇒ String

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.



39
40
41
 
# File 'lib/aws/sns/topic.rb', line 39

def name
  arn.split(/:/)[-1]
end

#num_subscriptions_confirmed ⇒ Integer 



178
179
180
 
# File 'lib/aws/sns/topic.rb', line 178

def num_subscriptions_confirmed
  to_h[:num_subscriptions_confirmed]
end

#num_subscriptions_deleted ⇒ Integer 



188
189
190
 
# File 'lib/aws/sns/topic.rb', line 188

def num_subscriptions_deleted
  to_h[:num_subscriptions_deleted]
end

#num_subscriptions_pending ⇒ Integer 



183
184
185
 
# File 'lib/aws/sns/topic.rb', line 183

def num_subscriptions_pending
  to_h[:num_subscriptions_pending]
end

#owner ⇒ String 



173
174
175
 
# File 'lib/aws/sns/topic.rb', line 173

def owner
  to_h[:owner]
end

#policy ⇒ Policy 



193
194
195
 
# File 'lib/aws/sns/topic.rb', line 193

def policy
  to_h[:policy]
end

#policy=(policy) ⇒ nil

Sets the topic’s policy.



202
203
204
205
206
 
# 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 = {}) ⇒ String

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.

Options Hash (options):

  • :subject (String) —

    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

  • :http (String) —

    • Message to use when sending to an

    HTTP endpoint.

  • :https (String) —

    • Message to use when sending to an

    HTTPS endpoint.

  • :email (String) —

    • Message to use when sending to an

    email endpoint.

  • :email_json (String) —

    • Message to use when sending

    to an email json endpoint.

  • :sqs (String) —

    • Message to use when sending to an

    SQS endpoint.



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# 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 = {}) ⇒ Subscription?

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

Subscribing to SQS Queues

If you subscribe to an SQS queue (with a AWS::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)

Examples:

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


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

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'))

Email address as endpoint


topic.subscribe('[email protected]')

Email address as a JSON endpoint


# send messages encoded as json object to the given email address
topic.subscribe('[email protected]', :json => true)

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-east-1:123456789123:AQueue')

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)

Options Hash (options):

  • :json (Boolean) — default: false 


108
109
110
111
112
113
114
115
116
 
# 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 ⇒ TopicSubscriptionCollection 



151
152
153
 
# File 'lib/aws/sns/topic.rb', line 151

def subscriptions
  TopicSubscriptionCollection.new(self)
end

#to_h ⇒ Hash 



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# 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