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 number of physical bytes that DataSync transfers over the network after compression. In most cases, this number is less than BytesTransferred unless the data isn't compressible.
Type: Long
- BytesTransferred
-
The number of bytes that DataSync sends to the network before compression. For the number of bytes transferred over the network, see BytesCompressed.
Type: Long
- BytesWritten
-
The number of logical bytes that DataSync actually writes to the destination location.
Type: Long
- EstimatedBytesToTransfer
-
The number of logical bytes that DataSync expects to write to the destination location.
Type: Long
- EstimatedFilesToDelete
-
The number of files, objects, and directories that DataSync expects to 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 number of files, objects, and directories that DataSync expects to transfer over the network. This value is calculated during the task execution's
PREPARING
phase before theTRANSFERRING
phase.How this gets calculated depends primarily on your task’s TransferMode configuration:
-
If
TranserMode
is set toCHANGED
- The calculation is based on comparing the content of the source and destination locations and determining the difference that needs to be transferred. The difference can include:-
Anything that's added or modified at the source location.
-
Anything that's in both locations and modified at the destination after an initial transfer (unless OverwriteMode is set to
NEVER
). -
The number of items that DataSync expects to delete (if PreserveDeletedFiles is set to
REMOVE
).
-
-
If
TranserMode
is set toALL
- The calculation is based only on the items that DataSync finds at the source location.
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 actually deletes 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 actually skips during your transfer.
Type: Long
- FilesTransferred
-
The number of files, objects, and directories that DataSync actually transfers 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 thanEstimatedFilesToTransfer
. 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 actually verifies 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 option before calling StartTaskExecution.
You also can override your task options for each task execution. For example, you might want to adjust the
LogLevel
for an individual execution.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 | CANCELLING | LAUNCHING | PREPARING | TRANSFERRING | VERIFYING | SUCCESS | ERROR
- TaskExecutionArn
-
The ARN of the task execution that you wanted information about.
TaskExecutionArn
is hierarchical and includesTaskArn
for the task that was executed.For example, a
TaskExecution
value with the ARNarn:aws:datasync:us-east-1:111222333444:task/task-0208075f79cedf4a2/execution/exec-08ef1e88ec491019b
executed the task with the ARNarn: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: