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

Class: AWS::S3::BucketLifecycleConfiguration

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/s3/bucket_lifecycle_configuration.rb

Overview

A lifecycle configuration specify rules that manage the way Amazon S3 stores objects. The rules apply to objects whose keys match the rule's prefix.

Rules

A rule is comprised primarily of an id, prefix and set of configuration options. Configuration options on the rules can specify:

  • When to expire an object
  • When to transition an object to Glacier
  • Whether the rule is enabled or disabled

See Rule for more information on all of the attributes and methods available for rules.

Expiring Objects

You can add a rule to a bucket lifecycle configuration using #add_rule inside of an #update block that will expire an object after a given number of days:

# delete backups after they are 1 year old
bucket.lifecycle_configuration.update do
  add_rule('backups/', :expiration_time => 365)
end

You can also define the rule to expire objects at a specific date:

# delete backups on January 1st of next year
bucket.lifecycle_configuration.update do
  date = Date.new(Time.now.year + 1, 01, 01)
  add_rule('backups/', :expiration_time => date)
end

Transitioning Objects to Glacier

You can add a rule to a bucket lifecycle configuration using #add_rule inside of an #update block that will transition objects to Glacier after a given number of days:

# move backups to Glacier after 3 days
bucket.lifecycle_configuration.update do
  add_rule('backups/', :glacier_transition_time => 3)
end

You can also define the rule to transition objects at a specific date:

# transition all backups on January 1st of next year
bucket.lifecycle_configuration.update do
  date = Date.new(Time.now.year + 1, 01, 01)
  add_rule('backups/', :glacier_transition_time => date)
end

Replacing Rules

If you prefer to completely replace a lifecycle configuration, call #add_rule inside a #replace block instead of an #update block:

# replace all existing rules with the following
bucket.lifecycle_configuration.replace do
  add_rule('backups/', :glacier_transition_time => 10)
  add_rule('temp/', :expiration_time => 30)
end

Removing Rules

You can delete specific rules with #remove_rule.

# delete all disabled rules
bucket.lifecycle_configuration.update do
  rules.each do |rule|
    remove_rule(rule) if rule.disabled?
  end
end

You can also remove all rules in a single call with #clear:

# remove all rules from this lifecycle configuration
bucket.lifecycle_configuration.clear

Editing Existing Rules

You can also make changes to existing rules.

# change the expiration days to 10 for EVERY rule
bucket.lifecycle_configuration.update do
  rules.each do |rule|
    rule.expiration_time = 10
  end
end

Please be aware, if you add, remove or edit rules outside of an #update or #replace block, then you must call #update yourself or the changes will not be persisted.

Defined Under Namespace

Classes: Rule

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#bucket ⇒ Bucket (readonly)

Returns the bucket this lifecycle configuration belongs to.

Returns:

  • (Bucket) —

    Returns the bucket this lifecycle configuration belongs to.



126
127
128
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 126

def bucket
  @bucket
end

Instance Method Details

#add_rule(prefix, options = {}) ⇒ Rule

Returns the rule that was added, as a Rule object.

Parameters:

  • prefix (String) —

    objects whose keys begin with this prefix will be affected by the rule.

Options Hash (options):

  • :id (String) —

    A unique ID for this rule. If an ID is not provided, one will be generated.

  • :disabled (Boolean) — default: false —

    By default, all rules will have the status of enabled. You can override this default by passing :disabled => true.

  • :expiration_time (Date, Integer) — default: nil —

    Indicates the lifetime for objects matching the given prefix.

  • :glacier_transition_time (Date, Integer) — default: nil —

    Indicates the time before objects matching the given prefix will be transitioned into the Amazon Glacier storage tier.

Returns:

  • (Rule) —

    Returns the rule that was added, as a Rule object.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 160

def add_rule prefix, expiration_time = nil, options = {}
  if Hash === expiration_time
    options = expiration_time
  else
    options[:expiration_time] = expiration_time
  end

  id = options[:id] || SecureRandom.uuid
  opts = {
    :status => options[:disabled] == true ? 'Disabled' : 'Enabled',
    :expiration_time => options[:expiration_time],
    :glacier_transition_time => options[:glacier_transition_time],
    :noncurrent_version_transition_days => options[:noncurrent_version_transition_days],
    :noncurrent_version_expiration_days => options[:noncurrent_version_expiration_days]
  }
  rule = Rule.new(self, id, prefix, opts)
  self.rules << rule
  rule
end

#clear ⇒ Object Also known as: remove 



276
277
278
279
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 276

def clear
  @rules = []
  bucket.lifecycle_configuration = nil
