AWS DataSync
User Guide

CreateLocationS3

Creates an endpoint for an Amazon S3 bucket.

For AWS DataSync to access a destination S3 bucket, it needs an AWS Identity and Access Management (IAM) role that has the required permissions. You can set up the required permissions by creating an IAM policy that grants the required permissions and attaching the policy to the role. An example of such a policy is shown in the examples section.

For more information, see Configuring Amazon S3 Location Settings in the AWS DataSync User Guide.

Request Syntax

{ "S3BucketArn": "string", "S3Config": { "BucketAccessRoleArn": "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.

S3BucketArn

The Amazon Resource Name (ARN) of the Amazon S3 bucket.

Type: String

Length Constraints: Maximum length of 76.

Pattern: ^arn:(aws|aws-cn):s3:::([^/]*)$

Required: Yes

S3Config

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

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

Type: S3Config object

Required: Yes

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_\-\./]*$

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 55 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):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 AWS DataSync service.

HTTP Status Code: 500

InvalidRequestException

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

HTTP Status Code: 400

Examples

The following example shows the simplest policy that grants the required permissions for AWS DataSync to access a destination Amazon S3 bucket and attaches it to an IAM role.

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

{ "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 AdministratorAccess managed policy.

For more information, see AdministratorAccess in the IAM User Guide.

You don't need to create this policy. It's managed by AWS, 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/AdministratorAccess'

Examples

Example

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

Sample Request

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

Example

The following response returns the Amazon Resource Name (ARN) for the Amazon S3 location.

Sample Response

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

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: