AWS Snowball

(1)

AWS Snowball

API Reference

AWS Snowball: API Reference

(2)

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Job Management API Reference

The job management API for AWS Snowball is a network protocol based on HTTP (RFC 2616). For more information on this RFC, see HTTP (RFC 2616) on the IETF website. For each call to the job management API, you make an HTTP request to the region-speciﬁc job management API endpoint for the AWS Region where you want to manage jobs. The API uses JSON (RFC 4627) documents for HTTP request/response bodies.

NoteAPI calls made within the US regions for listing jobs or describing addresses return all jobs or addresses within the US for that account.

The job management API for Snowball is an RPC model. In this model, there is a fixed set of operations and the syntax for each operation is known to clients without any previous interaction. Following, you can find a description of each API operation using an abstract RPC notation, with an operation name that does not appear on the wire. For each operation, the topic specifies the mapping to HTTP request elements.

The speciﬁc job management operation to which a given request maps is determined by a combination of the request's method (GET, PUT, POST, or DELETE) and which of the various patterns its Request-URI matches. If the operation is PUT or POST, Snowball extracts call arguments from the Request-URI path segment, query parameters, and the JSON object in the request body.

Although the operation name, such as CreateJob, doesn't appear on the wire, these operation names are meaningful in AWS Identity and Access Management (IAM) policies. The operation name is also used to name commands in command-line tools and elements of the AWS SDK APIs. For example, the AWS Command Line Interface (AWS CLI) command create-job maps to the CreateJob operation. The operation name also appears in CloudTrail logs for Snowball API calls.

For information on installing and setting up the AWS CLI, including specifying what regions you want to make AWS CLI calls against, see the AWS Command Line Interface User Guide.

NoteThe job management API provides programmatic access to the same functionality available in the AWS Snowball Management Console, that is to create and manage jobs for Snowball. To transfer data locally with a Snowball appliance, use the Snowball client or the S3 SDK Adapter for Snowball. For more information, see Transferring Data with a Snowball in the AWS Snowball User Guide.

If you use a Snowball Edge, use the Snowball client to unlock the appliance. For more information, see Using the Snowball Client in the AWS Snowball Developer Guide.

API Endpoint

The API endpoint is the Domain Name Service (DNS) name used as a host in the HTTP URI for the API calls. These API endpoints are region-speciﬁc and take the following form.

snowball.aws-region.amazonaws.com

For example, the Snowball API endpoint for the US West (Oregon) Region is the following.

snowball.us-west-2.amazonaws.com

(6)

For a list of AWS Regions that Snowball supports (where you can create and manage jobs), see AWS Import/Export in the AWS General Reference.

The region-speciﬁc API endpoint deﬁnes the scope of the Snowball resources that are accessible when you make an API call. For example, when you call the ListJobs operation using the preceding endpoint, you get a list of jobs in the US West (Oregon) Region that have been created in your account.

API Version

The version of the API being used for a call is identiﬁed by the ﬁrst path segment of the request URI, and its form is an ISO 8601 date. The documentation describes API version 2016-06-30.

API Permission Policy Reference

The following policies are needed for creating jobs with the job management API for Snowball.

Role Trust Policy for Creating Jobs

Using the job management API to create jobs requires the following trust policy.

{

"Version": "2012-10-17", "Statement": [

{

"Sid": "",

"Effect": "Allow", "Principal": {

"Service": "importexport.amazonaws.com"

},

"Action": "sts:AssumeRole", "Condition": {

"StringEquals": {

"sts:ExternalId": "AWSIE"

} } } ]}

NoteTo learn more about trust policies, see Modifying a Role in the IAM User Guide.

Role Policy for Creating Import Jobs

Creating an import job requires the following role policy.

{

"Effect": "Allow", "Action": [

"s3:GetBucketLocation",

"s3:ListBucketMultipartUploads"

],

"Resource": "arn:aws:s3:::*"

},

(7)

API Permission Policy Reference

{

"s3:GetBucketPolicy", "s3:PutObject",

"s3:AbortMultipartUpload", "s3:ListMultipartUploadParts", "s3:PutObjectAcl"

],

}, {

"snowball:*"

],

"Resource": [ "*"

] } ] }

Role Policy for Creating Export Jobs

Creating an export job requires the following role policy.