end

#remove_rule(rule_or_rule_id) ⇒ nil

Removes a single rule. You can pass a rule id or a Rule object.

# remove a single rule by its ID
bucket.lifecycle_configuration.update do
  remove_rule('rule-id')
end

# remove all disabled rules
bucket.lifecycle_configuration.update do
  rules.each do |rule|
    remove_rule(rule) if rule.disabled?
  end
end

If you call #remove_rule outside an update block you need to call #update to save the changes.

Parameters:

  • rule_or_rule_id (Rule, String)

Returns:

  • (nil) 


202
203
204
205
206
207
208
209
210
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 202

def remove_rule rule_or_rule_id
  rule_id = rule_or_rule_id
  if rule_id.nil?
    raise ArgumentError, "expected a rule or rule id, got nil"
  end
  rule_id = rule_id.id unless rule_id.is_a?(String)
  @rules = rules.select{|r| r.id != rule_id }
  nil
end

#replace(&block) ⇒ Object

Yields to the given block. Before yielding, the current rules will be blanked out. This allows you to provide all new rules.

When the block is complete, a single call will be made to save the new rules.

bucket.lifecycle_configuration.rules.size #=> 3

# replace the existing 3 rules with a single rule
bucket.lifecycle_configuration.replace
  add_rule 'temp/', 10
end

bucket.lifecycle_configuration.rules.size #=> 1



271
272
273
274
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 271

def replace &block
  @rules = []
  update(&block)
end

#rules ⇒ Array<Hash>

Returns an array of rules.

Returns:

  • (Array<Hash>) —

    Returns an array of rules.



129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 129

def rules
  @rules ||= begin
    begin
      opts = { :bucket_name => bucket.name }
      response = bucket.client.get_bucket_lifecycle_configuration(opts)
      parse_xml(response.http_response.body)
    rescue Errors::NoSuchLifecycleConfiguration
      []
    end
  end
end

#to_xml ⇒ String

Returns an xml string representation of this bucket lifecycle configuration.

Returns:

  • (String) —

    Returns an xml string representation of this bucket lifecycle configuration.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 284

def to_xml
  Nokogiri::XML::Builder.new do |xml|
    xml.LifecycleConfiguration do
      rules.each do |rule|
        xml.Rule do
          xml.ID rule.id
          xml.Prefix rule.prefix
          xml.Status rule.status
          xml.Expiration do
            if Integer === rule.expiration_time
              xml.Days rule.expiration_time
            else
              date = rule.expiration_time.to_s
              xml.Date "#{date}T00:00:00Z"
            end
          end if rule.expiration_time
          xml.Transition do
            xml.StorageClass 'GLACIER'
            if Integer === rule.glacier_transition_time
              xml.Days rule.glacier_transition_time
            else
              date = rule.glacier_transition_time.to_s
              xml.Date "#{date}T00:00:00Z"
            end
          end if rule.glacier_transition_time
          xml.NoncurrentVersionTransition do
            xml.StorageClass 'GLACIER'
            xml.NoncurrentDays rule.noncurrent_version_transition_days
          end if rule.noncurrent_version_transition_days
          xml.NoncurrentVersionExpiration do
            xml.NoncurrentDays rule.noncurrent_version_expiration_days
          end if rule.noncurrent_version_expiration_days
        end
      end
    end
  end.doc.root.to_xml
end

#update(arg = {}, &block) ⇒ nil

Saves changes made to this lifecycle configuration.

# set the number of days before expiration for all rules to 10
config = bucket.lifecycle_configuration
config.rules.each do |rule|
  rule.expiration_time = 10
end
config.update

You can call #update with a block. Changes are persisted at the end of the block.

# shorter version of the example above
bucket.lifecycle_configuration.update do
  rules.each {|rule| rule.expiration_time = 10 }
end

A block method for updating a BucketLifecycleConfiguration. All modifications made inside the block are persisted at the end of the block.

# 1 request
bucket.lifecycle_configuration.update do
  add_rule 'prefix/a', 10
  add_rule 'prefix/b', 5
end

# 2 requests
bucket.lifecycle_configuration.add_rule 'prefix/a', 10
bucket.lifecycle_configuration.add_rule 'prefix/b', 5

Returns:

  • (nil) 


245
246
247
248
249
250
251
252
253
254
 
# File 'lib/aws/s3/bucket_lifecycle_configuration.rb', line 245

def update arg = {}, &block
  begin
    @batching = true
    instance_exec(arg, &block) if block_given?
    persist(true)
  ensure
    @batching = false
  end
  nil
end