Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

CreateLocationS3

A location is an endpoint for an Amazon S3 bucket. Amazon DataSync can use the location as a source or destination for copying data.

Important

Before you create your location, make sure that you read the following sections:

For more information, see Creating an Amazon S3 location.

Request Syntax


{
   "AgentArns": [ "string" ],
   "S3BucketArn": "string",
   "S3Config": { 
      "BucketAccessRoleArn": "string"
   },
   "S3StorageClass": "string",
   "Subdirectory": "string",
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ]
}

Request Parameters

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

The request accepts the following data in JSON format.

AgentArns

If you're using DataSync on an Amazon Outpost, specify the Amazon Resource Names (ARNs) of the DataSync agents deployed on your Outpost. For more information about launching a DataSync agent on an Amazon Outpost, see Deploy your DataSync agent on Amazon Outposts.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 4 items.

Length Constraints: Maximum length of 128.

Pattern: ^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):datasync:[a-z\-0-9]+:[0-9]{12}:agent/agent-[0-9a-z]{17}$

Required: No

S3BucketArn

The ARN of the Amazon S3 bucket. If the bucket is on an Amazon Outpost, this must be an access point ARN.

Type: String

Length Constraints: Maximum length of 156.

Required: Yes

S3Config

The Amazon Resource Name (ARN) of the Amazon Identity and Access Management (IAM) role used to access an Amazon S3 bucket.

For detailed information about using such a role, see Creating a Location for Amazon S3 in the Amazon DataSync User Guide.

Type: S3Config object

Required: Yes

S3StorageClass

The Amazon S3 storage class that you want to store your files in when this location is used as a task destination. For buckets in Amazon Web Services Regions, the storage class defaults to Standard. For buckets on Amazon Outposts, the storage class defaults to Amazon S3 Outposts.

For more information about S3 storage classes, see Amazon S3 Storage Classes. Some storage classes have behaviors that can affect your S3 storage cost. For detailed information, see Considerations when working with S3 storage classes in DataSync.

Type: String

Required: No

Subdirectory

A subdirectory in the Amazon S3 bucket. This subdirectory in Amazon S3 is used to read data from the S3 source location or write data to the S3 destination.

Type: String

Length Constraints: Maximum length of 4096.

Pattern: ^[a-zA-Z0-9_\-\+\./\p{Zs}]*$

Required: No

Tags

The key-value pair that represents the tag that you want to add to the location. The value can be an empty string. We recommend using tags to name your resources.

Type: Array of TagListEntry objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No

Response Syntax


{
   "LocationArn": "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.

LocationArn

The Amazon Resource Name (ARN) of the source Amazon S3 bucket location that is created.

Type: String

Length Constraints: Maximum length of 128.

Pattern: ^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):datasync:[a-z\-0-9]+:[0-9]{12}:location/loc-[0-9a-z]{17}$

Errors

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

InternalException

This exception is thrown when an error occurs in the Amazon DataSync service.

HTTP Status Code: 500

InvalidRequestException

This exception is thrown when the client submits a malformed request.

HTTP Status Code: 400

Examples

Step 1. Allow to assume the IAM role required to write to the bucket

The following example shows the simplest policy that grants the required permissions for Amazon DataSync to access a destination Amazon S3 bucket, followed by an IAM role to which the create-location-s3-iam-role policy has been attached.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "datasync.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}


"Role": {
        "Path": "/",
        "RoleName": "MyBucketAccessRole",
        "RoleId": "role-id",
        "Arn": "arn:aws:iam::account-id:role/MyBucketAccessRole",
        "CreateDate": "2018-07-27T02:49:23.117Z",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "datasync.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                }
            ]
        }
    }
}

Step 2. Allow the created IAM role to write to the bucket

Attach a policy that has sufficient permissions to access the bucket to the role. An example of such policy is the AWSDataSyncFullAccess managed policy.

For more information, see AWSDataSyncFullAccess in the IAM console.

You don't need to create this policy. It's managed by Amazon, so all that you need to do is specify its ARN in the attach-role-policy command.


IAM_POLICY_ARN='arn:aws:iam::aws:policy/AWSDataSyncFullAccess'

Step 3. Create an endpoint for an Amazon S3 bucket

The following example creates an endpoint for an Amazon S3 bucket.

When the S3 endpoint is created, a response similar to the second example following returns the Amazon Resource Name (ARN) for the new Amazon S3 location.

Sample Request


{
  "S3BucketArn": "arn:aws:s3:::MyBucket",
  "S3Config": {
     "BucketAccessRoleArn": "arn:aws:iam::111222333444:role/MyBucketAccessRole",
    },
    "S3StorageClass": "STANDARD",
    "Subdirectory": "/MyFolder",
    "Tags": [
       {
          "Key": "Name",
          "Value": "s3Bucket-1"
       }
     ]
}

Sample Response


{
  "LocationArn": "arn:aws:datasync:us-east-2:111222333444:location/loc-07db7abfc326c50s3"
}