{ "Version": "2012-10-17", "Statement": [

{

"s3:GetBucketLocation", "s3:GetObject",

"s3:ListBucket"

],

}, {

"snowball:*"

],

"Resource": [ "*"

] } ] }

Amazon S3 Bucket Policy Principal for Creating Jobs

In some cases, the Amazon S3 buckets that you use with Snowball have bucket policies in place that require listing the role session name of the assumed role. In these cases, you need to specify a principal in those policies that identiﬁes AWSImportExport-Validation. The following Amazon S3 bucket policy example demonstrates how to do so.

Example

{ "Version": "2012-10-17",

(8)

"Statement": {

"Sid": "Allow AWS Snowball To Create Jobs", "Effect": "Deny",

"NotPrincipal": { "AWS": [

"arn:aws:iam::111122223333:role/rolename",

"arn:aws:sts::111122223333:assumed-role/rolename/AWSImportExport-Validation", "arn:aws:iam::111122223333:root"

]

}, "Action": "S3:*",

"Resource": ["arn:aws:s3:::examplebucket/*"]

}}

In this policy example, we deny access to all principals except the one named in the NotPrincipal element. For more information on how to use NotPrincipal, see NotPrincipal in the IAM User Guide.

NoteFor jobs in AWS GovCloud (US), Snowball uses AWSIEJob as the role session name of the assumed role.

Creating an IAM Role for Snowball and Snowball Edge

An IAM role policy must be created with read and write permissions for your Amazon S3 buckets. The IAM role must also have a trust relationship with Snowball. Having a trust relationship means that AWS can write the data in the Snowball and in your Amazon S3 buckets, depending on whether you're importing or exporting data.

When you create a job in the AWS Snow Family Management Console, creating the necessary IAM role occurs in step 4 in the Permission section. This process is automatic. The IAM role that you allow Snowball to assume is only used to write your data to your bucket when the Snowball with your transferred data arrives at AWS. The following procedure outlines that process.

To create the IAM role for your import job

1. Sign in to the AWS Management Console and open the AWS Snowball console at https://

console.aws.amazon.com/importexport/.

2. Choose Create job.

3. In the ﬁrst step, ﬁll out the details for your import job into Amazon S3, and then choose Next.

4. In the second step, under Permission, choose Create/Select IAM Role.

The IAM Management Console opens, showing the IAM role that AWS uses to copy objects into your speciﬁed Amazon S3 buckets.

5. Review the details on this page, and then choose Allow.

You return to the AWS Snow Family Management Console, where Selected IAM role ARN contains the Amazon Resource Name (ARN) for the IAM role that you just created.

6. Choose Next to ﬁnish creating your IAM role.

The preceding procedure creates an IAM role that has write permissions for the Amazon S3 buckets that you plan to import your data into. The IAM role that is created has one of the following structures, depending on whether it's for an import job or export job.

(9)

Creating an IAM Role for Snowball and Snowball Edge

IAM Role for an Import Job

{

"s3:GetBucketLocation",

"s3:ListBucketMultipartUploads"

],

}, {

"s3:GetBucketPolicy", "s3:PutObject",

"s3:AbortMultipartUpload", "s3:ListMultipartUploadParts", "s3:PutObjectAcl"

],

} ]}

If you use server-side encryption with AWS KMS–managed keys (SSE-KMS) to encrypt the Amazon S3 buckets associated with your import job, you also need to add the following statement to your IAM role.

{ "Effect": "Allow", "Action": [

"kms:GenerateDataKey"

],

"Resource": "arn:aws:s3:::SSEKMSEncryptedBucketName"

}

IAM Role for an Export Job {

{

"s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetObject", "s3:ListBucket"

],

} ] }

If you use server-side encryption with AWS KMS–managed keys to encrypt the Amazon S3 buckets associated with your export job, you also need to add the following statement to your IAM role.

{

(10)

“kms:Decrypt”

],

"Resource": "arn:aws:s3:::SSEKMSEncryptedBucketName"

}

(11)

Actions

The following actions are supported by AWS Snowball:

• CancelCluster (p. 9)

• CancelJob (p. 11)

• CreateAddress (p. 13)

• CreateCluster (p. 15)

• CreateJob (p. 21)

• CreateLongTermPricing (p. 29)

• CreateReturnShippingLabel (p. 31)

• DescribeAddress (p. 34)

• DescribeAddresses (p. 36)

• DescribeCluster (p. 39)

