DescribeTaskExecution - AWS DataSync

DescribeTaskExecution

Provides information about an execution of your AWS DataSync task. You can use this operation to help monitor the progress of an ongoing transfer or check the results of the transfer.

Request Syntax

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

TaskExecutionArn

Specifies the Amazon Resource Name (ARN) of the task execution that you want information about.

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}:task/task-[0-9a-f]{17}/execution/exec-[0-9a-f]{17}$

Required: Yes

Response Syntax

{ "BytesCompressed": number, "BytesTransferred": number, "BytesWritten": number, "EstimatedBytesToTransfer": number, "EstimatedFilesToDelete": number, "EstimatedFilesToTransfer": number, "Excludes": [ { "FilterType": "string", "Value": "string" } ], "FilesDeleted": number, "FilesSkipped": number, "FilesTransferred": number, "FilesVerified": number, "Includes": [ { "FilterType": "string", "Value": "string" } ], "ManifestConfig": { "Action": "string", "Format": "string", "Source": { "S3": { "BucketAccessRoleArn": "string", "ManifestObjectPath": "string", "ManifestObjectVersionId": "string", "S3BucketArn": "string" } } }, "Options": { "Atime": "string", "BytesPerSecond": number, "Gid": "string", "LogLevel": "string", "Mtime": "string", "ObjectTags": "string", "OverwriteMode": "string", "PosixPermissions": "string", "PreserveDeletedFiles": "string", "PreserveDevices": "string", "SecurityDescriptorCopyFlags": "string", "TaskQueueing": "string", "TransferMode": "string", "Uid": "string", "VerifyMode": "string" }, "ReportResult": { "ErrorCode": "string", "ErrorDetail": "string", "Status": "string" }, "Result": { "ErrorCode": "string", "ErrorDetail": "string", "PrepareDuration": number, "PrepareStatus": "string", "TotalDuration": number, "TransferDuration": number, "TransferStatus": "string", "VerifyDuration": number, "VerifyStatus": "string" }, "StartTime": number, "Status": "string", "TaskExecutionArn": "string", "TaskReportConfig": { "Destination": { "S3": { "BucketAccessRoleArn": "string", "S3BucketArn": "string", "Subdirectory": "string" } }, "ObjectVersionIds": "string", "OutputType": "string", "Overrides": { "Deleted": { "ReportLevel": "string" }, "Skipped": { "ReportLevel": "string" }, "Transferred": { "ReportLevel": "string" }, "Verified": { "ReportLevel": "string" } }, "ReportLevel": "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.

BytesCompressed

The physical number of bytes transferred over the network after compression was applied. In most cases, this number is less than BytesTransferred unless the data isn't compressible.

Type: Long

BytesTransferred

The total number of bytes that are involved in the transfer. For the number of bytes sent over the network, see BytesCompressed.

Type: Long

BytesWritten

The number of logical bytes written to the destination location.

Type: Long

EstimatedBytesToTransfer

The estimated physical number of bytes that will transfer over the network.

Type: Long

EstimatedFilesToDelete

The expected number of files, objects, and directories that DataSync will delete in your destination location. If you don't configure your task to delete data in the destination that isn't in the source, the value is always 0.

Type: Long

EstimatedFilesToTransfer

The expected number of files, objects, and directories that DataSync will transfer over the network. This value is calculated during the task execution's PREPARING phase before the TRANSFERRING phase. The calculation is based on comparing the content of the source and destination locations and finding the difference that needs to be transferred.

Type: Long

Excludes

A list of filter rules that exclude specific data during your transfer. For more information and examples, see Filtering data transferred by DataSync.

Type: Array of FilterRule objects

Array Members: Minimum number of 0 items. Maximum number of 1 item.

FilesDeleted

The number of files, objects, and directories that DataSync deleted in your destination location. If you don't configure your task to delete data in the destination that isn't in the source, the value is always 0.

Type: Long

FilesSkipped

The number of files, objects, and directories that DataSync skipped during your transfer.

Type: Long

FilesTransferred

The actual number of files, objects, and directories that DataSync transferred over the network. This value is updated periodically during the task execution's TRANSFERRING phase when something is read from the source and sent over the network.

If DataSync fails to transfer something, this value can be less than EstimatedFilesToTransfer. In some cases, this value can also be greater than EstimatedFilesToTransfer. This element is implementation-specific for some location types, so don't use it as an exact indication of what transferred or to monitor your task execution.

Type: Long

FilesVerified

The number of files, objects, and directories that DataSync verified during your transfer.

Note

When you configure your task to verify only the data that's transferred, DataSync doesn't verify directories in some situations or files that fail to transfer.

Type: Long

Includes

A list of filter rules that include specific data during your transfer. For more information and examples, see Filtering data transferred by DataSync.

Type: Array of FilterRule objects

Array Members: Minimum number of 0 items. Maximum number of 1 item.

ManifestConfig

The configuration of the manifest that lists the files or objects to transfer. For more information, see Specifying what DataSync transfers by using a manifest.

Type: ManifestConfig object

Options

Indicates how your transfer task is configured. These options include how DataSync handles files, objects, and their associated metadata during your transfer. You also can specify how to verify data integrity, set bandwidth limits for your task, among other options.

Each option has a default value. Unless you need to, you don't have to configure any of these options before starting your task.

Type: Options object

ReportResult

Indicates whether DataSync generated a complete task report for your transfer.

Type: ReportResult object

Result

The result of the task execution.

Type: TaskExecutionResultDetail object

StartTime

The time when the task execution started.

Type: Timestamp

Status

The status of the task execution.

For detailed information about task execution statuses, see Task execution statuses.

Type: String

Valid Values: QUEUED | LAUNCHING | PREPARING | TRANSFERRING | VERIFYING | SUCCESS | ERROR

TaskExecutionArn

The ARN of the task execution that you wanted information about. TaskExecutionArn is hierarchical and includes TaskArn for the task that was executed.

For example, a TaskExecution value with the ARN arn:aws:datasync:us-east-1:111222333444:task/task-0208075f79cedf4a2/execution/exec-08ef1e88ec491019b executed the task with the ARN arn:aws:datasync:us-east-1:111222333444:task/task-0208075f79cedf4a2.

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}:task/task-[0-9a-f]{17}/execution/exec-[0-9a-f]{17}$

TaskReportConfig

The configuration of your task report, which provides detailed information about for your DataSync transfer. For more information, see Creating a task report.

Type: TaskReportConfig object

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

Sample Request

This example illustrates a DescribeTaskExecution request.

{ "TaskExecutionArn": "arn:aws:datasync:us-east-1:111222333444:task/task-aaaabbbbccccddddf/execution/exec-1234abcd1234abcd1" }

Sample Response

This example illustrates a DescribeTaskExecution response.

{ "BytesCompressed": 3500, "BytesTransferred": 5000, "BytesWritten": 5000, "EstimatedBytesToTransfer": 5000, "EstimatedFilesToDelete": 10, "EstimatedFilesToTransfer": 100, "FilesDeleted": 10, "FilesSkipped": 0, "FilesTransferred": 100, "FilesVerified": 100, "Result": { "ErrorCode": "??????", "ErrorDetail": "??????", "PrepareDuration": 100, "PrepareStatus": "SUCCESS", "TransferDuration": 60, "TransferStatus": "AVAILABLE", "VerifyDuration": 30, "VerifyStatus": "SUCCESS" }, "StartTime": 1532660733.39, "Status": "SUCCESS", "OverrideOptions": { "Atime": "BEST_EFFORT", "BytesPerSecond": "1000", "Gid": "NONE", "Mtime": "PRESERVE", "PosixPermissions": "PRESERVE", "PreserveDevices": "NONE", "PreserveDeletedFiles": "PRESERVE", "Uid": "NONE", "VerifyMode": "POINT_IN_TIME_CONSISTENT" }, "TaskExecutionArn": "arn:aws:datasync:us-east-1:111222333444:task/task-aaaabbbbccccddddf/execution/exec-1234abcd1234abcd1", "TaskReportConfig": { "Destination": { "S3": { "BucketAccessRoleArn": "arn:aws:iam::111222333444:role/my-datasync-role", "S3BucketArn": "arn:aws:s3:::my-task-reports-bucket/*", "Subdirectory": "reports" } }, "ObjectVersionIds": "INCLUDE", "OutputType": "STANDARD", "Overrides": { "Deleted": { "ReportLevel": "ERRORS_ONLY" }, "Skipped": { "ReportLevel": "SUCCESSES_AND_ERRORS" }, "Transferred": { "ReportLevel": "ERRORS_ONLY" }, "Verified": { "ReportLevel": "ERRORS_ONLY" } }, "ReportLevel": "ERRORS_ONLY" } }

See Also

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