API reference
Protocol Documentation
Table of Contents
APIVersionRequest
An empty request that gets the API version
APIVersionResponse
Returns a list of all versions of the API that the transfer binary supports.
Field | Type | Label | Description |
supportedVersions | string | repeated |
Supported versions of the API
|
AsperaInfo
Information about the Aspera transfer binary
Field | Type | Label | Description |
asperaBinary | string | |
Name of IBM Aspera binary (ascp)
|
asperaVersion | string | |
Version number of the IBM Aspera binary
|
operatingSystem | string | |
User's operating system
|
error | Error | |
Error that is returned
|
Assets
Assets for the transfer
Field | Type | Label | Description |
destination_root_id | string | |
File ID of the destination root directory. Required if using bearer token authorization for the
destination node.
|
source_root_id | string | |
File ID of the source root directory
|
destination_root | string | |
Destination root directory
|
source_root | string | |
Source root directory
|
paths | Path | repeated |
Array of paths
|
BasicRetryStrategy
When a transfer fails, a simple strategy to retry the transfer until it completes
Field | Type | Label | Description |
maxCount | int64 | |
Maximum number of times to retry the transfer
|
retryInterval | int64 | |
Interval to wait before retrying the transfer
|
Chunk
Information about data packets
Field | Type | Label | Description |
contents | bytes | |
Byte array sent in streaming request and returned in response (both send and receive)
|
Compression
Compression object containing a string. Compresses file data inline.
Allowable values: none, zlib, lz4. (Default: lz4). If set to zlib, the compression hint can be used to set the
compression level.
Field | Type | Label | Description |
method | string | |
The method for compressing file data. Allowable values: none, zlib, lz4. (Default: lz4).
If set to zlib, the compression hint can be used to set the compression level.
|
hint | int32 | |
Compress file data to the specified level when the compression method is set to an option
that accepts compression level settings (currently only zlib). A lower value results in less,
but faster, data compression (0 = no compression). A higher value results in greater, slower
compression.
Valid values are "-1" to "9", where "-1" is "balanced". (Default:
"-1")
|
Error
Error message in response
Field | Type | Label | Description |
code | int32 | |
Error code
|
description | string | |
Description of error
|
ExponentialBackoffRetryStrategy
When a transfer fails, the exponential strategy for waiting and retrying. The wait time grows exponentially
with each retry attempt.
Field | Type | Label | Description |
maxAttempts | int64 | |
Maximum number of times to wait and retry before failing the transfer
|
multiplier | int64 | |
The exponential multiplier for the wait time. If < 1, default is 2.
|
initialDelay | int64 | |
Length of the initial wait time before retrying the transfer.
|
maxDelay | int64 | |
Maximum duration of wait time before retrying the transfer. If <= zero, no maximum is enforced.
|
FASPProxy
Access parameters for the Proxy that coordinates communications between the remote server and the (local)
client.
Field | Type | Label | Description |
url | string | |
URL of proxy server
|
username | string | |
Username for the proxy user
|
password | string | |
Password for the proxy user
|
Returned information about the transfer
Field | Type | Label | Description |
fileId | string | |
File ID
|
path | string | |
Path for the file transfer
|
startTimeUsec | int64 | |
Transfer start time, in microseconds
|
elapsedUsec | int64 | |
Total time elapsed during the transfer, in microseconds
|
status | string | |
Status of the transfer
|
errorCode | int64 | |
Error code
|
errorDescription | string | |
Description of the error
|
size | int64 | |
Transfer size (MB)
|
fileType | string | |
Type of file that was transferred
|
fileChecksumType | string | |
Hash of the file checksum.
Allowable values: sha-512,sha-384,sha-256,sha1,md5.
(Default: none)
|
checksum | string | |
Hash from fileChecksumType
|
startByte | int64 | |
Offset where file is written
|
bytesWritten | int64 | |
Total bytes written at the destination
|
bytesContiguous | int64 | |
From startByte, how many contiguous bytes have been written
|
sessionId | string | |
Unique ID that FASP assigns to a transfer session
|
faspFileArgIndex | int64 | |
Command line argument index that specified this file (if argument was a directory,
many files can have the same FaspFileArgIndex). In persistent mode, the argument is
constantly increasing.
|
Filesystem
Policies related to transfer assets
Field | Type | Label | Description |
create_dir | bool | |
Create a directory at the transfer destination
|
delete_before_transfer | bool | |
Before transfer, delete files that exist at the destination but not at the source.
The source and destination arguments must be directories that have matching names.
Objects on the destination that have the same name but different type or size as
objects on the source are not deleted.
|
exclude_newer_than | string | |
Exclude files (but not directories) that are newer than a specific time from the transfer,
based on when the file was last modified. Express in ISO 8601 format (for example,
2006-01-02T15:04:05Z) or as number of seconds elapsed since 00:00:00 UTC on 1 January 1970.
|
exclude_older_than | string | |
Exclude files (but not directories) that are older than a specific time from the transfer,
based on when the file was last modified. Express in ISO 8601 format (for example,
2006-01-02T15:04:05Z) or as number of seconds elapsed since 00:00:00 UTC on 1 January 1970.
|
move_after_transfer | string | |
Move source files under path the path after transfer success.
|
overwrite | string | |
Overwrite files at the destination with source files of the same name based on the policy:
- always – Always overwrite the file.
- never – Never overwrite the file. If the destination contains partial files that are older
or the same as the source files and resume is enabled, the partial files resume transfer.
Partial files with checksums or sizes that differ from the source files are not overwritten.
- diff – Overwrite the file if it is different from the source, depending on the compare method
(default is size). If the destination is object storage, diff has the same effect as always.
If resume is not enabled, partial files are overwritten if they are different from the source,
otherwise they are skipped. If resume is enabled, only partial files with different sizes or
checksums from the source are overwritten; otherwise, files resume.
- diff+older – Overwrite the file if it is older and different from the source, depending on
the compare method (default is size). If resume is not enabled, partial files are overwritten
if they are older and different from the source, otherwise they are skipped. If resume is enabled,
only partial files that are different and older than the source are overwritten, otherwise they
are resumed.
- older – Overwrite the file if its timestamp is older than the source timestamp.
If you set an overwrite policy of diff or diff+older, difference is determined by the value set
for resume_policy:
"none" - the source and destination files are always considered different and the destination
file is always overwritten
"attributes" - the source and destination files are compared based on file attributes
"sparse_checksum" - the source and destination files are compared based on sparse checksums,
(currently file size)
"full_checksum" - the source and destination files are compared based on full checksums
|
precalculate_job_size | bool | |
Restore the access time of the source file to the last access prior to transfer,
which the source considers an access.
|
preserve_access_time | bool | |
Preserve the time the file was last accessed (read or write access) on the source.
|
preserve_creation_time | bool | |
Preserve timestamp for when a file was created
|
preserve_modification_time | bool | |
Preserve the time the object was last modified (write access) on the source.
|
preserve_times | bool | |
|
remove_after_transfer | bool | |
Remove files at the source of the transfer after the transfer completes successfully
|
remove_empty_directories | bool | |
Remove empty subdirectories at the source of the transfer
|
resume_policy | string | |
If a transfer is interrupted or fails to finish, this policy directs the transfer
to resume without retransferring the files. Allowable values:
"none" – always re-transfer the entire file
"attributes" – compare file attributes and resume if they match, and re-transfer if they do not
"sparse_checksum" – compare file attributes and the sparse file checksums; resume if they match,
and
re-transfer if they do not
"full_checksum" – compare file attributes and the full file checksums; resume if they match, and
re-transfer
if they do not.
|
symlink_policy | string | |
The method for processing symbolic links. Allowable values:
follow, copy, copy+force, skip
|
checksum_type | string | |
Enable checksum reporting for transferred files by specifying the hash to use. Allowable values:
sha-512, sha-384, sha-256, sha1, md5. (Default: none)
|
src_base64 | string | |
The folder name below which the directory structure is preserved (base64 encoded)
|
inclusion_patterns | PathPattern | repeated |
Include files or directories from the transfer based on the specified pattern. Rules are
applied in the order in which they are encountered, from left to right. The following
symbols can be used in the pattern:
- * (asterisk) represents zero or more characters in a string, for example *.tmp matches
.tmp and abcde.tmp.
- ? (question mark) represents a single character, for example t?p matches tmp but not temp.
|
exclusion_patterns | PathPattern | repeated |
Exclude files or directories from the transfer based on the specified pattern. Rules are
applied in the order in which they are encountered, from left to right. The following
symbols can be used in the pattern:
- * (asterisk) represents zero or more characters in a string, for example *.tmp matches
.tmp and abcde.tmp.
- ? (question mark) represents a single character, for example t?p matches tmp but not temp.
|
apply_local_docroot | bool | |
Apply the local docroot. This option is used to avoid entering object storage access
credentials in the command line. Allowable values: true, false.
|
preserve_acls | string | |
Preserve access control lists. Allowable values: none, native, metafile.
|
preserve_remote_acls | string | |
Preserve remote access control lists. Allowable values: none, native, metafile
|
preserve_file_owner_uid | bool | |
Preserve the user ID for a file owner
|
preserve_file_owner_gid | bool | |
Preserve the group ID for a file owner
|
preserve_extended_attrs | string | |
Preserve the extended attributes. Allowable values: none, native, metafile
|
preserve_remote_extended_attrs | string | |
Preserve the extended attributes for a remote server. Allowable values: none, native, metafile
|
preserve_source_access_time | bool | |
Preserve the time logged for when the source file was accessed
|
remove_empty_source_dir | bool | |
Remove empty source subdirectories and remove the source directory itself, if empty
|
save_before_overwrite | bool | |
Rename the file instead of overwriting it. Allowable values: true, false.
|
skip_duplicate_check | bool | |
Don't check for duplicate files at the destination. Allowable values: true, false.
|
skip_special_files | bool | |
All assets other than files, directories and symbolic links are considered special.
A transfer will fail if the user attempts to transfer special assets.
If true, ascp skips special assets and proceeds with the transfer of all other assets.
|
HTTPFallback
Configuration for HTTP fallback
Field | Type | Label | Description |
port | int64 | |
Port used for HTTP fallback server
|
proxy | string | |
Proxy address and port. (Default: 80)
|
ICOSSpec
Configuration for IBM Cloud Object Storage
Field | Type | Label | Description |
api_key | string | |
API key for IBM Cloud Object Storage
|
bucket | string | |
CRN (cloud resource name) for the bucket
|
ibm_service_instance_id | string | |
Instance ID for the IBM service
|
ibm_service_endpoint | string | |
Endpoint for the IBM service
|
Initiation
Elements of transfer initiation
Field | Type | Label | Description |
ssh | SSHSpec | |
Parameters relating to SSH
|
icos | ICOSSpec | |
Parameters relating to IBM Cloud Object Storage
|
node_api | NodeAPISpec | |
Configuration parameters for a call to the Node API
|
InstanceInfo
Data about TransferD service instance
Field | Type | Label | Description |
managementPort | int64 | |
Port TransferD uses to run management messages
|
asperaInfo | AsperaInfo | repeated |
Information about the running IBM Aspera binaries
|
licenseInfo | LicenseInfo | |
Information about the IBM Aspera license
|
promiscuousMode | bool | |
Enable promiscuous mode for the transfer. If the transfer is started in promiscuous mode,
sessions are discoverable by any user. Allowable values: true, false.
|
InstanceInfoRequest
Requests data about TransferD service instance.
InstanceInfoResponse
Returns data about TransferD service instance.
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
info | InstanceInfo | |
Data about TransferD service instance
|
error | Error | |
Error that is returned
|
LicenseInfo
Information about the Aspera license
Field | Type | Label | Description |
maxRate | string | |
Maximum transfer rate enabled by the IBM Aspera license
|
accountNumber | string | |
IBM Aspera customer account number
|
licenseNumber | string | |
IBM Aspera license number
|
license | string | |
Contents of the IBM Aspera license
|
LockPersistentTransferRequest
Request to mark an existing persistent transfer as done
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests.
|
LockPersistentTransferResponse
Response from the request to mark an existing persistent transfer as done
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests.
|
error | Error | |
Error that is returned
|
MultiSession
MultiSession settings object. Specifies the configuration on how
the transfer fileset will be split so it is transferred in parallel
using multiple transfer processes.
Field | Type | Label | Description |
enable | bool | |
Enable using multisession mode.
|
number_of_sessions | int32 | |
Number of parallel processes to transfer the fileset.
|
hosts | MultiSessionHosts | |
Settings for using different remote hosts for the multiple
transfer processes.
|
file_splitting | MultiSessionFileSplitting | |
Settings for the minimum size required to partition a single file
across multiple transfer processes.
|
bandwidth | MultiSessionBandwidth | |
Settings for the minimum rate required to enable multisession.
|
MultiSessionBandwidth
Settings for the minimum rate required to enable multisession.
Field | Type | Label | Description |
bandwidth_kpbs_threshold | int32 | |
Minimum bandwidth rate in kilobits per second (kbps) required
to enable multisession.
|
MultiSessionFileSplitting
Settings for the minimum size required to partition a single file
across multiple transfer processes.
Field | Type | Label | Description |
size_kb_threshold | int32 | |
Minimum size in kilobytes (kb) required to partition a single file
across multiple transfer processes.
|
MultiSessionHosts
Settings for using different remote hosts for the multiple
transfer processes.
Field | Type | Label | Description |
usedns | bool | |
Use the different IP addresses associated with the specified
remoteHost hostname as destinations for the different transfer processes.
|
hosts | string | repeated |
If not using DNS, specify a list of hosts to use for the different
transfer processes.
|
Values for the Node API header. The Node API is used to initiate and manage Aspera transfers.
Field | Type | Label | Description |
key | string | |
Node API header key
|
value | string | |
Value for Node API header key
|
NodeAPISpec
Information for the call to the Node API, which initiates and manages Aspera transfers.
Field | Type | Label | Description |
url | string | |
URL for call to Node API
|
headers | NodeAPIHeaderSpec | repeated |
Headers for the call to the Node API
|
Path
Information about the transfer path
Field | Type | Label | Description |
source | string | |
Source path for the transfer
|
destination | string | |
Destination path for the transfer
|
PathPattern
Data pattern used in the transfer path
Field | Type | Label | Description |
pattern | string | |
Pattern, such as regex, used in the transfer path
|
PeerCheckRequest
Request for a peer check
Field | Type | Label | Description |
transferSpec | string | |
Configuration parameters for the request
|
PeerCheckResponse
Data returned from a peer check request
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
reachable | bool | |
Peer node is reachable. Allowable values: true, false
|
error | Error | |
Error data returned from the peer check
|
QueryTransferResponse
Data returned a transfer query
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UUID for the transfer returned from the initial transfer request, used for subsequent requests
|
title | string | |
User-assigned title for the transfer
|
transferType | TransferType | |
Transfer type
|
status | TransferStatus | |
Transfer status
|
error | Error | |
Error message
|
transferInfo | TransferInfo | |
Returned information about the transfer
|
message | string | |
Message string
|
ReadStreamRequest
Request to read data from the stream
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer returned from the initial transfer request.
Used for subsequent requests.
|
ReadStreamResponse
Data returned after reading data from the stream
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
path | string | |
Path where the stream is read
|
pathSize | int64 | |
Size of the file or path that is received as a stream
|
chunk | Chunk | |
Byte array sent in the stream
|
error | Error | |
Error that is returned
|
RegistrationFilter
Components for filtering specific events. A filter without any item is considered as a pass through filter
(accepting all the events).
Field | Type | Label | Description |
operator | RegistrationFilterOperator | |
Operator applying to this filter set used to compose registration filter items.
|
eventType | TransferEvent | repeated |
All transfer event types
|
transferId | string | repeated |
All UUIDs included in the transfer
|
cookie | string | repeated |
All cookies included in the transfer
|
tags64 | string | repeated |
All tags included in the transfer (base64 encoded)
|
direction | string | |
Direction of transfer, either send (upload) or receive (download)
|
cookieRegex | string | |
Regex match for cookie included in the transfer
|
transferType | TransferType | repeated |
A set of Transfer types
|
transferStatus | TransferStatus | repeated |
A set of Transfer status types
|
RegistrationRequest
Request to filter specific events
Field | Type | Label | Description |
transferId | string | repeated |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests.
|
filters | RegistrationFilter | repeated |
The RegistrationFilter objects, specifying which filter to apply on events to monitor.
The goal of filter is to narrow down the events monitoring to a subset of events.
Filter items can be composed using an operator (AND/OR, default is OR).
When multiple filters are registered, they are processed as composed with an OR operator.
|
RetryStrategy
RetryStrategy configures the components of the retry strategy.
SSHSpec
SSH Configuration
Field | Type | Label | Description |
ssh_port | int64 | |
TCP port that initiates the transfer session.
|
remote_password | string | |
Password for the remote user
|
remote_user | string | |
Remote user's username
|
ssh_private_key | string | |
Private key for SSH
|
ssh_private_key_path | string | |
Path to the private key for SSH
|
ssh_private_key_passphrase | string | |
Private key passphrase for SSH
|
ssh_fingerprint | string | |
Public SSH key of the server
|
Security
Security configuration
Field | Type | Label | Description |
content_protection_password | string | |
Password for encryption of transferred assets
|
remote_access_key | string | |
Access key for a remote server
|
token | string | |
Token to authenticate the transfer.
For details see the 'Authentication and authorization' section in the IBM Aspera High Speed
Transfer Server
admin guide.
|
cipher | string | |
Cipher algorithm to apply during the transfer. Valid values are:
aes-128, aes-192, aes-256, aes-128-cfb, aes-192-cfb, aes-256-cfb,
aes-128-gcm, aes-192-gcm, aes-256-gcm, none
|
Returned information about a transfer session. There can be multiple transfer sessions for each transfer.
Field | Type | Label | Description |
id | string | |
Unique ID that TransferD assigns to a transfer session
|
sessionId | string | |
Unique ID that FASP assigns to a transfer session
|
user | string | |
Remote transfer user
|
clientUser | string | |
Username of the user running the transfer client on the local machine
|
clientNodeId | string | |
ID of the node for the transfer client on the local machine
|
clientClusterId | string | |
If applicable, the ID of the cluster for high availability on the local machine
|
serverNodeId | string | |
Node ID of the remote transfer server
|
serverClusterId | string | |
If applicable, the ID of the cluster for high availability on the remote transfer server
|
clientIPAddress | string | |
IP address for the client on the local machine
|
serverIPAddress | string | |
IP address for the remote transfer server
|
port | int64 | |
UDP port used by FASP
|
tcpPort | int64 | |
TCP port used to initiate a connection with TransferD
|
status | string | |
Status of the transfer session. Allowable values: initiated, passed, skipped, failed.
|
startTimeUsec | int64 | |
Transfer start time, in microseconds
|
endTimeUsec | int64 | |
Transfer end time, in microseconds
|
elapsedUsec | int64 | |
Total time elapsed during the transfer, in microseconds
|
bytesTransferred | int64 | |
Total bytes transferred
|
bytesWritten | int64 | |
Total bytes written at the destination
|
bytesLost | int64 | |
Total bytes lost during the transfer
|
filesCompleted | int64 | |
Total number of files that transferred successfully to the destination
|
filesFailed | int64 | |
Total number of files that failed to transfer successfully
|
filesSkipped | int64 | |
Total number of files skipped during the transfer session
|
directoriesCompleted | int64 | |
Total number of directories that transferred completely
|
targetRateKbps | int64 | |
Target transfer rate (Kbps)
|
minRateKbps | int64 | |
Minimum transfer rate (Kbps)
|
calcRateKbps | int64 | |
Calculated transfer rate (Kbps)
|
networkDelayUsec | int64 | |
Network delay (microseconds)
|
errorCode | int64 | |
Error code returned for a failed transfer of files or folders
|
errorDesc | string | |
Description of the error for a failed transfer of files or folders
|
manifestFilePath | string | |
Path to the manifest file
|
sourcePathsScanExcluded | int64 | |
Number of source paths excluded from the filesystem scan
|
sourcePathsScanIrregular | int64 | |
Number of irregular source paths found in the filesystem scan
|
sourcePathsScanFailed | int64 | |
Number of source paths in a failed filesystem scan
|
sourcePathsScanAttempted | int64 | |
Number of source paths in a filesystem scan that was initiated
|
transfersSkipped | int64 | |
Total number of transfers skipped, because, for example, the file already exists
at the destination.
|
transfersPassed | int64 | |
Total number of successful transfers
|
transfersFailed | int64 | |
Total number of transfers with errors
|
transfersAttempted | int64 | |
Total number of transfers initiated
|
cookie | string | |
All cookies included in the transfer
|
direction | string | |
Direction of transfer, either send (upload) or receive (download)
|
fileChecksumType | string | |
Hash of the file checksum.
Allowable values: HASH: sha-512,sha-384,sha-256,sha1,md5.
(Default: none)
|
operation | string | |
Indicates a transfer or just a bandwidth measurement. Allowable values: Transfer, BWMeasurement
|
tags | string | |
Metatags in JSON format specified by --tags
|
argTransfersAttempted | int64 | |
Total number of transfers initiated, where the data is provided as an argument
|
argTransfersPassed | int64 | |
Number of successful transfers, where the data is provided as an argument
|
argTransfersSkipped | int64 | |
Number of skipped transfers, where the data is provided as an argument
|
argTransfersFailed | int64 | |
Number of failed transfers, where the data is provided as an argument
|
encryption | string | |
If yes, use encryption.
|
adaptive | string | |
Transfer policy. Allowable values: Adaptive, Fixed, High
|
remote | string | |
If Yes, this process is acting as the server. If No, this process is acting as the client.
|
destination | string | |
Destination path for files being transferred
|
priority | int64 | |
Transfer priority (1: high | 2: regular)
|
transferId | string | |
UUID for the transfer, returned from the initial transfer request. Used for subsequent requests.
|
rateCap | int64 | |
Maximum rate for transfers, in kilobits per second
|
minRateCap | int64 | |
Minimum target rate for transfers, in kilobits per second
|
policyCap | string | |
Transfer policy that is allowed
|
rateLock | string | |
If yes, lock the target transfer rate to the default value set on the server. If no,
changing the target rate is allowed.
|
minRateLock | string | |
If no, changing the minimum transfer rate--set on the server--is allowed.
|
policyLock | string | |
If no, changing the transfer policy (priority)--set on the server--is allowed.
|
serverHostname | string | |
Hostname for the transfer server
|
remoteAddress | string | |
IP address for the remote transfer server
|
cipher | string | |
Cipher for content protection
|
resumePolicy | string | |
Policy for resuming a transfer after the transfer is paused
|
createPolicy | int64 | |
Policy for creating the transfer
|
manifestPolicy | string | |
Policy for application settings in TransferD
|
precalc | string | |
Policy for precalculating job size
|
overwritePolicy | string | |
Overwrite files at the destination with source files of the same name based on the policy:
- always – Always overwrite the file.
- never – Never overwrite the file. If the destination contains partial files that are older
or the same as the source files and resume is enabled, the partial files resume transfer.
Partial files with checksums or sizes that differ from the source files are not overwritten.
- diff – Overwrite the file if it is different from the source, depending on the compare method
(default is size). If the destination is object storage, diff has the same effect as always.
If resume is not enabled, partial files are overwritten if they are different from the source,
otherwise they are skipped. If resume is enabled, only partial files with different sizes or
checksums from the source are overwritten; otherwise, files resume.
- diff+older – Overwrite the file if it is older and different from the source, depending on
the compare method (default is size). If resume is not enabled, partial files are overwritten
if they are older and different from the source, otherwise they are skipped. If resume is enabled,
only partial files that are different and older than the source are overwritten, otherwise they
are resumed.
- older – Overwrite the file if its timestamp is older than the source timestamp.
If you set an overwrite policy of diff or diff+older, difference is determined by the value set
for resume_policy:
"none" - the source and destination files are always considered different and the destination
file is always overwritten
"attributes" - the source and destination files are compared based on file attributes
"sparse_checksum" - the source and destination files are compared based on sparse checksums,
(currently file size)
"full_checksum" - the source and destination files are compared based on full checksums
|
rttAutocorrect | string | |
Round trip time autocorrection
|
timePolicy | int64 | |
Total time allowed for the transfer
|
manifestInprogress | string | |
Suffix of the manifest file while the transfer is running
|
filesEncrypt | string | |
Specifies that the files are encrypted with user supplied password. Allowable values: yes, no.
|
filesDecrypt | string | |
Specifies that the files are decrypted with user supplied password. Allowable values: yes, no.
|
datagramSize | int64 | |
Sets the datagram size to be used by the sender
|
vLinkVersion | int64 | |
Version of the aggregate bandwidth caps applied to transfer sessions
|
peerVLinkVersion | int64 | |
At the peer IP address, version of the aggregate bandwidth caps applied to transfer sessions
|
vLinkLocalEnabled | string | |
Vlkink is enabled on the local machine
|
vLinkRemoteEnabled | string | |
Vlkink is enabled on the remote transfer server
|
readBlockSize | int64 | |
The size of data to be read from the disk on the sender
|
writeBlockSize | int64 | |
The size of data to be written to the disk on the receiver
|
clusterNumNodes | int64 | |
Number of sessions used in a multi-session transfer
|
clusterNodeId | int64 | |
The session index number in a multi-session transfer
|
moveRange | string | |
Size of data to be transferred when a range transfer is specified
|
keepalive | string | |
The session is running in persistent session mode
|
testLogin | string | |
The session is attempting a login, only, without data transfer
|
useProxy | string | |
Use the forward proxy for Aspera file transfers
|
rateControlAlgorithm | string | |
Algorithm to adapt the transmission rate in response to varying conditions
|
pmtu | int64 | |
Path maximum transmission unit (MTU) value
|
preTransferFiles | int64 | |
Total number of files discovered at the source that can potentially be transferred
|
preTransferBytes | int64 | |
Total number of bytes discovered at the source that can potentially be transferred
|
preTransferDirs | int64 | |
Total number of directories discovered at the source that can potentially be transferred
|
preTransferSpecial | int64 | |
Total number of special files discovered at the source that can potentially be transferred
|
sourcePathsScanCompleted | int64 | |
Total number of source paths that are scanned
|
argScansAttempted | int64 | |
Source arguments handled
|
argScansCompleted | int64 | |
Source arguments completed
|
argFaspFileArgIndex | int64 | |
Command line argument index that specified this file (if argument was a directory,
many files can have the same FaspFileArgIndex). In persistent mode, the argument
is constantly increasing.
|
dirCreatesAttempted | int64 | |
Total number of attempts to create a destination directory.
|
dirCreatesFailed | int64 | |
Total number of attempts to create a destination directory that failed.
|
dirCreatesPassed | int64 | |
Total number of attempts to create a directory where the destination directory already
existed or was successfully created
|
dirScansCompleted | int64 | |
Total source directory scans completed
|
StartTransferResponse
Data returned from the transfer request
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UUID for the transfer returned from the initial transfer request, used for subsequent requests
|
title | string | |
User-assigned title for the transfer
|
transferType | TransferType | |
Type of transfer
|
status | TransferStatus | |
Transfer status
|
error | Error | |
Error message for the transfer, if any
|
StopInfo
Query to find out if the transfer is stopped
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer returned from the initial transfer request, used for subsequent requests
|
stopped | bool | |
Transfer is stopped.
|
error | Error | |
Error that is returned
|
StopTransferRequest
Request to stop the transfer
Field | Type | Label | Description |
transferId | string | repeated |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests.
|
delay | int64 | |
Length of time to delay before stopping the transfer
|
StopTransferResponse
Data returned from the request to stop the transfer
Field | Type | Label | Description |
apiVersion | string | |
API version
|
stopResult | StopInfo | repeated |
Data about the results of the StopTransferRequest
|
Streaming
Configuration for streaming
Field | Type | Label | Description |
chunk_size | int64 | |
Size of the byte array sent in streaming request and returned in response for
both send and receive.
|
local_memory | int64 | |
Amount of memory available on the local machine
|
remote_memory | int64 | |
Amount of memory available on the remote server
|
sparse_file | bool | |
Do not use sparse_file
|
compression | Compression | |
Compression object containing a string. Compress file data inline.
Allowable values: none, zlib, lz4. (Default: lz4). If set to zlib, the compression hint
can be used to set the compression level.
|
Tracking
Tracking parameters
Field | Type | Label | Description |
cookie | string | |
All cookies included in the transfer
|
tags | string | |
All tags included in the transfer
|
tags64 | string | |
All tags included in the transfer (base64 encoded)
|
TransferConfig
Configuration elements for the transfer
Field | Type | Label | Description |
retry | RetryStrategy | |
Strategy that is defined for retrying the transfer. Optional. No retry if not set.
|
license | string | |
Contents of a custom license file. Optional. License in the binary path is used if not set.
|
localLog | string | |
Local log directory path. Optional.
|
remoteLog | string | |
Remote log directory path. Optional.
|
logLevel | sfixed32 | |
Level of detail to return in the log. Allowable values: 0 (minimal log data),
1, 2 (most detailed log data).
|
asperaConf | string | |
Path to the aspera.conf configuration file. Optional. Configuration file in the etc path is used if not
set.
|
TransferInfo
Returned information about the transfer
Field | Type | Label | Description |
averageRateKbps | int64 | |
Average rate for the transfer, in kilobits per second
|
bytesLost | int64 | |
Total bytes lost during the transfer
|
bytesTransferred | int64 | |
Total bytes transferred
|
bytesWritten | int64 | |
Total bytes written at the destination
|
directoriesCompleted | int64 | |
Total directories that transferred completely
|
startTimeUsec | int64 | |
Transfer start time, in microseconds
|
elapsedUsec | int64 | |
Total time elapsed during the transfer, in microseconds
|
endTimeUsec | int64 | |
Transfer end time, in microseconds
|
errorCode | string | |
Error code for the transfer
|
errorDescription | string | |
Description of error
|
filesCompleted | int64 | |
Number of files that arrived successfully at the destination.
|
targetRateKbps | int64 | |
Target transfer rate (in Kbps)
|
minRateKbps | int64 | |
Minimum transfer rate (in Kbps)
|
argTransfersAttempted | int64 | |
Total number of transfers initiated, where the data is provided as an argument.
For example, for an attempted transfer of a folder that contains multiple files, the
value is 1.
|
argTransfersPassed | int64 | |
Total number of successful transfers, where the data is provided as an argument.
For example, for a given transferred folder that contains multiple files, the
value is 1.
|
argTransfersSkipped | int64 | |
Total number of skipped transfers, where the data is provided as an argument.
For example, for a skipped transfer of a folder that contains multiple files, the
value is 1.
|
argTransfersFailed | int64 | |
Number of failed transfers
|
fileChecksumType | string | |
Hash of the file checksum.
Allowable values: HASH: sha-512,sha-384,sha-256,sha1,md5.
(Default: none)
|
cookie | string | |
Application-specified string
|
direction | string | |
Direction of transfer, either send (upload) or receive (download)
|
operation | string | |
Indicates a transfer or a bandwidth measurement. Allowable values: Transfer, BWMeasurement
|
tags64 | string | |
All tags to include in the transfer (base64 encoded)
|
TransferInfoRequest
Request for information about the transfer
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer returned from the initial transfer request. Used for subsequent requests.
|
TransferModificationRequest
Request to modify the transfer
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests
|
transferSpec | string | |
Defines the configuration parameters for the transfer
|
TransferModificationResponse
Data returned from the request to modify the transfer
Field | Type | Label | Description |
apiVersion | string | |
API version
|
transferId | string | |
UUID for the transfer returned from the initial transfer request.
Used for subsequent requests.
|
status | TransferStatus | |
Status of the transfer
|
error | Error | |
Error message, if any
|
TransferPath
Information about transfer paths
Field | Type | Label | Description |
source | string | |
Source path for files being transferred
|
destination | string | |
Destination path for files being transferred
|
range | TransferRange | |
Defines the range for a stream
|
TransferPathRequest
Request for information about the transfer path
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer, returned from the initial transfer request.
Used for subsequent requests.
|
transferPath | TransferPath | repeated |
Information about transfer paths, both source and destination
|
TransferPathResponse
Data returned from the request for information about the transfer path
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UUID for the transfer returned from the initial transfer request, used for subsequent requests
|
error | Error | |
Error that is returned
|
TransferRange
Transfer range in a file or stream request
Field | Type | Label | Description |
offset | int64 | |
offset for the stream
|
length | int64 | |
length of the stream
|
TransferRequest
Parameters to submit to the transfer server
Field | Type | Label | Description |
transferType | TransferType | |
Specify the type of transfer. Allowable values: UNKNOWN_TRANSFER_TYPE, FILE_REGULAR,
FILE_PERSISTENT, FILE_TO_STREAM_DOWNLOAD, STREAM_TO_FILE_UPLOAD
|
config | TransferConfig | |
Policies and permissions for the transfer
|
transferSpec | string | |
Full configuration details for the transfer
|
TransferResponse
Data returned from the transfer request
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UID for the transfer returned from the initial transfer request. Used for subsequent requests
|
title | string | |
User-assigned title of the transfer
|
transferType | TransferType | |
Transfer type
|
status | TransferStatus | |
Status of the transfer
|
error | Error | |
Error message for the transer
|
transferEvent | TransferEvent | |
Transfer event type
|
transferInfo | TransferInfo | |
Returned information about the transfer
|
message | string | |
Message string
|
sessionInfo | SessionTransferInformation | |
Information about a transfer session. There can be more than one transfer sessions
for a given transfer.
|
fileInfo | FileTransferInformation | |
Information about the file transfer
|
TransferSpecV1
The transfer specification (transferSpec) contains all components needed to initiate, monitor, and control
transfers.
Field | Type | Label | Description |
cipher | string | |
Cipher for content protection
|
content_protection | string | |
Enable client-side content protection (encryption-at-rest).
For uploads, set to encrypt to transfer encrypted files and store them on the server with the extension
".aspera-env".
To download and decrypt encrypted files, set to decrypt.
content_protection_password must be specified if this option is set.
Values are : encrypt and decrypt
|
content_protection_password | string | |
Password for encryption of transferred assets
|
cookie | string | |
Application-specified string
|
create_dir | bool | |
Create a directory at the transfer destination
|
delete_before_transfer | bool | |
Before transfer, delete files that exist at the destination but not at the source.
The source and destination arguments must be directories that have matching names.
Objects on the destination that have the same name but different type or size as
objects on the source are not deleted.
|
delete_source | bool | |
Delete the source directory after the assets are transferred
|
destination_root_id | string | |
Root ID at the destination
|
direction | string | |
Directon of transfer, whether send (upload) or receive (download)
|
exclude_newer_than | string | |
Exclude files (but not directories) that are newer than a specific time from the transfer,
based on when the file was last modified. Express in ISO 8601 format (for example,
2006-01-02T15:04:05Z) or as number of seconds elapsed since 00:00:00 UTC on 1 January 1970.
|
exclude_older_than | string | |
Exclude files (but not directories) that are older than a specific time from the transfer,
based on when the file was last modified. Express in ISO 8601 format (for example,
2006-01-02T15:04:05Z) or as number of seconds elapsed since 00:00:00 UTC on 1 January 1970.
|
fasp_port | int64 | |
Port used for the transfer. (Default: 33001)
|
http_fallback | bool | |
Parameters to configure HTTP fallback
|
http_fallback_port | int64 | |
Port used for HTTP fallback server
|
https_fallback_port | int64 | |
Port used for HTTPS fallback
|
move_after_transfer | string | |
Move source files under path the path after transfer success.
|
multi_session | int64 | |
Split files across multiple ascp sessions to enable faster transfers.
Allowable values: true, false.
|
multi_session_threshold | int64 | |
Split files across multiple ascp sessions if their size is greater than or equal
to the specified value. Default: 0 (no files are split).
|
overwrite | string | |
Overwrite files at the destination with source files of the same name based on the policy:
- always – Always overwrite the file.
- never – Never overwrite the file. If the destination contains partial files that are older
or the same as the source files and resume is enabled, the partial files resume transfer.
Partial files with checksums or sizes that differ from the source files are not overwritten.
- diff – Overwrite the file if it is different from the source, depending on the compare method
(default is size). If the destination is object storage, diff has the same effect as always.
If resume is not enabled, partial files are overwritten if they are different from the source,
otherwise they are skipped. If resume is enabled, only partial files with different sizes or
checksums from the source are overwritten; otherwise, files resume.
- diff+older – Overwrite the file if it is older and different from the source, depending on
the compare method (default is size). If resume is not enabled, partial files are overwritten
if they are older and different from the source, otherwise they are skipped. If resume is enabled,
only partial files that are different and older than the source are overwritten, otherwise they
are resumed.
- older – Overwrite the file if its timestamp is older than the source timestamp.
If you set an overwrite policy of diff or diff+older, difference is determined by the value set
for resume_policy:
"none" - the source and destination files are always considered different and the destination
file is always overwritten
"attributes" - the source and destination files are compared based on file attributes
"sparse_checksum" - the source and destination files are compared based on sparse checksums,
(currently file size)
"full_checksum" - the source and destination files are compared based on full checksums
|
paths | Path | repeated |
Path for the transfer
|
precalculate_job_size | bool | |
Restore the access time of the source file to the last access prior to transfer,
which the source considers an access.
|
preserve_access_time | bool | |
Preserve the time the file was last accessed (read or write access) on the source.
|
preserve_creation_time | bool | |
Preserve timestamp for when a file is created
|
preserve_modification_time | bool | |
Preserve the time the object was last modified (write access) on the source.
|
preserve_times | bool | |
Preserve file timestamps
|
rate_policy | string | |
The transfer rate policy to use when sharing bandwidth. Allowable values:
high - When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.
fair - (Default) Share bandwidth equally with other traffic.
low - Use only unused bandwidth.
fixed - Transfer at the target rate, regardless of the actual network capacity.
Do not share bandwidth. Aspera recommends that you do not use this setting except under special
circumstances, otherwise the destination storage can be damaged.
|
remote_access_key | string | |
Access key for the remote server
|
remote_host | string | |
Remote server used for the transfer
|
remote_password | string | |
Password for the remote user
|
remote_user | string | |
Remote user's username
|
remove_after_transfer | bool | |
Remove files at the source of the transfer after the transfer completes successfully
|
remove_empty_directories | bool | |
Remove empty subdirectories at the source of the transfer
|
resume_policy | string | |
If a transfer is interrupted or fails to finish, this policy directs the transfer
to resume without retransferring the files. Allowable values:
"none" – always re-transfer the entire file
"attributes" – compare file attributes and resume if they match, and re-transfer if they do not
"sparse_checksum" – compare file attributes and the sparse file checksums; resume if they match,
and
re-transfer if they do not
"full_checksum" – compare file attributes and the full file checksums; resume if they match, and
re-transfer
if they do not.
|
retry_duration | int64 | |
Total time committed to retrying the transfer
|
source_root_id | string | |
The file ID of the source root directory. Required if using bearer token authorization for the source
node.
|
ssh_port | int64 | |
TCP port that initiates the transfer session
|
ssh_private_key | string | |
Private key for SSH
|
ssh_private_key_path | string | |
Path to private key for SSH
|
ssh_private_key_passphrase | string | |
Private key passphrase for SSH
|
symlink_policy | string | |
The method for processing symbolic links.
Allowable values: follow, copy, copy+force, skip
|
tags | string | |
Tags to include in the transfer
|
tags64 | string | |
Tags to include in the transfer (base64 encoded)
|
target_rate_cap_kbps | int64 | |
Maximum target rate for incoming transfers, in kilobits per second.
|
target_rate_kbps | int64 | |
Ideal transfer rate, in kilobits per second. There is no default value.
|
title | string | |
Title of the transfer
|
token | string | |
Token to authenticate the transfer.
For details see the 'Authentication and authorization' section in the IBM Aspera High Speed
Transfer Server
admin guide.
|
use_ascp4 | bool | |
Deprecated. Do not use use_ascp4
|
fasp_proxy | FASPProxy | |
Proxy for communications between the remote server and the (local) client.
|
destination_root | string | |
Destination root directory
|
source_root | string | |
Source root directory
|
min_rate_cap_kbps | int64 | |
The highest minimum rate that an incoming transfer can request, in kilobits per second.
Client minimum rate requests that exceed the minimum rate cap are ignored. The default
value of unlimited applies no cap to the minimum rate. (Default: 0)
|
lock_rate_policy | bool | |
If true, lock the rate policy to the default value
Allowable values: true, false.
|
lock_target_rate_kbps | bool | |
If true, lock the target transfer rate to the default value set for target_rate_kbps.
If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
|
lock_min_rate_kbps | bool | |
If true, lock the minimum transfer rate to the value set for min_rate_kbps.
If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
|
src_base64 | string | |
The folder name below which the directory structure is preserved (base64 encoded)
|
icos | ICOSSpec | |
Configuration parameters for IBM Cloud Object Storage (ICOS)
|
node_api | NodeAPISpec | |
Configuration parameters for a call to the Node API
|
apply_local_docroot | bool | |
Apply the local docroot. This option is used to avoid entering object storage
access credentials in the command line. Allowable values: true, false.
|
preserve_acls | string | |
Preserve access control lists. Allowable values: none, native, metafile.
|
preserve_remote_acls | string | |
Preserve remote access control lists. Allowable values: none, native, metafile
|
preserve_file_owner_uid | bool | |
Preserve the user ID for a file owner
|
preserve_file_owner_gid | bool | |
Preserve the group ID for a file owner
|
preserve_extended_attrs | string | |
Preserve the extended attributes. Allowable values: none, native, metafile
|
preserve_remote_extended_attrs | string | |
Preserve the extended attributes for a remote server. Allowable values: none,
native, metafile
|
preserve_source_access_time | bool | |
Preserve the time logged for when the source file was accessed
|
remove_empty_source_dir | bool | |
Remove empty source subdirectories and remove the source directory itself, if empty
|
save_before_overwrite | bool | |
Rename the file instead of overwriting it. Allowable values: true, false.
|
skip_duplicate_check | bool | |
Don't check for duplicate files at the destination. Allowable values: true, false.
|
skip_special_files | bool | |
All assets other than files, directories and symbolic links are considered special.
A transfer will fail if the user attempts to transfer special assets.
If true, ascp skips special assets and proceeds with the transfer of all other assets.
|
Fields with deprecated option
TransferSpecV2
The transfer specification (transferSpec) contains all components needed to initiate, monitor, and control
transfers.
TransferSpecv2 allows you to construct a custom transfer specification. You only need to configure the modules
(such as
Security or Transport) and parameters that are essential for your transfers.
Field | Type | Label | Description |
session_initiation | Initiation | |
Parameters that define transfer initiation, including SSH
|
security | Security | |
Parameters that define security for the transfer
|
tracking | Tracking | |
Parameters that define asset tracking for the transfer, such as tags
|
file_system | Filesystem | |
Parameters that define the handling of files and directories being transferred
|
transport | Transport | |
Parameters that define rate policy and transfer rate
|
assets | Assets | |
Parameters that define source and location for the transfer
|
direction | string | |
Direction of the transfer, whether send (upload) or receive (download)
|
remote_host | string | |
Name of the remote server
|
title | string | |
Name assigned to the transfer
|
Transport
Values related to the transfer, including transfer policies
Field | Type | Label | Description |
fasp_port | int64 | |
Port used for the transfer. (Default: 33001)
|
http_fallback | HTTPFallback | |
Fields for configuring HTTP fallback in the transferSpec v2
|
fasp_proxy | FASPProxy | |
Fields for configuring the FASP proxy in the transferSpec v2. The FASP proxy coordinates
communications between the remote server and the (local) client.
|
streaming | Streaming | |
Fields for configuring streaming in the transferSpec v2.
|
multi_session | MultiSession | |
Split files across multiple ascp sessions to enable faster transfers.
Allowable values: true, false.
|
multi_session_threshold | int64 | |
Split files across multiple ascp sessions if their size is greater than or equal to the
specified value. Default: 0 (no files are split).
|
rate_policy | string | |
The transfer rate policy to use when sharing bandwidth. Allowable values:
high - When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.
fair - (Default) Share bandwidth equally with other traffic.
low - Use only unused bandwidth.
fixed - Transfer at the target rate, regardless of the actual network capacity.
Do not share bandwidth. Aspera recommends that you do not use this setting except under special
circumstances, otherwise the destination storage can be damaged.
|
lock_rate_policy | bool | |
If true, lock the rate policy to the default value
Allowable values: true, false.
|
target_rate_cap_kbps | int64 | |
Maximum target rate for incoming transfers, in kilobits per second.
|
target_rate_kbps | int64 | |
Ideal transfer rate, in kilobits per second. There is no default value.
|
min_rate_cap_kbps | int64 | |
The highest minimum rate that an incoming transfer can request, in kilobits per second.
Client minimum rate requests that exceed the minimum rate cap are ignored. The default
value of unlimited applies no cap to the minimum rate. (Default: unlimited)
|
min_rate_kbps | int64 | |
Minimum transfer rate (in Kbps)
|
lock_target_rate_kbps | bool | |
If true, lock the target transfer rate to the default value set for target_rate_kbps.
If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
|
lock_min_rate_kbps | bool | |
If true, lock the minimum transfer rate to the value set for min_rate_kbps.
If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
|
Fields with deprecated option
ValidationRequest
ValidationRequest submits the transfer specification (transferSpec) for validation and specifies a transfer
type.
Field | Type | Label | Description |
transferSpec | string | |
The transfer specification to be validated
|
transferType | TransferType | |
The type of transfer
|
ValidationResponse
ValidationResponse contains the API version, the version of the transfer spec validator which is used, a
boolean to indicate
if the validation is successful, and an error message, if any.
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
valid | bool | |
Transfer specification is valid. Allowable values: true, false.
|
validatorVersion | string | |
Version of transfer specification validator
|
unknownField | string | repeated |
Unkown field in the transfer specification
|
error | Error | |
Error that is returned
|
WriteStreamChunkRequest
Response to the request to add data packets to the stream
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer returned from the initial transfer request.
Used for subsequentrequests
|
path | string | |
Path where stream is written
|
range | TransferRange | |
Range for the stream
|
chunk | Chunk | |
Byte array sent in the stream
|
WriteStreamChunkResponse
Response to the request to write data to the stream
Field | Type | Label | Description |
apiVersion | string | |
API version
|
transferId | string | |
UUID for the transfer returned from the initial transfer request.
Used for subsequent requests.
|
error | Error | |
Error message, if any
|
WriteStreamRequest
Request to write data to the stream
Field | Type | Label | Description |
transferId | string | |
UUID for the transfer returned from the initial transfer request.
Used for subsequent requests.
|
path | string | |
Path to the stream
|
size | int64 | |
Stream size
|
chunk | Chunk | |
Byte array sent in the stream
|
WriteStreamResponse
Response to the request to write data to the stream
Field | Type | Label | Description |
apiVersion | string | |
Version of the API
|
transferId | string | |
UUID for the transfer returned from the initial transfer request, used for subsequent requests
|
error | Error | |
Error that is returned
|
RegistrationFilterOperator
Used to compose registration filter items.
Name | Number | Description |
OR | 0 |
Logical OR operator that returns the boolean value TRUE if either or both operands is TRUE and returns
FALSE otherwise
|
AND | 1 |
Logical AND operator that returns a value of TRUE if both its operands are TRUE, and FALSE otherwise
|
TransferEvent
Transfer events
Name | Number | Description |
UNKNOWN_EVENT | 0 |
Transfer event can't be identified
|
SESSION_START | 1 |
Transfer session started
|
SESSION_STOP | 2 |
Transfer session stopped
|
SESSION_ERROR | 3 |
Transfer session failed with an error
|
FILE_START | 4 |
File transfer started
|
FILE_STOP | 5 |
File transfer stopped
|
FILE_ERROR | 6 |
File transfer failed with an error
|
ARG_STOP | 7 |
ARG_STOP is a management message returned by FASP to indicate the completion
of a transfer path provided as an argument to the transfer binary.
|
PROGRESS | 8 |
Transfer in progress
|
CONNECTING | 9 |
Transfer is connecting
|
RATE_MODIFICATION | 10 |
Transfer rate modified during the transfer
|
FILE_SKIP | 11 |
One or more files skipped during the transfer session
|
BANDWIDTH_MEASUREMENT | 12 |
Bandwidth measurement assessed during the transfer
|
SESSION_CANCELED | 13 |
User canceled session
|
TransferStatus
TransferStatus statuses a transfer can hold.
Name | Number | Description |
UNKNOWN_STATUS | 0 |
Transfer status is unknown
|
QUEUED | 1 |
File or folder is queued for transfer
|
RUNNING | 2 |
Transfer is running at the time of the query
|
COMPLETED | 3 |
Transfer successfully completed
|
FAILED | 4 |
Transfer failed
|
CANCELED | 5 |
Transfer was canceled by the user
|
PAUSED | 6 |
Transfer was paused by the user
|
ORPHANED | 7 |
A file transferred without its parent folder
|
TransferType
TransferType describes the possible transfer types.
When a user requests a new transfer, she can specify the type of transfer in the transferSpec.
Name | Number | Description |
UNKNOWN_TRANSFER_TYPE | 0 |
Unknown transfer type
|
FILE_REGULAR | 1 |
File transfer using the paths you provide in the transferSpec
|
FILE_PERSISTENT | 2 |
File transfer where you provide the source and destination paths while the transfer is in progress
|
URL_STREAM_TO_STREAM | 3 |
Do not use URL_STREAM_TO_STREAM
|
FILE_TO_STREAM_DOWNLOAD | 4 |
Download a file as a stream at the destination. You must specify the size of the source file when
starting the streaming of every file.
Note: For this type of transfer, the supported values for the overwrite option are "always" or
"never" in the transferSpec: any value other than "always" and "never" is
defaulted to "never".
Resume option is not supported: any value for this option is defaulted to "none".
|
STREAM_TO_FILE_UPLOAD | 5 |
Upload a stream as a file at the destination. You must specify the total number of bytes to upload when
starting the streaming of every file.
Note: For this type of transfer, the supported values for the overwrite option are "always" or
"never" in the transferSpec: any value other than "always" and "never" is
defaulted to "never".
Resume option is not supported: any value for this option is defaulted to "none".
|
PERSISTENT_STREAM_UPLOAD | 6 |
Stream to file upload in a persistent session--meaning that you don't specify the stream size at
the beginning of the transfer--using the URI specified in the transferSpec.
|
ASYNC_SESSION | 7 |
Async transfer session using configuration section of the IBM Aspera Sync API
|
TransferService
Transfer service definition. This service enables users to start, manage and monitor transfers.
You can also get information about the transfer service settings and confirm the availability of
communication between the engine and a remote transfer server.
Method Name | Request Type | Response Type | Description |
Validate | ValidationRequest | ValidationResponse |
Validate accepts a transfer spec string and a transfer type, and returns the validation result.
|
StartTransfer | TransferRequest | StartTransferResponse |
StartTransfer starts a new transfer and returns the transfer information required to manage and monitor
the transfer.
This request doesn't close until the transfer is terminated or the request is canceled by the
client.
|
StartTransferWithMonitor | TransferRequest | TransferResponse stream |
StartTransferWithMonitor starts a new transfer and streams back the transfer events.
The request doesn't return immediately, as it continues streaming responses to the client until the
transfer is terminated or the request is canceled
by the client.
|
QueryTransfer | TransferInfoRequest | QueryTransferResponse |
QueryTransfer requests transfer data.
|
ModifyTransfer | TransferModificationRequest | TransferModificationResponse |
ModifyTransfer modifies an existing transfer.
|
AddTransferPaths | TransferPathRequest | TransferPathResponse |
AddTransferPaths can be used with persistent transfer to add paths to an existing transfer.
(type TransferType.FILE_PERSISTENT).
|
LockPersistentTransfer | LockPersistentTransferRequest | LockPersistentTransferResponse |
LockPersistentTransfer, used with persistent transfer, marks an existing persistent transfer as done.
Once the method is called, any subsequent call to AddTransferPaths results in an error.
(type TransferType.FILE_PERSISTENT).
|
StopTransfer | StopTransferRequest | StopTransferResponse |
StopTransfer stops a transfer.
|
MonitorTransfers | RegistrationRequest | TransferResponse stream |
MonitorTransfers monitors transfers matching the defined filters and streams back the transfer events.
The request doesn't return an immediate response because MonitorTransfers continues streaming
responses to the client until the client cancels the request.
|
GetAPIVersion | APIVersionRequest | APIVersionResponse |
GetAPIVersion gets the API version.
|
GetInfo | InstanceInfoRequest | InstanceInfoResponse |
GetInfo gets data about TransferD service instance.
|
IsPeerReachable | PeerCheckRequest | PeerCheckResponse |
IsPeerReachable confirms whether or not the peer endpoint is reachable.
|
WriteStreamChunk | WriteStreamChunkRequest stream | WriteStreamChunkResponse |
WriteStreamChunk writes chunks of streaming data for the specified in-progress
transfer of type PERSISTENT_STREAM_UPLOAD, at a specific offset.
When StopTransfer is called on the transfer, subsequent calls to this function will fail.
|
WriteStream | WriteStreamRequest stream | WriteStreamResponse |
WriteStream writes chunks of streaming data for the specified in-progress transfer of type
STREAM_TO_FILE_UPLOAD.
Once StopTransfer is called on the transfer, subsequent calls to this function will fail.
|
ReadStream | ReadStreamRequest | ReadStreamResponse stream |
ReadStream reads chunks of streaming data from a specified in-progress transfer of type
FILE_TO_STREAM_DOWNLOAD.
Once StopTransfer is called on this transfer, subsequent calls to this function will fail.
|
Scalar Value Types
.proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
double | | double | double | float | float64 | double | float | Float |
float | | float | float | float | float32 | float | float | Float |
int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to
have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to
have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than
regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than
regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |