跳至主要內容
文件
文件
Adaptive Planning
ai.sftp

ai.sftp

The article describes the ai.sftp namespace and the associated methods to create a client, perform basic client operations, upload and download files with the file Reader and Writer objects.
The ai.sftp namespace allows a user to upload and download files to an SFTP server. It also allows uploading and downloading encrypted files letting you encrypt and decrypt them with PGP.

Create a Client

ai.sftp.createClient
You can create an SFTP instance with the createClient() method and initiate all operations with the SFTP server. This function takes the name of the SFTP connection string configured for the script as a parameter and returns a client instance object.
Method
Parameters
Return type
Description
createClient(sftpConnection)
sftpConnection : String
Name of your SFTP Connection
Object
Creates an SFTP Client
Usage

const client = ai.sftp.createClient('mySftpConnectionSetting');

Basic Client Operations

You can perform the following operations on the client instance object returned from the ai.createClient method.
Method
Parameters
Return Type
Description
isConnected()
Boolean
Returns True if the SFTP client is connected; False otherwise.
disconnect()
Logs out and closes the client session with the server. Any further operations called on the client will result in an exception being thrown.
delete(fileName)
fileName : String Name of the file to be deleted
Deletes the specified file
rename (renameFrom, renameTo)
renameFrom : String
Original Name of the file
renameTo : String
New name of the file
Renames the specified file
createDirectory(directoryName)
Name: String
Relative path of the new directory
Creates a directory on the server.
changeDirectory(newLocation)
newLocation : String
Relative path of the new location on the server
String
Changes the current working directory on the server. This operation will return the current working directory
getCurrentDirectory()
String
Get the current working directory
getFileSizeBytes(fileName)
fileName : String File name for the file size fetched
Number
Returns the size of the specified file in bytes
listCurrentDirectory()
Collection
Returns a list of all files and directories in the current working directory.

Download a File

Use the following client methods to download files from the server.
downloadFile(fileName)
fileName: String
Name of the file to download
Object
Downloads the file and returns a reader to read through the file line by line.
downloadEncryptedFile(fileName, encryptionSettingName)
fileName : String
Relative path of the file to download
encryptionSettingName : String
Name of your encryption setting from the
Credentials
 area in Design Integrations.
Object
Downloads the file, decrypts it using the specified encryption setting and returns a reader to read through the file line by line.
downloadAndVerifyEncryptedFile(fileName, encryptionSettingName)
fileName : String
Relative path of the file to download
encryptionSettingName : String
Name of your encryption setting from the
Credentials
 area in Design Integrations.
Object
Downloads the file, verifies and decrypts it using the specified encryption setting and returns a reader which to read through the file line by line
File Reader Methods
You can invoke these methods on the reader object returned from the downloadFiles() method.
readLine()
String
Reads a file line by line
cleanUp()
Free the system resources consumed by the file Reader object.
FileReader can't be used after running the cleanup() method.
Resources are automatically cleaned up at the end of the script.
Example

//Pass the relative filepath and the name of your encryption setting
const reader = client.downloadEncryptedFile('./archive/datasample.csv.asc', 'mypgp');
let line = reader.readLine()
while(line !== null){
    //Process the line
    line = reader.readLine()
}

Upload a File

To upload a file, a writer must be created to which lines can be written. The writer object is obtained from the ai.sftp namespace. Once the file has been created it can be uploaded to the client using one of the following methods.
uploadFile(writer, uploadedFileName)
Writer : writer
Obtained from ai.sftp.createFileWriter() method
uploadedFileName: String
Name of the file you are uploading
Uploads the specified file to the server.
uploadEncryptedFile (writer, uploadedFileName, encryptionSettingName )
Writer : writer
Obtained from ai.sftp.createFileWriter() method
uploadedFileName: String
Name of the file you are uploading
encryptionSettingName : String
Name of your encryption setting
Encrypts the file using the specified encryption setting (found in the
Credentials
 area in Design Integrations) and uploads it to the server. The file name and location is specified by the uploadedFileName argument.
uploadEncryptedAndSignedFile(writer, uploadedFileName, encryptionSettingName)
Writer : writer
Obtained from ai.sftp.createFileWriter() method
uploadedFileName: String
Name of the file you are uploading
encryptionSettingName : String
Name of your encryption setting
Encrypts and signs the file using the specified encryption setting (found in the
Credentials
 area in Design Integrations) and uploads it to the server. The file name and location is specified by the uploadedFileName argument.
File Writer Methods
You can invoke the following methods on the Reader object that has been returned from downloading files.
writeLine(val)
val : String
Content to write to a file
Writes content to a file line by line.
cleanUp()
Free the system resources consumed by the File Writer object.
Writer can't be used after running the cleanup() method.
Resources are automatically cleaned up at the end of the script.
Example


const client = ai.sftp.createClient('mySftpConnectionSetting');
​
//Invoke the File Writer method
const writer = ai.sftp.createFileWriter();
​
//Write content to the writer variable
writer.writeLine('Here is a line to upload');
client.uploadFile(writer, 'myFileToShare.txt');
writer.cleanUp();

Notes on AWS Transfer for SFTP

While connecting to an AWS S3 server via SFTP, there are some differences in behavior with the AWS S3 file organization compared to Open SSH servers.
  • CreateDirectory
    • AWS S3 allows you to specify the path of new directories. For example, client.createDirectory('./parent/child'); will create the parent directory. However, If the parent directory already exists and you attempt to create a child directory, an exception will be thrown.