file.put

The file.put command reserves a file handle to be used to upload a file via HTTP POST. To learn more about how files are used in the ,  see Understanding files.

TR50 Request

{
  "cmd": {
    "command": "file.put",
    "params": {
      "fileName": "myname.txt",
      "thingKey": "myThing",
      "public": false,
      "tags": [
        "note",
        "readme"
	],
	"basicAuth": {
	  "username": "fileUsername",
	  "password": "filePassword"
	},
      }
    }
  }
}

Request Parameters

Name Type Required Description
thingKey String The Thing that the file will be attached to.

Note: Default to the current session's Thing. As a user, thingKey is required.
global Boolean If set to true, the file will be a global file and the thingKey parameter will be ignored. Defaults to false.
fileName String Yes The name of the file to be uploaded to the platform.
public Bool If true, identifies the file as publicly accessible outside of the organization. If false, the file is private to the organization. Defaults to false.
crc32 Integer A IEEE CRC32 checksum of the file to be uploaded. When the file is subsequently sent via the HTTP interface, the checksum will be validated, and if incorrect, the file will be discarded an an error returned.
tags Array A list of tags to associate to the file.
secTags Array A list of tags to specify security access to the file.
ttl Integer Specify an expect ttl (in seconds) for a file. If a file is uploaded partially in a set ttl, partial file will be deleted after elapsed time.
logComplete Boolean If set to true, creates an event log entry when the file upload is complete.
calculateSha256 Boolean If true, the SHA256 of the file will be calculated and stored with the metadata for the file
basicAuth struct   An instance of a Basic Auth Object. If a file should be password protected, use the basicAuth element and include the username and password fields to enable Basic Access Authentication for the file. If either field is omitted neither will be set and the file will not have Basic Access Authentication enabled. To download the file when Basic Access Authentication is enabled for the file, the username and password must be entered and authenticated or the file will not be accessible.
private Boolean   If true, the file will be secured with a token/password. This password will only be returned when this command executes successfully. To access this file, the token will be required. Is mutually exclusive to the public parameter. Defaults to false.

Basic Auth Object

Name Type Required Description
username String This field enables Basic Access Authentication for downloading the file. The username cannot contain a colon ( : ).
password String This field enables Basic Access Authentication for downloading the file.

TR50 Response

When you upload a large file to the deviceWISE Cloud, the file gets divided into smaller chuncks by the deviceWISE Cloud. If you try to download or delete a file that is being uploaded in chunk, you will get a File <filename> not found error.

If the command is sent successfully a success message and params list is returned. Otherwise, an error and error message will be returned.

{
  "cmd": {
    "success": true,
    "params": {
      "fileId": "50000000000000000000042"
    }
  }
}

The fileId returned from file.put is only valid for a single use and times out within 300 seconds by default.

Response Parameters

Name Type Description
fileId String A unique file handle id to be used in the HTTP POST.
privToken String Will be returned when the private parameter in the request is set to true.