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

CreateAgent

Activates an Amazon DataSync agent that you deploy in your storage environment. The activation process associates the agent with your Amazon Web Services 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.

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-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 your VPC service endpoint is located. You can only specify one ARN.

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-iso|aws-iso-b):ec2:[a-z\-0-9]*:[0-9]{12}:subnet/.*$

Required: No

Tags

Specifies labels that help you categorize, filter, and search for your Amazon 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).

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 Amazon Web Services account and Amazon Web Services Region.

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}:agent/agent-[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

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"
}