DescribeAgent - Amazon DataSync
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

DescribeAgent

Returns metadata about an Amazon DataSync agent, such as its name, endpoint type, and status.

Request Syntax

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

AgentArn

Specifies the Amazon Resource Name (ARN) of the DataSync agent to describe.

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

Required: Yes

Response Syntax

{ "AgentArn": "string", "CreationTime": number, "EndpointType": "string", "LastConnectionTime": number, "Name": "string", "PrivateLinkConfig": { "PrivateLinkEndpoint": "string", "SecurityGroupArns": [ "string" ], "SubnetArns": [ "string" ], "VpcEndpointId": "string" }, "Status": "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.

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

CreationTime

The time that the agent was activated (that is, created in your account).

Type: Timestamp

EndpointType

The type of endpoint that your agent is connected to. If the endpoint is a VPC endpoint, the agent is not accessible over the public internet.

Type: String

Valid Values: PUBLIC | PRIVATE_LINK | FIPS

LastConnectionTime

The time that the agent last connected to DataSync.

Type: Timestamp

Name

The name of the agent.

Type: String

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

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

PrivateLinkConfig

The subnet and the security group that DataSync used to access a VPC endpoint.

Type: PrivateLinkConfig object

Status

The status of the agent. If the status is ONLINE, then the agent is configured properly and is available to use. The Running status is the normal running status for an agent. If the status is OFFLINE, the agent's VM is turned off or the agent is in an unhealthy state. When the issue that caused the unhealthy state is resolved, the agent returns to ONLINE status.

Type: String

Valid Values: ONLINE | OFFLINE

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

Example

The following example returns information about the agent specified in the sample request.

Sample Request

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

Example

This example illustrates one usage of DescribeAgent.

Sample Response

{ "AgentArn": "arn:aws:datasync:us-east-2:111222333444:agent/agent-0b0addbeef44baca3", "CreationTime": "1532660733.39", "LastConnectionTime": "1532660733.39", "Name": "MyAgent", "Status": "ONLINE" }

See Also

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