Description
The ftpRequest and sftpRequest methods allow you to access and run a series of commands against a remote server using the FTP protocol. Commands are executed sequentially against the server.
The response contains a log of the commands and responses as they are performed, a list containing details of all files downloaded in the session, a list containing details of all files in the current directory, and a list containing details of all files uploaded in the session.
This method includes several commands which are able to interact with the API Server's filestore. In these situations the filestore is treated as a "local" directory.
Parameters
| Name | Type | Description |
|---|---|---|
| host | String, required | The FTP host to connect to |
| port | Integer, optional | The port. Default: 21 for FTP, 22 for SFTP |
| user | String, required | The username for the FTP server |
| password | String, required | The password |
| tls | Boolean, optional | Default: false. If true the client will attempt to negotiate an FTPS connection with the server |
| implicit | Boolean, optional | Default: false. true to enable SSL session reuse |
| passive | Boolean, optional | Default: false. If true it will place the client in passive mode |
| minport | Integer, optional | Use minport and maxport to restrict the local ports used for active FTP connections |
| maxport | Integer, optional | |
| connectTimeoutMillis | Integer, optional | An optional connection timeout in milliseconds |
| dataTimeoutMillis | Integer, optional | An optional data timeout in milliseconds |
| commands | Array, optional | An array of commands, see below |
Supported Commands
Commands are supplied to this method as an array of objects.
The first property of each object is always "cmd".
The second property is the "args" array.
Several commands support the "opts" array "ignoreErrors".
See the sample below for an example request showing various commands in use.
| Command | Description |
|---|---|
| quit | Stops the processing of further commands and disconnects from the server |
| exit | Same as quit |
| pwd | Print current working directory |
| cd | Change working directory to the remote path specified in the first argument |
| ls | List the contents of the current working directory or files specified by the remote path in the first argument |
| dir | Same as ls |
| mv | Move/rename the file specified in the first argument to the file specified in the second argument |
| rename | Same as mv |
| rm | Delete the file specified in the first argument. Also accepts the option "ignoreErrors" so that the command stack will continue even if the command fails |
| rmdir | Delete the directory specified in the first argument. Also accepts the option "ignoreErrors" so that the command stack will continue even if the command fails |
| mkdir | Create the directory specified in the first argument. Also accepts the option "ignoreErrors" so that the command stack will continue even if the command fails |
| get | Get the remote file specified by the first argument and store it in the local location specified by the second argument. The second argument can be a local filesystem path, the word "filestore", or a filestore id. If it is an id the existing file will be updated |
| getUnique | Get the remote file specified by the first argument and store it in the local location specified by the second argument with a unique name. If the second the second argument is the word "filestore" or a filestore id, the command will behave in the same manner as a normal get |
| put | Put the local file specified by the first argument and store it in the remote location specified by the second argument. The first argument can be a local filesystem path or a filestore id |
| putUnique | Put the local file specified by the first argument and store it in the remote location specified by the second argument with a unique name. The first argument can be a local filesystem path or a filestore id |
| stat | Returns the status of the remote file specified by the first argument |
Additional SFTP Commands
| Command | Description |
|---|---|
| df | Return information on the current remote file system or another remote file system specified by the path in the first argument |
| version | Returns the SFTP version on the remote server |
Example Request
In this example request the directory is changed to /example, all of the text files in that directory are listed, all of the text files are copied to the filestore, a new directory called "test" is created in the example directory, a file is retrieved from the filestore and added to the test directory, the same file is retrieved again and stored in the test directory with a unique name (so we end up with two copies of the same file).
{
"id": 1,
"method": "ftpRequest",
"params": {
"host": "someserver",
"port":"21",
"user":"youruser",
"password":"yourpassword",
"tls":false,
"passive":false,
"minport":6000,
"maxport":6100,
"commands":[
{"cmd":"pwd"},
{"cmd":"cd", "args":["./example"]},
{"cmd":"ls", "args":["./*.txt"]},
{"cmd":"get", "args":["./*.txt", "filestore"]},
{"cmd":"mkdir", "args":["test"], "opts":["ignoreErrors"]},
{"cmd":"put", "args":["1e79f237-6ed1-4e0f-8ed0-5e175e13e1f1","test"]},
{"cmd":"putUnique", "args":["1e79f237-6ed1-4e0f-8ed0-5e175e13e1f1","test"]}
]
},
"jsonrpc": "2.0"
}
Example Response
{
"id": 1,
"result": {
"result": {
"putList": [
{
"path": "/home/youruser/example/test/text1.txt",
"lastUpdated": "2016-07-21T12:56Z",
"filename": "text1.txt",
"type": "text/plain",
"size": 0
},
{
"path": "/home/youruser/example/test/LXCMQ3_text1.txt",
"lastUpdated": "2016-07-21T12:56Z",
"filename": "LXCMQ3_text1.txt",
"type": "text/plain",
"size": 0
}
],
"getList": [
{
"id": "bb2386e3-01d9-4551-a409-8924aef496a6",
"created": "2016-07-21T11:55Z",
"path": "http://127.0.0.1:5706/filestore/http/file/bb2386e3-01d9-4551-a409-8924aef496a6",
"lastUpdated": "2016-07-21T11:55Z",
"filename": "text.txt",
"type": "text/plain",
"size": 39
},
{
"id": "aa8e331d-2059-4246-abbb-6c20c6f20e95",
"created": "2016-07-21T11:55Z",
"path": "http://127.0.0.1:5706/filestore/http/file/aa8e331d-2059-4246-abbb-6c20c6f20e95",
"lastUpdated": "2016-07-21T11:55Z",
"filename": "text1.txt",
"type": "text/plain",
"size": 39
},
{
"id": "4e4a063b-6a19-4773-a5b7-79602eed3c8e",
"created": "2016-07-21T11:55Z",
"path": "http://127.0.0.1:5706/filestore/http/file/4e4a063b-6a19-4773-a5b7-79602eed3c8e",
"lastUpdated": "2016-07-21T11:55Z",
"filename": "text2.txt",
"type": "text/plain",
"size": 39
}
],
"log": [
"connecting to GI00351a",
"220 (vsFTPd 3.0.2)\r\n",
"230 Login successful.\r\n",
"ftp> pwd",
"/home/youruser",
"ftp> cd ./example",
"250 Directory successfully changed.\r\n",
"ftp> ls ./*.txt",
"-rw-rw-r-- 1 1000 1000 0 2016-07-04 17:02 UTC text.txt",
"-rw-rw-r-- 1 1000 1000 0 2016-07-04 17:02 UTC text1.txt",
"-rw-rw-r-- 1 1000 1000 0 2016-07-04 17:02 UTC text2.txt",
"226 Directory send OK.\r\n",
"ftp> get ./*.txt filestore",
"Geting files with wildcard",
"Geting regular file ./text.txt",
"destination is the filestore",
"226 Transfer complete.\r\n",
"File stored with id: bb2386e3-01d9-4551-a409-8924aef496a6",
"Geting regular file ./text1.txt",
"destination is the filestore",
"226 Transfer complete.\r\n",
"File stored with id: aa8e331d-2059-4246-abbb-6c20c6f20e95",
"Geting regular file ./text2.txt",
"destination is the filestore",
"226 Transfer complete.\r\n",
"File stored with id: 4e4a063b-6a19-4773-a5b7-79602eed3c8e",
"ftp> mkdir test",
"257 \"/home/daves/example/test\" created\r\n",
"ftp> put 1e79f237-6ed1-4e0f-8ed0-5e175e13e1f1 test",
"destination is test/text1.txt",
"226 Transfer complete.\r\n",
"ftp> putUnique 1e79f237-6ed1-4e0f-8ed0-5e175e13e1f1 test",
"requested destination is test/text1.txt making unique",
"destination is test/LXCMQ3_text1.txt",
"226 Transfer complete.\r\n",
"closing connection"
]
}
},
"jsonrpc": "2.0",
"_transport_": {
"statusCode": 200,
"message": "OK"
}
}
Share this page