• DescribeJob (p. 42)

• DescribeReturnShippingLabel (p. 47)

• GetJobManifest (p. 49)

• GetJobUnlockCode (p. 51)

• GetSnowballUsage (p. 53)

• GetSoftwareUpdates (p. 54)

• ListClusterJobs (p. 56)

• ListClusters (p. 59)

• ListCompatibleImages (p. 61)

• ListJobs (p. 63)

• ListLongTermPricing (p. 65)

• UpdateCluster (p. 67)

• UpdateJob (p. 71)

• UpdateJobShipmentState (p. 75)

• UpdateLongTermPricing (p. 77)

The following actions are supported by AWS Snow Device Management:

• CancelTask (p. 79)

• CreateTask (p. 81)

• DescribeDevice (p. 84)

• DescribeDeviceEc2Instances (p. 88)

• DescribeExecution (p. 91)

• DescribeTask (p. 94)

• ListDeviceResources (p. 97)

• ListDevices (p. 100)

• ListExecutions (p. 103)

• ListTagsForResource (p. 106)

• ListTasks (p. 108)

• TagResource (p. 111)

(12)

• UntagResource (p. 113)

AWS Snowball

The following actions are supported by AWS Snowball:

• CancelCluster (p. 9)

• CancelJob (p. 11)

• CreateAddress (p. 13)

• CreateCluster (p. 15)

• CreateJob (p. 21)

• CreateLongTermPricing (p. 29)

• CreateReturnShippingLabel (p. 31)

• DescribeAddress (p. 34)

• DescribeAddresses (p. 36)

• DescribeCluster (p. 39)

• DescribeJob (p. 42)

• DescribeReturnShippingLabel (p. 47)

• GetJobManifest (p. 49)

• GetJobUnlockCode (p. 51)

• GetSnowballUsage (p. 53)

• GetSoftwareUpdates (p. 54)

• ListClusterJobs (p. 56)

• ListClusters (p. 59)

• ListCompatibleImages (p. 61)

• ListJobs (p. 63)

• ListLongTermPricing (p. 65)

• UpdateCluster (p. 67)

• UpdateJob (p. 71)

• UpdateJobShipmentState (p. 75)

• UpdateLongTermPricing (p. 77)

(13)

CancelCluster

Service: AWS Snowball

Cancels a cluster job. You can only cancel a cluster job while it's in the AwaitingQuorum status. You'll have at least an hour after creating a cluster job to cancel it.

Request Syntax

{ "ClusterId": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 173).

The request accepts the following data in JSON format.

ClusterId (p. 9)

The 39-character ID for the cluster that you want to cancel, for example CID123e4567- e89b-12d3-a456-426655440000.

Type: String

Length Constraints: Fixed length of 39.

Pattern: CID[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 175).

InvalidJobStateException

The action can't be performed because the job's current state doesn't allow that action to be performed.

HTTP Status Code: 400 InvalidResourceException

The speciﬁed resource can't be found. Check the information you provided in your last request, and try again.

HTTP Status Code: 400 KMSRequestFailedException

The provided AWS Key Management Service key lacks the permissions to perform the speciﬁed CreateJob (p. 21) or UpdateJob (p. 71) action.

(14)

HTTP Status Code: 400

CancelJob

Cancels the speciﬁed job. You can only cancel a job before its JobState value changes to

PreparingAppliance. Requesting the ListJobs or DescribeJob action returns a job's JobState as part of the response element data returned.

Request Syntax

{ "JobId": "string"

}

Request Parameters

JobId (p. 11)

The 39-character job ID for the job that you want to cancel, for example JID123e4567- e89b-12d3-a456-426655440000.

Type: String

