Job Management API Reference

The job management API for Amazon 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-specific job management API endpoint for the Amazon Web Services Region where you want to manage jobs. The API uses JSON (RFC 4627) documents for HTTP request/response bodies.

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 specific 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 Amazon Identity and Access Management (IAM) policies. The operation name is also used to name commands in command-line tools and elements of the Amazon SDK APIs. For example, the Amazon Command Line Interface (Amazon 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 Amazon CLI, including specifying what regions you want to make Amazon CLI calls against, see the Amazon Command Line Interface User 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-specific 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

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

The region-specific API endpoint defines 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 identified by the first 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"
        }
      }
    }
  ]
}

Role Policy for Creating Import Jobs

Creating an import job requires the following role policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucketMultipartUploads"
            ],
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketPolicy",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "snowball:*"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Role Policy for Creating Export Jobs

Creating an export job requires the following role policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::*"
    },
    {
       "Effect": "Allow",
       "Action": [
         "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 identifies AWSImportExport-Validation. The following Amazon S3 bucket policy example demonstrates how to do so.

{
	"Version": "2012-10-17",
	"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/*"]
	}
}

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 Amazon 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 Amazon 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 Amazon. The following procedure outlines that process.

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.

IAM Role for an Import Job

          {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": "arn:aws:s3:::*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketPolicy",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::*"
    }
  ]
}

If you use server-side encryption with Amazon 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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:GetBucketPolicy",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::*"
    }
  ]
}

If you use server-side encryption with Amazon 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.

{
     "Effect": "Allow",
     "Action": [
            “kms:Decrypt”
      ],
      "Resource": "arn:aws:s3:::SSEKMSEncryptedBucketName"
}