Transferring Files through the REST Web Services
To prepare for file transfers, set up the EMS with virtual directories to send and receive files. If it is not already running, start the LSR for the device so that the virtual Thing at the edge is up and running and the ThingWorx Platform knows it is connected.
To invoke a file transfer from the platform, use the HTTP POST method and the following URL:
http://<server_name>:<port>/Thingworx/Subsystems/FileTransferSubsystem/Services/Copy
In the area provided in the REST client, enter the parameters for the Copy service (in a JSON object), as indicated here:
{
"sourceRepo": "<Enter a Valid Repository"
"sourcePath": "<Enter a Valid Path>"
"sourceFile": "<Enter a Valid File>"
"targetRepo": "<Enter a Valid Thing>"
"targetPath": "<Enter a Valid Path>"
"targetFile": "<Enter a New Name for the file (optional>"
}
The parameters are broken down by target and source (you can view the parameters by looking at the definition for the Copy service in ThingWorx Composer).
|
Refer to the ThingWorxHelp Center for more information about the Copy services, specifically the details concerning what is a valid file repository (that is, which templates support file transfer).
|
When you run the request, you can view the results (in JSON) format in the REST client. Scroll down until you locate the rows of the infotable. The value of the state parameter is "validated" if the file was transferred successfully.
You can also execute a file transfer through the EMS, using the same parameters and same POST, with the URL pointed at the local EMS:
http://localhost:8000/Thingworx/Subsystems/FileTransferSubsystem/Services/Copy
The headers for the EMS differ in that you have only the content-type header for the EMS. The results are the same (except that the EMS puts the rows at the top and the Data Shape at the bottom).
Why use the EMS or an SDK with the REST Web Service instead of just calling the ThingWorx Platform REST Web Services from an application? There are some benefits to using the EMS or an SDK just to interact with the ThingWorx Platform, using the REST Web Services:
• You can have a secure connection when you use an EMS or an SDK to interact with a ThingWorx Platform.
• The AlwaysOn protocol persists the connection between an application and a configured ThingWorx Platform.
• When an EMS or an SDK makes the REST calls instead of your application, you save a lot in terms of resource usage on the ThingWorx Platform. The platform could potentially have to handle hundreds of HTTP requests coming from an application that is running on hundreds of devices, all sending multiple requests. Typically, the most expensive part of HTTP request is opening the socket — all the headers that are sent across the wire and so forth. When you use an EMS or SDK, you eliminate the burden on the ThingWorx Platform. The WebSocket connection is already set up (and persisted), and the multiple requests for an application are sent over the single WebSocket. In addition, the EMS and the SDKs send the requests using binary data, which results in more efficient use of bandwidth (in terms of the number of bytes that go across the wire).
• With the EMS or an SDK, the step to set up the socket is eliminated. Requests and responses can be exchanged more quickly. Especially if you have multiple applications that are making multiple requests behind an EMS, performance improvements are significant when you use the EMS to pass REST requests instead of passing them directly to your ThingWorx Platform.