Pattern: (M|J)ID[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InvalidJobStateException

(16)

CreateAddress

Creates an address for a Snow device to be shipped to. Addresses are validated at the time of creation.

The address you provide must be located within the serviceable area of your region. If the address is invalid or unsupported, then an exception is thrown.

Request Syntax

{ "Address": {

"AddressId": "string", "City": "string", "Company": "string", "Country": "string", "IsRestricted": boolean, "Landmark": "string", "Name": "string", "PhoneNumber": "string", "PostalCode": "string",

"PrefectureOrDistrict": "string", "StateOrProvince": "string", "Street1": "string",

"Street2": "string", "Street3": "string"

} }

Request Parameters

Address (p. 13)

The address that you want the Snow device shipped to.

Type: Address (p. 117) object Required: Yes

Response Syntax

{ "AddressId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

(18)

AddressId (p. 13)

The automatically generated ID for a speciﬁc address. You'll use this ID when you create a job to specify which address you want the Snow device for that job shipped to.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Errors

InvalidAddressException

The address provided was invalid. Check the address with your region's carrier, and try again.

HTTP Status Code: 400 UnsupportedAddressException

The address is either outside the serviceable area for your region, or an error occurred. Check the address with your region's carrier and try again. If the issue persists, contact AWS Support.

CreateCluster

Creates an empty cluster. Each cluster supports ﬁve nodes. You use the CreateJob (p. 21) action

separately to create the jobs for each of these nodes. The cluster does not ship until these ﬁve node jobs have been created.

Request Syntax

{ "AddressId": "string", "Description": "string",

"ForwardingAddressId": "string", "JobType": "string",

"KmsKeyARN": "string", "Notification": {

"JobStatesToNotify": [ "string" ], "NotifyAll": boolean,

"SnsTopicARN": "string"

},

"OnDeviceServiceConfiguration": { "NFSOnDeviceService": { "StorageLimit": number, "StorageUnit": "string"

},

"TGWOnDeviceService": { "StorageLimit": number, "StorageUnit": "string"

} },

"RemoteManagement": "string", "Resources": {

"Ec2AmiResources": [ {

"AmiId": "string",

"SnowballAmiId": "string"

} ],

"LambdaResources": [ {

"EventTriggers": [ {

"EventResourceARN": "string"

} ],

"LambdaArn": "string"

} ],

"S3Resources": [ {

"BucketArn": "string", "KeyRange": {

"BeginMarker": "string", "EndMarker": "string"

},

"TargetOnDeviceServices": [ {

"ServiceName": "string", "TransferOption": "string"

} ] } ]

(20)

},

"RoleARN": "string", "ShippingOption": "string", "SnowballType": "string", "TaxDocuments": { "IND": {

"GSTIN": "string"

} } }

Request Parameters

The ID for the address that you want the cluster shipped to.

Type: String

Pattern: ADID[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: Yes Description (p. 15)

An optional description of this speciﬁc cluster, for example Environmental Data Cluster-01.

Type: String

Required: No

ForwardingAddressId (p. 15)

This ﬁeld is not supported in your region.

Type: String

Required: No JobType (p. 15)

The type of job for this cluster. Currently, the only job type supported for clusters is LOCAL_USE.

For information about Snow Family device types, see Snow Family Devices and Capacity in the Snowcone User Guide or Snow Family Devices and Capacity in the Snowball Edge User Guide.

Type: String

Valid Values: IMPORT | EXPORT | LOCAL_USE

(21)

CreateCluster

Required: Yes KmsKeyARN (p. 15)

The KmsKeyARN value that you want to associate with this cluster. KmsKeyARN values are created by using the CreateKey API action in AWS Key Management Service (AWS KMS).

Type: String

Length Constraints: Maximum length of 255.

Pattern: arn:aws.*:kms:.*:[0-9]{12}:key/.*

Required: No Notiﬁcation (p. 15)

The Amazon Simple Notiﬁcation Service (Amazon SNS) notiﬁcation settings for this cluster.

Type: Notiﬁcation (p. 144) object Required: No

OnDeviceServiceConﬁguration (p. 15)

Speciﬁes the service or services on the Snow Family device that your transferred data will be exported from or imported into. AWS Snow Family device clusters support Amazon S3 and NFS (Network File System).

Type: OnDeviceServiceConﬁguration (p. 145) object Required: No

RemoteManagement (p. 15)

Allows you to securely operate and manage Snow devices in a cluster remotely from outside of your internal network. When set to INSTALLED_AUTOSTART, remote management will automatically be available when the device arrives at your location. Otherwise, you need to use the Snowball Client to manage the device.

Type: String

Valid Values: INSTALLED_ONLY | INSTALLED_AUTOSTART Required: No

Resources (p. 15)

The resources associated with the cluster job. These resources include Amazon S3 buckets and optional AWS Lambda functions written in the Python language.

Type: JobResource (p. 138) object Required: Yes

RoleARN (p. 15)

The RoleARN that you want to associate with this cluster. RoleArn values are created by using the CreateRole API action in AWS Identity and Access Management (IAM).

Type: String

Pattern: arn:aws.*:iam::[0-9]{12}:role/.*

(22)

Required: Yes ShippingOption (p. 15)

The shipping speed for each node in this cluster. This speed doesn't dictate how soon you'll get each Snowball Edge device, rather it represents how quickly each device moves to its destination while in transit. Regional shipping speeds are as follows:

• In Australia, you have access to express shipping. Typically, Snow devices shipped express are delivered in about a day.

• In the European Union (EU), you have access to express shipping. Typically, Snow devices shipped express are delivered in about a day. In addition, most countries in the EU have access to standard shipping, which typically takes less than a week, one way.

• In India, Snow devices are delivered in one to seven days.

• In the United States of America (US), you have access to one-day shipping and two-day shipping.

• In Australia, you have access to express shipping. Typically, devices shipped express are delivered in about a day.

• In the US, you have access to one-day shipping and two-day shipping.

Type: String

Valid Values: SECOND_DAY | NEXT_DAY | EXPRESS | STANDARD Required: Yes

SnowballType (p. 15)

The type of Snow Family devices to use for this cluster.

NoteFor cluster jobs, AWS Snow Family currently supports only the EDGE device type.

Type: String

TaxDocuments (p. 15)

The tax documents required in your AWS Region.

Type: TaxDocuments (p. 151) object Required: No

Response Syntax

}

(23)

CreateCluster

Response Elements

The automatically generated ID for a cluster.

Type: String

Errors

Ec2RequestFailedException

Your IAM user lacks the necessary Amazon EC2 permissions to perform the attempted action.

InvalidInputCombinationException

Job or cluster creation failed. One or more inputs were invalid. Conﬁrm that the

CreateCluster:SnowballType (p. 18) value supports your CreateJob:JobType (p. 24), and try again.

CreateJob

Creates a job to import or export data between Amazon S3 and your on-premises data center. Your AWS account must have the right trust policies and permissions in place to create a job for a Snow device. If you're creating a job for a node in a cluster, you only need to provide the clusterId value; the other job attributes are inherited from the cluster.

NoteOnly the Snowball; Edge device type is supported when ordering clustered jobs.

The device capacity is optional.

Availability of device types diﬀer by AWS Region. For more information about Region availability, see AWS Regional Services.

Snow Family devices and their capacities.

• Snow Family device type: SNC1_SSD

• Capacity: T14

• Description: Snowcone

• Snow Family device type: SNC1_HDD

• Capacity: T8

• Description: Snowcone

• Device type: EDGE_S

• Capacity: T98

• Description: Snowball Edge Storage Optimized for data transfer only

• Device type: EDGE_CG

• Capacity: T42

• Description: Snowball Edge Compute Optimized with GPU

• Device type: EDGE_C

• Capacity: T42

• Description: Snowball Edge Compute Optimized without GPU

• Device type: EDGE

• Capacity: T100

• Description: Snowball Edge Storage Optimized with EC2 Compute

• Device type: STANDARD

• Capacity: T50

• Description: Original Snowball device

NoteThis device is only available in the Ningxia, Beijing, and Singapore AWS Region

• Device type: STANDARD

• Capacity: T80

• Description: Original Snowball device

NoteThis device is only available in the Ningxia, Beijing, and Singapore AWS Region.

(26)

Request Syntax

{ "AddressId": "string", "ClusterId": "string", "Description": "string", "DeviceConfiguration": {

"SnowconeDeviceConfiguration": { "WirelessConnection": { "IsWifiEnabled": boolean }

} },

"KmsKeyARN": "string",

"LongTermPricingId": "string", "Notification": {

},

} },

"AmiId": "string",

"SnowballAmiId": "string"

} ],

