Class: Aws::S3::PresignedPost
- Inherits:
-
Object
- Object
- Aws::S3::PresignedPost
- Defined in:
- lib/aws-sdk-s3/presigned_post.rb
Overview
Normally you do not need to construct a PresignedPost yourself. See Bucket#presigned_post and Object#presigned_post.
## Basic Usage
To generate a presigned post, you need AWS credentials, the region your bucket is in, and the name of your bucket. You can apply constraints to the post object as options to #initialize or by calling methods such as #key and #content_length_range.
The following two examples are equivalent.
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket,
key: '/uploaded/object/key',
content_length_range: 0..1024,
acl: 'public-read',
metadata: {
'original-filename' => '${filename'
}
}) post.fields #=> { … }
post = Aws::S3::PresignedPost.new(creds, region, bucket).
key('/uploaded/object/key').
content_length_range(0..1024).
acl('public-read').
('original-filename' => '$filename').
fields
#=> { … } “‘
## HTML Forms
You can use a {PresignedPost} object to build an HTML form. It is recommended to use some helper to build the form tag and input tags that properly escapes values.
### Form Tag
To upload a file to Amazon S3 using a browser, you need to create a post form. The {#url} method returns the value you should use as the form action.
“‘erb <form action=“<%= @post.url %>” method=“post” enctype=“multipart/form-data”>
...
</form> “‘
The follow attributes must be set on the form:
-
‘action` - This must be the {#url}.
-
‘method` - This must be `post`.
-
‘enctype` - This must be `multipart/form-data`.
### Form Fields
The {#fields} method returns a hash of form fields to render inside the form. Typically these are rendered as hidden input fields.
“‘erb <% @post.fields.each do |name, value| %>
<input type="hidden" name="<%= name %>" value="<%= value %>"/>
<% end %> “‘
Lastly, the form must have a file field with the name ‘file`.
“‘erb <input type=“file” name=“file”/> “`
## Post Policy
When you construct a {PresignedPost}, you must specify every form field name that will be posted by the browser. If you omit a form field sent by the browser, Amazon S3 will reject the request. You can specify accepted form field values three ways:
-
Specify exactly what the value must be.
-
Specify what value the field starts with.
-
Specify the field may have any value.
### Field Equals
You can specify that a form field must be a certain value. Simply pass an option like ‘:content_type` to the constructor, or call the associated method.
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket). post.content_type(’text/plain’) “‘
If any of the given values are changed by the user in the form, then Amazon S3 will reject the POST request.
### Field Starts With
You can specify prefix values for many of the POST form fields. To specify a required prefix, use the ‘:<fieldname>_starts_with` option or call the associated `#<field_name>_starts_with` method.
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {
key_starts_with: '/images/',
content_type_starts_with: 'image/',
# ...
}) “‘
When using starts with, the form must contain a field where the user can specify the value. The {PresignedPost} will not add a value for these fields.
### Any Field Value
To white-list a form field to send any value, you can name that field with ‘:allow_any` or {#allow_any}.
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {
key: 'object-key',
allow_any: ['Filename'],
# ...
}) “‘
### Metadata
You can add rules for metadata fields using ‘:metadata`, {#metadata}, `:metadata_starts_with` and {#metadata_starts_with}. Unlike other form fields, you pass a hash value to these options/methods:
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket).
key('/fixed/key').
(foo: 'bar')
post.fields #=> ‘bar’ “‘
### The ‘${filename}` Variable
The string ‘${filename}` is automatically replaced with the name of the file provided by the user and is recognized by all form fields. It is not supported with `starts_with` conditions.
If the browser or client provides a full or partial path to the file, only the text following the last slash (/) or backslash () will be used (e.g., “C:Program Filesdirectory1file.txt” will be interpreted as “file.txt”). If no file or file name is provided, the variable is replaced with an empty string.
In the following example, we use ‘${filename}` to store the original filename in the `x-amz-meta-` hash with the uploaded object.
“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {
key: '/fixed/key',
metadata: {
'original-filename': '${filename}'
}
}) “‘
Instance Attribute Summary collapse
-
#url ⇒ String
readonly
The URL to post a file upload to.
Fields collapse
-
#acl(canned_acl) ⇒ self
Specify the cannedl ACL (access control list) for the object.
- #acl_starts_with(prefix) ⇒ self
-
#cache_control(value) ⇒ self
Specify caching behavior along the request/reply chain.
- #cache_control_starts_with(prefix) ⇒ self
-
#content_disposition(value) ⇒ self
Specifies presentational information for the object.
- #content_disposition_starts_with(prefix) ⇒ self
-
#content_encoding(value) ⇒ self
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
- #content_encoding_starts_with(prefix) ⇒ self
-
#content_length_range(byte_range) ⇒ self
The minimum and maximum allowable size for the uploaded content.
-
#content_type(value) ⇒ self
A standard MIME type describing the format of the contents.
- #content_type_starts_with(prefix) ⇒ self
-
#expires(time) ⇒ self
The date and time at which the object is no longer cacheable.
- #expires_starts_with(prefix) ⇒ self
-
#key(key) ⇒ self
The key to use for the uploaded object.
-
#key_starts_with(prefix) ⇒ self
Specify a prefix the uploaded.
-
#metadata(hash) ⇒ self
Metadata hash to store with the uploaded object.
-
#metadata_starts_with(hash) ⇒ self
Specify allowable prefix for each key in the metadata hash.
-
#storage_class(value) ⇒ self
Storage class to use for storing the object.
-
#success_action_redirect(value) ⇒ self
The URL to which the client is redirected upon successful upload.
- #success_action_redirect_starts_with(prefix) ⇒ self
-
#success_action_status(value) ⇒ self
The status code returned to the client upon successful upload if #success_action_redirect is not specified.
-
#website_redirect_location(value) ⇒ self
If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.
Server-Side Encryption Fields collapse
-
#server_side_encryption(value) ⇒ self
Specifies a server-side encryption algorithm to use when Amazon S3 creates an object.
-
#server_side_encryption_aws_kms_key_id(value) ⇒ self
If #server_side_encryption is called with the value of ‘aws:kms`, this method specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for the object.
Server-Side Encryption with Customer-Provided Key Fields collapse
-
#server_side_encryption_customer_algorithm(value) ⇒ self
Specifies the algorithm to use to when encrypting the object.
-
#server_side_encryption_customer_key(value) ⇒ self
Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data.
- #server_side_encryption_customer_key_starts_with(prefix) ⇒ self
Class Method Summary collapse
Instance Method Summary collapse
-
#allow_any(*field_names) ⇒ self
A list of form fields to white-list with any value.
-
#fields ⇒ Hash
A hash of fields to render in an HTML form as hidden input fields.
-
#initialize(credentials, bucket_region, bucket_name, options = {}) ⇒ PresignedPost
constructor
A new instance of PresignedPost.
Constructor Details
#initialize(credentials, bucket_region, bucket_name, options = {}) ⇒ PresignedPost
Returns a new instance of PresignedPost.
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 211 def initialize(credentials, bucket_region, bucket_name, = {}) @credentials = credentials.credentials @bucket_region = bucket_region @bucket_name = bucket_name @url = .delete(:url) || bucket_url @fields = {} @key_set = false @signature_expiration = Time.now + 3600 @conditions = [{ 'bucket' => @bucket_name }] .each do |option_name, option_value| case option_name when :allow_any then allow_any(option_value) when :signature_expiration then @signature_expiration = option_value else send("#{option_name}", option_value) end end end |
Instance Attribute Details
#url ⇒ String (readonly)
Returns The URL to post a file upload to. This should be the form action.
231 232 233 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 231 def url @url end |
Class Method Details
.define_field(field, *args) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
256 257 258 259 260 261 262 263 264 265 266 267 268 269 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 256 def self.define_field(field, *args) = args.last.is_a?(Hash) ? args.pop : {} field_name = args.last || field.to_s define_method("#{field}") do |value| with(field_name, value) end if [:starts_with] define_method("#{field}_starts_with") do |value| starts_with(field_name, value) end end end |
Instance Method Details
#acl(canned_acl) ⇒ self
Specify the cannedl ACL (access control list) for the object. May be one of the following values:
* `private`
* `public-read`
* `public-read-write`
* `authenticated-read`
* `bucket-owner-read`
* `bucket-owner-full-control`
317 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 317 define_field(:acl, starts_with: true) |
#acl_starts_with(prefix) ⇒ self
317 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 317 define_field(:acl, starts_with: true) |
#allow_any(*field_names) ⇒ self
A list of form fields to white-list with any value.
247 248 249 250 251 252 253 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 247 def allow_any(*field_names) field_names.flatten.each do |field_name| @key_set = true if field_name.to_s == 'key' starts_with(field_name, '') end self end |
#cache_control(value) ⇒ self
Specify caching behavior along the request/reply chain.
329 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 329 define_field(:cache_control, 'Cache-Control', starts_with: true) |
#cache_control_starts_with(prefix) ⇒ self
329 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 329 define_field(:cache_control, 'Cache-Control', starts_with: true) |
#content_disposition(value) ⇒ self
Specifies presentational information for the object.
354 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 354 define_field(:content_disposition, 'Content-Disposition', starts_with: true) |
#content_disposition_starts_with(prefix) ⇒ self
354 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 354 define_field(:content_disposition, 'Content-Disposition', starts_with: true) |
#content_encoding(value) ⇒ self
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
368 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 368 define_field(:content_encoding, 'Content-Encoding', starts_with: true) |
#content_encoding_starts_with(prefix) ⇒ self
368 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 368 define_field(:content_encoding, 'Content-Encoding', starts_with: true) |
#content_length_range(byte_range) ⇒ self
The minimum and maximum allowable size for the uploaded content.
390 391 392 393 394 395 396 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 390 def content_length_range(byte_range) min = byte_range.begin max = byte_range.end max -= 1 if byte_range.exclude_end? @conditions << ['content-length-range', min, max] self end |
#content_type(value) ⇒ self
A standard MIME type describing the format of the contents.
342 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 342 define_field(:content_type, 'Content-Type', starts_with: true) |
#content_type_starts_with(prefix) ⇒ self
342 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 342 define_field(:content_type, 'Content-Type', starts_with: true) |
#expires(time) ⇒ self
This does not affect the expiration of the presigned post signature.
The date and time at which the object is no longer cacheable.
376 377 378 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 376 def expires(time) with('Expires', time.httpdate) end |
#expires_starts_with(prefix) ⇒ self
383 384 385 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 383 def expires_starts_with(prefix) starts_with('Expires', prefix) end |
#fields ⇒ Hash
Returns A hash of fields to render in an HTML form as hidden input fields.
235 236 237 238 239 240 241 242 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 235 def fields check_required_values! datetime = Time.now.utc.strftime("%Y%m%dT%H%M%SZ") fields = @fields.dup fields.update('policy' => policy(datetime)) fields.update(signature_fields(datetime)) fields.update('x-amz-signature' => signature(datetime, fields['policy'])) end |
#key(key) ⇒ self
The key to use for the uploaded object. Use can use ‘$filename` as a variable in the key. This will be replaced with the name of the file as provided by the user.
For example, if the key is given as ‘/user/betty/$filename` and the file uploaded is named `lolcatz.jpg`, the resultant key will be `/user/betty/lolcatz.jpg`.
284 285 286 287 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 284 def key(key) @key_set = true with('key', key) end |
#key_starts_with(prefix) ⇒ self
Specify a prefix the uploaded
293 294 295 296 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 293 def key_starts_with(prefix) @key_set = true starts_with('key', prefix) end |
#metadata(hash) ⇒ self
Metadata hash to store with the uploaded object. Hash keys will be prefixed with “x-amz-meta-”.
469 470 471 472 473 474 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 469 def (hash) hash.each do |key, value| with("x-amz-meta-#{key}", value) end self end |
#metadata_starts_with(hash) ⇒ self
Specify allowable prefix for each key in the metadata hash.
480 481 482 483 484 485 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 480 def (hash) hash.each do |key, value| starts_with("x-amz-meta-#{key}", value) end self end |
#server_side_encryption(value) ⇒ self
Specifies a server-side encryption algorithm to use when Amazon S3 creates an object. Valid values include:
-
‘aws:kms`
-
‘AES256`
500 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 500 define_field(:server_side_encryption, 'x-amz-server-side-encryption') |
#server_side_encryption_aws_kms_key_id(value) ⇒ self
If #server_side_encryption is called with the value of ‘aws:kms`, this method specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for the object.
508 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 508 define_field(:server_side_encryption_aws_kms_key_id, 'x-amz-server-side-encryption-aws-kms-key-id') |
#server_side_encryption_customer_algorithm(value) ⇒ self
Specifies the algorithm to use to when encrypting the object. Must be set to ‘AES256` when using customer-provided encryption keys. Must also call #server_side_encryption_customer_key.
521 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 521 define_field(:server_side_encryption_customer_algorithm, 'x-amz-server-side-encryption-customer-algorithm') |
#server_side_encryption_customer_key(value) ⇒ self
Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key.
You must also call #server_side_encryption_customer_algorithm.
532 533 534 535 536 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 532 def server_side_encryption_customer_key(value) field_name = 'x-amz-server-side-encryption-customer-key' with(field_name, base64(value)) with(field_name + '-MD5', base64(OpenSSL::Digest::MD5.digest(value))) end |
#server_side_encryption_customer_key_starts_with(prefix) ⇒ self
541 542 543 544 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 541 def server_side_encryption_customer_key_starts_with(prefix) field_name = 'x-amz-server-side-encryption-customer-key' starts_with(field_name, prefix) end |
#storage_class(value) ⇒ self
Storage class to use for storing the object. Defaults to ‘STANDARD`. Must be one of:
-
‘STANDARD`
-
‘REDUCED_REDUNDANCY`
You cannot specify ‘GLACIER` as the storage class. To transition objects to the GLACIER storage class you can use lifecycle configuration.
447 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 447 define_field(:storage_class, 'x-amz-storage-class') |
#success_action_redirect(value) ⇒ self
The URL to which the client is redirected upon successful upload. If #success_action_redirect is not specified, Amazon S3 returns the empty document type specified by #success_action_status.
If Amazon S3 cannot interpret the URL, it acts as if the field is not present. If the upload fails, Amazon S3 displays an error and does not redirect the user to a URL.
415 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 415 define_field(:success_action_redirect, starts_with: true) |
#success_action_redirect_starts_with(prefix) ⇒ self
415 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 415 define_field(:success_action_redirect, starts_with: true) |
#success_action_status(value) ⇒ self
The status code returned to the client upon successful upload if #success_action_redirect is not specified.
Accepts the values ‘200`, `201`, or `204` (default).
If the value is set to 200 or 204, Amazon S3 returns an empty document with a 200 or 204 status code. If the value is set to 201, Amazon S3 returns an XML document with a 201 status code.
If the value is not set or if it is set to an invalid value, Amazon S3 returns an empty document with a 204 status code.
433 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 433 define_field(:success_action_status) |
#website_redirect_location(value) ⇒ self
If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores this value in the object metadata.
The value must be prefixed by, “/”, “http://” or “https://”. The length of the value is limited to 2K.
463 |
# File 'lib/aws-sdk-s3/presigned_post.rb', line 463 define_field(:website_redirect_location, 'x-amz-website-redirect-location') |