         | Did this page help you? Yes No Tell us about it... |
Working with Amazon S3 Substitutions
The substitutions option is helpful for changing file names,
appending prefixes or suffixes to file names, or other name changes during an Amazon S3
import or export job. For import jobs, use the substitutions option
to change object key names. For export jobs, use the substitutions
option to change names to write to your file system. For example, use the following entry to
replace all the uppercase "A", "B" and "C" letters in your file names and directories with
lowercase letters on the object key names before the data is uploaded to your Amazon S3
bucket.
The substitutions option can only be used when
manifestVersion is set to 2.0, and is not available
for Amazon EBS import jobs.
substitutions:
"A" : "a"
"B" : "b"
"C" : "c"![[Important]](http://docs.amazonwebservices.com/docs-common/images/important.png) | Important |
|---|---|
Avoid attempting to replace an entire value with an empty string. For import jobs, an empty string causes the import to fail and report a "400 InvalidSubstitution" error in the log. Also, avoid substitutions that result in multiple files mapping to the same file name. For import jobs, when multiple files map to the same file name, the behavior is undefined. For export jobs, when multiple files map to the same file name, the object falls into the recovery process. For more information about the recovery process, see Collecting Files That Have Naming Errors. |
The substitutions option is applied after any
prefix options are applied. First, the
prefix option determines what Amazon S3 data to copy. Then,
the substitutions option determines the value to write. For
export jobs, if a targetDirectory option is specified, the
substitutions option is applied to the targetDirectory value
while it is writing to your device.
Example: Using Both Prefix and Substitutions Options
prefix: myprefix$COLON$
substitutions:
"$COLON$" : ":"
"$QUOTE$" : "\""When you use the above options, you can enter a fully qualified file name on your device, such as:
/backup/$COLON$/$QUOTE$computer1$QUOTE$/c$COLON$/image.dat
AWS Import/Export performs the substitution and the file name becomes the following object name on Amazon S3.
myprefix:backup/:/"computer1"/c:/image.dat
Example: Using prefix, targetDirectory, and substitutions Options
substitutions:
":" : "$COLON$"
"," : "$COMMA$"
operations:
- exportBucket: mybucket
prefix: myprefix,
targetDirectory: data,When you use the above options, you can enter an Amazon S3 object name, such as:
mybucket/myprefix,/backup/:/computer1/c:/image.dat
AWS Import/Export performs the substitution, and the object name becomes the following fully qualified file name on your device.
/data$COMMA$/myprefix$COMMA$/backup/$COLON$/computer1/c$COLON$/image.dat
Example: Changing Name Space Encoding
In most cases the file system name space requirements are more restrictive than the Amazon S3 name space requirements, and you might need to map between valid file system names and the Amazon S3 key name space. For an import job, you can take advantage of Amazon S3's more expressive name space support by encoding the file name with information that is decoded before upload. In the following example, character encoding for a colon is converted to a colon in the Amazon S3 name space:
substitutions:
$COLON$ : ":"For an export job, you can handle characters that don't map to the file system.
substitutions:
":" : "$COLON$"