"S3Resources": [ {

},

(27)

CreateJob

} ] } ] },

"RoleARN": "string", "ShippingOption": "string",

"SnowballCapacityPreference": "string", "SnowballType": "string",

"TaxDocuments": { "IND": {

"GSTIN": "string"

} } }

Request Parameters

The ID for the address that you want the Snow device shipped to.

Type: String

Required: No ClusterId (p. 22)

The ID of a cluster. If you're creating a job for a node in a cluster, you need to provide only this clusterId value. The other job attributes are inherited from the cluster.

Type: String

Required: No Description (p. 22)

Deﬁnes an optional description of this speciﬁc job, for example Important Photos 2016-08-11.

Type: String

Required: No

DeviceConﬁguration (p. 22)

Deﬁnes the device conﬁguration for an AWS Snowcone job.

(28)

Type: DeviceConﬁguration (p. 126) object Required: No

ForwardingAddressId (p. 22)

This ﬁeld is not supported in your Region.

Type: String

Required: No JobType (p. 22)

Deﬁnes the type of job that you're creating.

Type: String

Valid Values: IMPORT | EXPORT | LOCAL_USE Required: No

KmsKeyARN (p. 22)

The KmsKeyARN that you want to associate with this job. KmsKeyARNs are created using the CreateKey AWS Key Management Service (KMS) API action.

