AWS Import/Export
Developer Guide (API Version 2010-06-03)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Create Your First Amazon S3 Import Job

With an Amazon S3 import, AWS uploads individual files from your device to objects in an Amazon S3 bucket. If you encrypt your data using TrueCrypt, the data is decrypted using the password you provide. One device is loaded to one bucket. Your device's file system is mounted on an AWS Import/Export data loading station and each file is uploaded as an object in your Amazon S3 bucket. You can optionally manage directories and filenames as part of the load process.

After the import operation completes, AWS Import/Export erases your device before shipping it.

You must submit a separate job request for each device.

Note

You can send multiple devices in the same shipment. If you do, however, there are specific guidelines and limitations that govern what devices you can ship and how your devices must be packaged. If your shipment is not prepared and packed correctly, AWS Import/Export cannot process your jobs. Regardless of how many devices you ship at one time, you must submit a separate job request for each device. For complete details about packaging requirements when shipping multiple devices, see Shipping Multiple Devices.

For more information, see Guidelines and Limitations

You must submit a separate job request for each device.

To create an Amazon S3 import job

  1. Create a manifest file.

  2. Prepare your device for shipping.

  3. Send a CreateJob request.

    AWS Import/Export sends a response with a SIGNATURE file and job information.

  4. Copy the SIGNATURE file to your device.

  5. Ship your device.

Tip

You can create an Amazon S3 bucket using AWS Management Console. For more information, go to http://docs.aws.amazon.com/AmazonS3/latest/UG/CreatingaBucket.html.

These steps assume that you have signed up for an AWS account and created your AWScredentials.properties file as described in the earlier tasks.

Create a Manifest File

The manifest file is a YAML-formatted text file that tells AWS how to handle your job. It consists of a set of name-value pairs that supply required information, such as your device ID, TrueCrypt password, and return address. For more information about YAML, go to http://yaml.org.

The AWS Import/Export Web Service Tool provides three examples of manifest files that you can modify for your import and export jobs.

  1. Go to the Examples folder in the folder where you installed the AWS Import/Export Web Service Tool.

  2. Open the S3-import-manifest.txt file in a text editor.

    manifestVersion:2.0
    generator:Text editor
    bucket:[Enter import bucket]
    deviceId:[Enter device serial number]
    eraseDevice:yes
    notificationEmail: [Email addresses, semicolon separated]
    trueCryptPassword: [Optional – password]
    acl:private
    serviceLevel:standard
    returnAddress:
        name:[Your name]
        company:[Optional - your company]
        street1:[Your street]
        street2:[Optional - additional street info]
        street3:[Optional - additional street info]
        city:[Your city]
        stateOrProvince:[Required for USA and Canada. Your state or province.]
        postalCode:[Your postal code]
        country:[Your country]
        phoneNumber: [Contact number]
    

    Important

    When shipping devices internationally except within the European Union you must include the customs option in the manifest. For more information about the customs manifest option, see Customs Manifest File Option.

  3. In the file, replace all text in brackets with the appropriate values. Delete any unused optional lines.

  4. Provide the name of the existing Amazon S3 bucket where you want to upload your data. AWS Import/Export loads the data to a single bucket. For the bucket option provide only the name of your bucket, for example s3examplebucket.

  5. For the eraseDevice field, specify yes to acknowledge that AWS will erase your device following the import operation before shipping it. If the eraseDevice field is missing or if the value is not yes, the job request will fail.

  6. For the notificationEmail field, enter one or more email addresses, separated by semicolons, so we can contact you if there are any problems. If the notificationEmail field is missing or empty, the job request will fail.

  7. Save the file as MyS3ImportManifest.txt in the same folder as your AWSCredentials.properties file.

For more information about manifest file options, see Creating Import Manifests.

Prepare Your Device for Import

Next, you prepare your device for import.

  1. Optionally encrypt your data using TrueCrypt.

    For added security, we strongly recommend that you encrypt your data. You can encrypt the drive or create an encrypted file container on your device. For more information, see Using TrueCrypt Encryption.

  2. Verify that all file names are valid. File names must use standard ASCII or UTF-8 character encoding. Any file with a name that is not a valid ASCII or UTF-8 string is not imported.

  3. Copy your data to the device. Do not ship the only copy of your data. AWS will erase your device, even if we cannot perform an import.

If your device is not properly prepared for import, AWS might erase the device and return it without processing the request. If we are unable to erase the data on the device, we will schedule it for destruction and our support team will contact you using the email address specified in the manifest file. For more information, see Shipping Your Storage Device.

Send a CreateJob Request

Now that you have your credentials file and manifest file in place, you send a CreateJob request to AWS Import/Export. You submit a separate CreateJob request for each device.

  1. Open a command prompt (or, on a Mac, use the Terminal application), and change to the directory where you unzipped the AWS Import/Export tool.

  2. Enter the following CreateJob request on the command line.

    CmdPrompt>java -jar lib/AWSImportExportWebServiceTool-1.0.jar CreateJob Import MyS3ImportManifest.txt .  

    The CreateJob request includes a directory name for where you want the SIGNATURE file saved. In this example, the closing period (.) at the end of the command refers to the current directory. Either include the period, as shown above, or replace it with a directory name.

If there is an error, AWS Import/Export returns an error message.

If there are no errors in the request, AWS Import/Export returns a JOB CREATED response. The following is a sample response.

JOB CREATED 
	JobId: ABCDE 
	JobType: Import 
	**************************************** 
	* AwsShippingAddress * 
	**************************************** 
	AWS Import/Export C/O AnyCompany 
	JOBID ABCDE 
	123 Any Street 
	Anytown, VA 22153 
	**************************************** 
	* SignatureFileContents * 
	**************************************** 
	version:2.0 
	signingMethod:HmacSHA1 
	jobId:ABCDE-VALIDATE-ONLY 
	signature:cbfdUuhhmauYS+ABCl5R9heDK/V= 
	Writing SignatureFileContents to cmdPrompt\.\SIGNATURE

Your job expires after 30 days. If you do not send a device, there is no charge.

Copy the Signature File

In response to your CreateJob request, AWS writes a file named SIGNATURE to your computer. The SIGNATURE file contains a signature, which is an encrypted string that allows us to authenticate your device and match it to your job request.

Locate the SIGNATURE file in the directory you specified in your job request and copy it to the root directory of your storage device. The file name must be named SIGNATURE and it must be in the device's root directory.

Each device you send must include the unique SIGNATURE file for that device and that JOBID. AWS Import/Export validates the SIGNATURE file on your storage device before starting the data load. If the SIGNATURE file is missing or invalid (for example, if it is associated with a different job request), AWS Import/Export will not perform the data load and we will return your storage device.

Ship Your Device

It is essential that you prepare your device properly before shipping.

Note

You can send multiple devices in the same shipment. If you do, however, there are specific guidelines and limitations that govern what devices you can ship and how your devices must be packaged. If your shipment is not prepared and packed correctly, AWS Import/Export cannot process your jobs. Regardless of how many devices you ship at one time, you must submit a separate job request for each device. For complete details about packaging requirements when shipping multiple devices, see Shipping Multiple Devices.

  1. Pack the power supply, power cable, and interface cables with your storage device. Without these, we can't transfer your data and will return your device.

  2. Fill out the packing slip and include the packing slip with your device and cables.

    Download the packing slip from http://s3.amazonaws.com/awsimportexport/AWS_Import_Export_Packing_Slip.pdf.

  3. Send your package to the address provided in the CreateJob response.

    For detailed instructions for preparing and shipping your device, see Shipping Your Storage Device.

Important

Your job expires after 30 days. If you do not send a device, there is no charge. You are billed only after AWS Import/Export receives your device. If we receive your package after your job expires, we will return your device. You will only be charged for the shipping fees, if any.

Now, you have explored the getting started steps of AWS Import/Export. To learn more about the product, see Where Do I Go from Here?.