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

CreateAgent

Activates an AWS DataSync agent that you deploy in your storage environment. The activation process associates the agent with your AWS account.

If you haven't deployed an agent yet, see Do I need a DataSync agent?

Request Syntax


{
   "ActivationKey": "string",
   "AgentName": "string",
   "SecurityGroupArns": [ "string" ],
   "SubnetArns": [ "string" ],
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "VpcEndpointId": "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.

ActivationKey

Specifies your DataSync agent's activation key. If you don't have an activation key, see Activating your agent.

Type: String

Length Constraints: Maximum length of 29.

Pattern: [A-Z0-9]{5}(-[A-Z0-9]{5}){4}

Required: Yes

AgentName

Specifies a name for your agent. We recommend specifying a name that you can remember.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: ^[a-zA-Z0-9\s+=._:@/-]+$

Required: No

SecurityGroupArns

Specifies the Amazon Resource Name (ARN) of the security group that allows traffic between your agent and VPC service endpoint. You can only specify one ARN.

The ARN must specify your own account, even when the security group was shared with you from the account that owns the VPC. The security group must belong to the same VPC as the subnet that you specify in SubnetArns.

Type: Array of strings

Array Members: Fixed number of 1 item.

Length Constraints: Maximum length of 128.

Pattern: ^arn:(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b):ec2:[a-z\-0-9]*:[0-9]{12}:security-group/sg-[a-f0-9]+$

Required: No

SubnetArns

Specifies the ARN of the subnet where DataSync creates the network interfaces that handle data transfer traffic for your tasks. You can only specify one ARN.

The subnet doesn't have to be the subnet that contains your VPC service endpoint. The subnet can be one that another AWS account shared with you through AWS RAM, in which case the ARN must specify the account that owns the subnet. For more information, see Using a single VPC service endpoint across multiple subnets.

Type: Array of strings

Array Members: Fixed number of 1 item.

Length Constraints: Maximum length of 128.

Pattern: ^arn:(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b):ec2:[a-z\-0-9]*:[0-9]{12}:subnet/subnet-[a-f0-9]+$

Required: No

Tags

Specifies labels that help you categorize, filter, and search for your AWS resources. We recommend creating at least one tag for your agent.

Type: Array of TagListEntry objects

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

Required: No

VpcEndpointId

Specifies the ID of the VPC service endpoint that you're using. For example, a VPC endpoint ID looks like vpce-01234d5aff67890e1.

Important

The VPC service endpoint you use must include the DataSync service name (for example, com.amazonaws.us-east-2.datasync).

The endpoint ID is informational. DataSync doesn't verify it or use it to connect to your agent. For more information, see Using a single VPC service endpoint across multiple subnets.

Type: String

Pattern: ^vpce-[0-9a-f]{17}$

Required: No

Response Syntax


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

AgentArn

The ARN of the agent that you just activated. Use the ListAgents operation to return a list of agents in your AWS account and AWS Region.

Type: String

Length Constraints: Maximum length of 128.

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

Errors

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

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

Sample Request

The following example activates a DataSync agent.


{
    "ActivationKey": "AAAAA-1AAAA-BB1CC-33333-EEEEE",
    "AgentName": "MyAgent",
    "Tags": [{
        "Key": "Job",
        "Value": "TransferJob-1"
    }]
}

Sample Response

The response returns the ARN of the activated agent.


{
    "AgentArn": "arn:aws:datasync:us-east-2:111222333444:agent/agent-0b0addbeef44baca3"
}