Type: String

Pattern: arn:aws.*:kms:.*:[0-9]{12}:key/.*

Required: No

LongTermPricingId (p. 22)

The ID of the long-term pricing type for the device.

Type: String

Pattern: LTPID[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: No Notiﬁcation (p. 22)

Defines the Amazon Simple Notification Service (Amazon SNS) notification settings for this job.

Type: Notiﬁcation (p. 144) object Required: No

OnDeviceServiceConﬁguration (p. 22)

Speciﬁes the service or services on the Snow Family device that your transferred data will be exported from or imported into. AWS Snow Family supports Amazon S3 and NFS (Network File System) and the AWS Storage Gateway service Tape Gateway type.

Type: OnDeviceServiceConﬁguration (p. 145) object

(29)

CreateJob

Required: No

RemoteManagement (p. 22)

Allows you to securely operate and manage Snowcone devices remotely from outside of your internal network. When set to INSTALLED_AUTOSTART, remote management will automatically be available when the device arrives at your location. Otherwise, you need to use the Snowball Client to manage the device.

Type: String

Valid Values: INSTALLED_ONLY | INSTALLED_AUTOSTART Required: No

Resources (p. 22)

Deﬁnes the Amazon S3 buckets associated with this job.

With IMPORT jobs, you specify the bucket or buckets that your transferred data will be imported into.

With EXPORT jobs, you specify the bucket or buckets that your transferred data will be exported from. Optionally, you can also specify a KeyRange value. If you choose to export a range, you deﬁne the length of the range by providing either an inclusive BeginMarker value, an inclusive EndMarker value, or both. Ranges are UTF-8 binary sorted.

Type: JobResource (p. 138) object Required: No

RoleARN (p. 22)

The RoleARN that you want to associate with this job. RoleArns are created using the CreateRole AWS Identity and Access Management (IAM) API action.

Type: String

Pattern: arn:aws.*:iam::[0-9]{12}:role/.*

Required: No ShippingOption (p. 22)

The shipping speed for this job. This speed doesn't dictate how soon you'll get the Snow device, rather it represents how quickly the Snow device moves to its destination while in transit. Regional shipping speeds are as follows:

• In Australia, you have access to express shipping. Typically, Snow devices shipped express are delivered in about a day.

• In the US, you have access to one-day shipping and two-day shipping.

Type: String

Valid Values: SECOND_DAY | NEXT_DAY | EXPRESS | STANDARD Required: No

(30)

SnowballCapacityPreference (p. 22)

If your job is being created in one of the US regions, you have the option of specifying what size Snow device you'd like for this job. In all other regions, Snowballs come with 80 TB in storage capacity.

Type: String

Valid Values: T50 | T80 | T100 | T42 | T98 | T8 | T14 | NoPreference Required: No

The type of Snow Family devices to use for this job.

NoteFor cluster jobs, AWS Snow Family currently supports only the EDGE device type.

The type of AWS Snow device to use for this job. Currently, the only supported device type for cluster jobs is EDGE.

For more information, see Snowball Edge Device Options in the Snowball Edge Developer Guide.

Type: String

TaxDocuments (p. 22)

The tax documents required in your AWS Region.

Type: TaxDocuments (p. 151) object Required: No

Response Syntax

{ "JobId": "string"

}

Response Elements

JobId (p. 26)

The automatically generated ID for a job, for example JID123e4567-e89b-12d3- a456-426655440000.

(31)

CreateJob

Type: String

Errors

ClusterLimitExceededException

Job creation failed. Currently, clusters support five nodes. If you have fewer than five nodes for your cluster and you have more nodes to create for this cluster, try again and create jobs until your cluster has exactly five nodes.

HTTP Status Code: 400 Ec2RequestFailedException

Your IAM user lacks the necessary Amazon EC2 permissions to perform the attempted action.

CreateLongTermPricing

Creates a job with the long-term usage option for a device. The long-term usage is a 1-year or 3-year long-term pricing type for the device. You are billed upfront, and AWS provides discounts for long-term pricing.

Request Syntax

{ "IsLongTermPricingAutoRenew": boolean, "LongTermPricingType": "string", "SnowballType": "string"

}

Request Parameters

IsLongTermPricingAutoRenew (p. 29)

Speciﬁes whether the current long-term pricing type for the device should be renewed.

Type: Boolean Required: No

LongTermPricingType (p. 29)

The type of long-term pricing option you want for the device, either 1-year or 3-year long-term pricing.

Type: String

Valid Values: OneYear | ThreeYear Required: Yes

The type of Snow Family devices to use for the long-term pricing job.

Type: String

Response Syntax

{ "LongTermPricingId": "string"

}

(34)

Response Elements

LongTermPricingId (p. 29)

The ID of the long-term pricing type for the device.

Type: String

Pattern: LTPID[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Errors

InvalidResourceException

CreateReturnShippingLabel

Creates a shipping label that will be used to return the Snow device to AWS.

Request Syntax

{ "JobId": "string",

"ShippingOption": "string"

}

Request Parameters

JobId (p. 31)

The ID for a job that you want to create the return shipping label for; for example, JID123e4567- e89b-12d3-a456-426655440000.

Type: String

Required: Yes ShippingOption (p. 31)

The shipping speed for a particular job. This speed doesn't dictate how soon the device is returned to AWS. This speed represents how quickly it moves to its destination while in transit. Regional shipping speeds are as follows:

Type: String

Valid Values: SECOND_DAY | NEXT_DAY | EXPRESS | STANDARD Required: No

Response Syntax

{

"Status": "string"

}

Response Elements

(36)

Status (p. 31)

The status information of the task on a Snow device that is being returned to AWS.

Type: String

Valid Values: InProgress | TimedOut | Succeeded | Failed

Errors

ConﬂictException

You get this exception when you call CreateReturnShippingLabel more than once when other requests are not completed.

HTTP Status Code: 400 InvalidJobStateException

ReturnShippingLabelAlreadyExistsException

You get this exception if you call CreateReturnShippingLabel and a valid return shipping label already exists. In this case, use DescribeReturnShippingLabel to get the URL.

DescribeAddress

Takes an AddressId and returns speciﬁc details about that address in the form of an Address object.

Request Syntax

{ "AddressId": "string"

}

Request Parameters

The automatically generated ID for a speciﬁc address.

Type: String

Required: Yes

Response Syntax

{

"Address": {

"PrefectureOrDistrict": "string", "StateOrProvince": "string", "Street1": "string",

"Street2": "string", "Street3": "string"

}}

Response Elements

(39)

DescribeAddress

Address (p. 34)

The address that you want the Snow device(s) associated with a speciﬁc job to be shipped to.

Type: Address (p. 117) object

Errors

DescribeAddresses

Returns a speciﬁed number of ADDRESS objects. Calling this API in one of the US regions will return addresses from the list of all addresses associated with this account in all US regions.

Request Syntax

{ "MaxResults": number, "NextToken": "string"

}

Request Parameters

MaxResults (p. 36)

The number of ADDRESS objects to return.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 100.

Required: No NextToken (p. 36)

HTTP requests are stateless. To identify what object comes "next" in the list of ADDRESS objects, you have the option of specifying a value for NextToken as the starting point for your list of returned addresses.

Type: String

Required: No

Response Syntax

{ "Addresses": [ {

"PrefectureOrDistrict": "string", "StateOrProvince": "string",

(41)

DescribeAddresses

"Street1": "string", "Street2": "string", "Street3": "string"

} ],

"NextToken": "string"

}

Response Elements

Addresses (p. 36)

The Snow device shipping addresses that were created for this account.

Type: Array of Address (p. 117) objects NextToken (p. 36)

HTTP requests are stateless. If you use the automatically generated NextToken value in your next DescribeAddresses call, your list of returned addresses will start from this point in the array.

Type: String

Errors

InvalidNextTokenException

The NextToken string was altered unexpectedly, and the operation has stopped. Run the operation without changing the NextToken string, and try again.

DescribeCluster

Returns information about a speciﬁc cluster including shipping information, cluster status, and other important metadata.

Request Syntax

}

Request Parameters

The automatically generated ID for a cluster.

Type: String

Required: Yes

Response Syntax

{ "ClusterMetadata": { "AddressId": "string", "ClusterId": "string", "ClusterState": "string", "CreationDate": number, "Description": "string",

"KmsKeyARN": "string", "Notification": {

},

"OnDeviceServiceConfiguration": { "NFSOnDeviceService": {

"StorageLimit": number, "StorageUnit": "string"

},

}

(44)

},

"Resources": {

"AmiId": "string", "SnowballAmiId": "string"

} ],

"S3Resources": [ {

},

} ] } ] },

