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

CreateAgent

Activates an Amazon DataSync agent that you've deployed 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 the following topics to learn more:

Note

If you're transferring between Amazon storage services, you don't 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 Activate 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. You can see this name in the DataSync console.

Type: String

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

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

Required: No

SecurityGroupArns

Specifies the Amazon Resource Name (ARN) of the security group that protects your task's network interfaces when using a virtual private cloud (VPC) 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 you want to run your DataSync task when using a VPC endpoint. This is the subnet where DataSync creates and manages the network interfaces for your transfer. 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 endpoint that you want your agent to connect to. For example, a VPC endpoint ID looks like vpce-01234d5aff67890e1.

Important

The VPC 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 and associates it with your Amazon Web Services account.


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