This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

File Upload

Customize the files transfer to a backend storage.

1: File upload configuration
2: File Upload API

1 - File upload configuration

Customize the files transfer to a backend storage.

Properties

To control all aspects of the file upload behavior.

Property	Type	Default	Description
featureId	string	AutoUploadable	Feature unique identifier in the scope of the edge digital twin
type	string	file	Type of the files that are uploaded by this feature
context	string	edge	Context of the files that are uploaded by this feature, unique in the scope of the `type`
files	string		Glob pattern to select the files for upload
mode	string	strict	Restriction on files that can be dynamically selected for an upload, the supported modes are: strict, lax and scoped
singleUpload	bool	false	Forbid triggering of new uploads when there is an upload in progress
checksum	bool	false	Send MD5 checksum for uploaded files to ensure data integrity
stopTimeout	string	30s	Time to wait for running uploads to finish as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
delete	bool	false	Delete successfully uploaded files
Upload - TLS
serverCert	string		PEM encoded certificate file for secure uploads
Auto upload
active	bool	false	Activate periodic uploads
activeFrom	string		Time from which periodic uploads should be active, in RFC 3339 format, if omitted (and `active` flag is set) current time will be used as start of the periodic uploads
activeTill	string		Time till which periodic uploads should be active, in RFC 3339 format, if omitted (and `active` flag is set) periodic uploads will be active indefinitely
period	string	10h	Upload period as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as: 300ms, 1.5h, 10m30s, etc., time units are: ns, us (or µs), ms, s, m, h
Local connectivity
broker	string	tcp://localhost:1883	Address of the MQTT server/broker that the file upload will connect for the local communication, the format is: `scheme://host:port`
username	string		Username that is a part of the credentials
password	string		Password that is a part of the credentials
Local connectivity - TLS
caCert	string		PEM encoded CA certificates file
cert	string		PEM encoded certificate file to authenticate to the MQTT server/broker
key	string		PEM encoded unencrypted private key file to authenticate to the MQTT server/broker
Logging
logFile	string	log/file-upload.log	Path to the file where log messages are written
logLevel	string	INFO	All log messages at this or higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE
logFileCount	int	5	Log file maximum rotations count
logFileMaxAge	int	28	Log file rotations maximum age in days, use 0 to not remove old log files
logFileSize	int	2	Log file size in MB before it gets rotated

Example

The minimal required configuration that sets the file type to log.