"RoleARN": "string", "ShippingOption": "string", "SnowballType": "string", "TaxDocuments": { "IND": {

"GSTIN": "string"

} } }}

Response Elements

ClusterMetadata (p. 39)

Information about a speciﬁc cluster, including shipping information, cluster status, and other important metadata.

Type: ClusterMetadata (p. 121) object

Errors

(45)

DescribeCluster

DescribeJob

Returns information about a speciﬁc job including shipping information, job status, and other important metadata.

Request Syntax

{ "JobId": "string"

}

Request Parameters

JobId (p. 42)

The automatically generated ID for a job, for example JID123e4567-e89b-12d3- a456-426655440000.

Type: String

Required: Yes

Response Syntax

{ "JobMetadata": {

"AddressId": "string", "ClusterId": "string", "CreationDate": number, "DataTransferProgress": { "BytesTransferred": number, "ObjectsTransferred": number, "TotalBytes": number,

"TotalObjects": number },

"Description": "string", "DeviceConfiguration": {

} },

"ForwardingAddressId": "string", "JobId": "string",

"JobLogInfo": {

"JobCompletionReportURI": "string", "JobFailureLogURI": "string",

(47)

DescribeJob

"JobSuccessLogURI": "string"

},

"JobState": "string", "JobType": "string", "KmsKeyARN": "string",

},

