You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::SNS::Topic

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from HasDeliveryPolicy

#delivery_policy, #delivery_policy=, #effective_delivery_policy

Constructor Details

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

Returns a new instance of Topic

Parameters:

  • arn (String) —

    The topic ARN.



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)

Returns The topic ARN.

Returns:

  • (String) —

    The topic ARN.



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.

Parameters:

  • token (String) —

    Short-lived token sent to an endpoint during the #subscribe action.

  • options (Hash) (defaults to: {}) —

    Additional options for confirming the subscription.

Options Hash (options):

  • :authenticate_on_unsubscribe (Boolean) —

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

Returns:



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.

Returns:

  • (nil) 


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>

Returns The delivery policy JSON string.

Returns:

  • (nil, String<JSON>) —

    The delivery policy JSON string.



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

def delivery_policy_json
  to_h[:delivery_policy_json]
end

#display_name ⇒ 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.

Returns:

  • (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.



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

def display_name
  to_h[:display_name]
end

#display_name=(display_name) ⇒ String

Returns the display_name as passed.

Parameters:

  • display_name (String) —

    Sets the human-readable name used in the "From" field for notifications to email and email-json endpoints.

Returns:

  • (String) —

    Returns the display_name as passed.



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>

Returns The effective delivery policy JSON string. into account system defaults.

Returns:

  • (String<JSON>) —

    The effective delivery policy JSON string. into account system defaults.



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: ==

Returns true if compared to another AWS::SNS::Topic with the same ARN.

Returns:

  • (Boolean) —

    Returns true if compared to another AWS::SNS::Topic with the same ARN.



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.

Returns:

  • (String) —

    Returns the topic name.



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

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

#num_subscriptions_confirmed ⇒ Integer

Returns number of confirmed topic subscriptions.

Returns:

  • (Integer) —

    Returns number of confirmed topic subscriptions.



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

Returns number of deleted topic subscriptions.

Returns:

  • (Integer) —

    Returns number of deleted topic subscriptions.



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

Returns number of pending topic subscriptions.

Returns:

  • (Integer) —

    Returns number of pending topic subscriptions.



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

def num_subscriptions_pending
  to_h[:num_subscriptions_pending]
end

#owner ⇒ String

Returns The topic owner's ID.

Returns:

  • (String) —

    The topic owner's ID.



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

def owner
  to_h[:owner]
end

#policy ⇒ Policy

Returns The topic's Policy.

Returns:



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.

Parameters:

  • policy (String, Policy) —

    A JSON policy string, a Policy object or any other object that responds to #to_json with a valid policy.

Returns:

  • (nil) 


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.

Parameters:

  • default_message (String) —

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

  • options (Hash) (defaults to: {})

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.

Returns:

  • (String) —

    Returns the ID of the message that was sent.



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('nobody@example.com')

Email address as a JSON endpoint


# send messages encoded as json object to the given email address
topic.subscribe('nobody@example.com', :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-west-2: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)

Parameters:

  • endpoint (mixed) —

    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
    • AWS::SQS::Queue
    • SQS queue ARN
    • phone number of an SMS-enabled device
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :json (Boolean) — default: false

Returns:

  • (Subscription, nil) —

    Returns a subscription when possible. If the subscription requires confirmation first, then nil is returned instead.



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

Returns a collection that represents all of the subscriptions for this topic.

Returns:



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

def subscriptions
  TopicSubscriptionCollection.new(self)
end

#to_h ⇒ 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

Returns:

  • (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


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