{
    "type": "log",
    "files": "/var/tmp/file-upload/*.*",
    "logFile": "/var/log/file-upload/file-upload.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "featureId": "AutoUploadable",
    "type": "file",
    "context": "edge",
    "files": "",
    "mode": "strict",
    "singleUpload": false,
    "checksum": false,
    "stopTimeout": "30s",
    "delete": false,
    "serverCert": "",
    "active": false,
    "activeFrom": "",
    "activeTill": "",
    "period": "10h",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "caCert": "",
    "cert": "",
    "key": "",
    "logFile": "log/file-upload.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

2 - File Upload API

The file upload service provides the ability to start, trigger, cancel, activate or deactivate upload of the file.

Start

Start a file upload operation.

Request

Hono Command: command//<name>:<namespace>/req//start

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/start Information about the affected Thing and the type of operation
path /features/AutoUploadable/inbox/messages/start A path to the AutoUploadable Feature, it’s message channel, and start command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID other UUID Identifier of the uploaded file
options Options are specific for each provider
storage.provider aws/azure/generic Storage provider that will be used for uploading the files

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/start`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/inbox/messages/start`	A path to the `AutoUploadable` Feature, it’s message channel, and `start` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID	other UUID	Identifier of the uploaded file
options		Options are specific for each provider
storage.provider	aws/azure/generic	Storage provider that will be used for uploading the files

Example : Start uploading a file.

Topic: command//edge:device/req//start

{
	"topic":"edge/device/things/live/messages/start",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/inbox/messages/start",
	"value":{
		"correlationID":"upload-id-1704439450#n",
		"options":{
			"aws.access.key.id":"AWSACCESSKEYID",
			"aws.region":"eu-central-1",
			"aws.s3.bucket":"blob-upload-test",
			"aws.secret.access.key":"AWSSECRETACCESSKEY",
			"storage.provider":"aws"
		}
	}
}

Response

Hono Command : command//<name>:<namespace>/res//start

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/start Information about the affected Thing and the type of operation
path /features/AutoUploadable/outbox/messages/start A path to the AutoUploadable Feature, it’s message channel, and start command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the operation start upload the file

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/start`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/outbox/messages/start`	A path to the `AutoUploadable` Feature, it’s message channel, and `start` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the operation start upload the file

Example : Successful response of a start file upload operation.

Topic: `command//edge:device/res//start``

{
	"topic":"edge/device/things/live/messages/start",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/outbox/messages/start",
	"status": 204
}

Trigger

Trigger a file upload operation.

Request

Hono Command: command//<name>:<namespace>/req//trigger

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/trigger Information about the affected Thing and the type of operation
path /features/AutoUploadable/inbox/messages/trigger A path to the AutoUploadable Feature, it’s message channel, and trigger command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID other UUID Identifier of the triggered file
options Options are specific for each provider

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/trigger`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/inbox/messages/trigger`	A path to the `AutoUploadable` Feature, it’s message channel, and `trigger` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID	other UUID	Identifier of the triggered file
options		Options are specific for each provider

Example : Trigger a file upload operation.

Topic: command//edge:device/req//trigger

{
	"topic":"edge/device/things/live/messages/trigger",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/inbox/messages/trigger",
	"value":{
		"correlationID":"other <UUID>",
		"options":{}
	}
}

Response

Hono Command : command//<name>:<namespace>/res//trigger

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/trigger Information about the affected Thing and the type of operation
path /features/AutoUploadable/outbox/messages/trigger A path to the AutoUploadable Feature, it’s message channel, and trigger command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the trigger operation

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/trigger`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/outbox/messages/trigger`	A path to the `AutoUploadable` Feature, it’s message channel, and `trigger` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the `trigger` operation

Example : Successful response of a trigger operation.

Topic: `command//edge:device/res//trigger``

{
	"topic":"edge/device/things/live/messages/trigger",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/outbox/messages/trigger",
	"status":204
}

Cancel

Cancel a file upload operation.

Request

Hono Command: command//<name>:<namespace>/req//cancel

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/cancel Information about the affected Thing and the type of operation
path /features/AutoUploadable/inbox/messages/cancel A path to the AutoUploadable Feature, it’s message channel, and cancel command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID other UUID Identifier of the uploaded file
statusCode This status code is set to update status code
message This message is set to update status message

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/cancel`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/inbox/messages/cancel`	A path to the `AutoUploadable` Feature, it’s message channel, and `cancel` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
correlationID	other UUID	Identifier of the uploaded file
statusCode		This status code is set to update status code
message		This message is set to update status message

Example : Cancel a file upload operation.

Topic: command//edge:device/req//cancel

{
	"topic":"edge/device/things/live/messages/cancel",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/inbox/messages/cancel",
	"value":{
		"correlationID":"upload-id-1704439450#n",
		"statusCode": 400,
		"message":"description why the upload is canceled "
	}
}

Response

Hono Command : command//<name>:<namespace>/res//cancel

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/cancel Information about the affected Thing and the type of operation
path /features/AutoUploadable/outbox/messages/cancel A path to the AutoUploadable Feature, it’s message channel, and cancel command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the operation cancel file upload

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/cancel`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/outbox/messages/cancel`	A path to the `AutoUploadable` Feature, it’s message channel, and `cancel` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the operation `cancel` file upload

Example : The response of the cancel file upload operation.

Topic: `command//edge:device/res//cancel``

{
	"topic":"edge/device/things/live/messages/cancel",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/outbox/messages/cancel",
	"status":204
}

Activate

Activate an upload of a file.

Request

Hono Command: command//<name>:<namespace>/req//activate

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/activate Information about the affected Thing and the type of operation
path /features/AutoUploadable/inbox/messages/activate A path that references a part of a Thing which is affected by this message
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
from A Time after which the upload must be activated
to A Time grater than from marks the end of activated

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/activate`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/inbox/messages/activate`	A path that references a part of a Thing which is affected by this message
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the sent back response message
Value
from		A Time after which the upload must be activated
to		A Time grater than `from` marks the end of activated

Example : Activate file upload.

Topic: command//edge:device/req//activate

{
	"topic":"edge/device/things/live/messages/activate",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/inbox/messages/activate",
	"value":{
		"from":957139200,
		"to":959817599
	}
}

Response

Hono Command : command//<name>:<namespace>/res//activate

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/activate Information about the affected Thing and the type of operation
path /features/AutoUploadable/outbox/messages/activate A path to the AutoUploadable Feature, it’s message channel, and activate command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the operation activate file upload

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/activate`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/outbox/messages/activate`	A path to the `AutoUploadable` Feature, it’s message channel, and `activate` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the operation `activate` file upload

Example : Successful response of an activate file upload operation.

Topic: `command//edge:device/res//activate``

{
	"topic":"edge/device/things/live/messages/activate",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/outbox/messages/activate",
	"status":204
}

Deactivate

Deactivate a file upload.

Request

Hono Command: command//<name>:<namespace>/req//deactivate

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/deactivate Information about the affected Thing and the type of operation
path /features/AutoUploadable/inbox/messages/deactivate A path to the AutoUploadable Feature, it’s message channel, and deactivate command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id UUID Used for correlating protocol messages, the same correlation-id as the response message
Value

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/deactivate`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/inbox/messages/deactivate`	A path to the `AutoUploadable` Feature, it’s message channel, and `deactivate` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	UUID	Used for correlating protocol messages, the same correlation-id as the response message
Value

Example : Deactivate a file upload.

Topic: command//edge:device/req//deactivate

{
	"topic":"edge/device/things/live/messages/deactivate",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/inbox/messages/deactivate",
	"value":{}
}

Response

Hono Command : command//<name>:<namespace>0/res//deactivate

Ditto Message:

Name Value Description
topic <name>/<namespace>/things/live/messages/deactivate Information about the affected Thing and the type of operation
path /features/AutoUploadable/outbox/messages/deactivate A path to the AutoUploadable Feature, it’s message channel, and deactivate command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the operation deactivate file upload

Name	Value	Description
topic	`<name>/<namespace>/things/live/messages/deactivate`	Information about the affected Thing and the type of operation
path	`/features/AutoUploadable/outbox/messages/deactivate`	A path to the `AutoUploadable` Feature, it’s message channel, and `deactivate` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the operation `deactivate` file upload

Example : Successful response of the deactivate file upload operation.

Topic: `command//edge:device/res//deactivate``

{
	"topic":"edge/device/things/live/messages/deactivate",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/AutoUploadable/outbox/messages/deactivate",
	"status":204
}