"OnDeviceServiceConfiguration": { "NFSOnDeviceService": {

"StorageLimit": number, "StorageUnit": "string"

},

} },

} ],

"S3Resources": [ {

},

} ] } ] },

"RoleARN": "string", "ShippingDetails": { "InboundShipment": { "Status": "string", "TrackingNumber": "string"

},

"OutboundShipment": { "Status": "string", "TrackingNumber": "string"

},

(48)

},

"GSTIN": "string"

} } },

"SubJobMetadata": [ {

"AddressId": "string", "ClusterId": "string", "CreationDate": number, "DataTransferProgress": { "BytesTransferred": number, "ObjectsTransferred": number, "TotalBytes": number,

"TotalObjects": number },

"Description": "string", "DeviceConfiguration": {

} },

"ForwardingAddressId": "string", "JobId": "string",

"JobLogInfo": {

"JobCompletionReportURI": "string", "JobFailureLogURI": "string", "JobSuccessLogURI": "string"

},

"JobState": "string", "JobType": "string", "KmsKeyARN": "string",

},

} },

} ],

(49)

DescribeJob

} ],

"S3Resources": [ {

},

} ] } ] },

"RoleARN": "string", "ShippingDetails": { "InboundShipment": { "Status": "string",

"TrackingNumber": "string"

},

"OutboundShipment": { "Status": "string",

"TrackingNumber": "string"

},

"GSTIN": "string"

} } } ]}

Response Elements

JobMetadata (p. 42)

Information about a speciﬁc job, including shipping information, job status, and other important metadata.

Type: JobMetadata (p. 134) object SubJobMetadata (p. 42)

Information about a speciﬁc job part (in the case of an export job), including shipping information, job status, and other important metadata.

Type: Array of JobMetadata (p. 134) objects

AWS Snowball

AWS Snowball

API Reference

AWS Snowball: API Reference

Table of Contents

Job Management API Reference

API Endpoint

API Version

API Permission Policy Reference

Creating an IAM Role for Snowball and Snowball Edge

Actions

AWS Snowball

CancelCluster

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CancelJob

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CreateAddress

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateCluster

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateJob

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateLongTermPricing

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateReturnShippingLabel

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeAddress

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeAddresses

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeCluster

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also