Skip to content

IoT File Service

Idea

The IoT File Service provides the user with file management for files related to entity instances.

The service enables the user to carry out following file management tasks:

  • Read, upload, update and delete files associated with assets.
  • Save metadata of uploaded files.
  • Search for files by metadata.
  • Upload files to a temporary storage and manage there.
  • Download files to specified agents.

Access

The following permissions are required for file management:

  • Writing or updating a file: iot.fil.w
  • Reading a file: iot.fil.r
  • Deleting a file: iot.fil.d
  • Searching for files: iot.fil.r

A user can only interact with files within his tenant and subtenants.

Basics

The service implements CRUD (create, read, update and delete) functionality and searching for files.

Each file is related to an entity. An entity instance can have multiple files attached. The entity ID is required for each request.

Each file has a set of standard properties as metadata:

  • File name
  • File path
  • File type (e.g., image)
  • File size
  • Description
  • Time stamps
  • ...

The content of these files is not parsed by MindSphere and it will require custom applications or analytical tools to interpret and visualize the data.

The maximum file size that can be stored or retrieved is dependent on the client's network speed. The current timeout is one minute, and any file that takes longer than one minute to read or write will result in an error 502 "Bad Gateway".

Versioning

The service does not provide explicit versioning. If different versions of a file need to be stored, the application can put a version identifier in the file name to make it unique.

File deletion

Files are always deleted physically. There is no logical delete. Files of an entity instance are automatically deleted if the instance is deleted physically.

Search filter syntax

Files can be queried by filtering on any of their available file properties. Complex filters using multiple clauses and various operators are possible.

The allowed operators in a filter clause are:

  • eq or =
  • gte or >=
  • gt or >
  • lte or <=
  • lt or <

Filters can use the wildcard character * on any field. Multiple filters can be specified using the and operator (or is not supported).

Note that time stamps are stored as strings in ISO 8601 format in the UTC timezone. Be aware that if an entity time stamp of "2017-09-21T14:08:22.345+02:00" is written in the file property, searching for this file by time stamp would have to be a search for "2017-09-21T12:08:22.345Z".

Malware protection

Malware detection and protection can be done by customer-provided malware scanners. The IoT File Service communicates with the malware scanner. Only cleared files will be stored in MindSphere. For rejected files, a log entry is created.

Features

The IoT File Service exposes its API for realizing the following tasks:

  • Create a new file.
  • Update (overwrite) an existing file.
  • Read a file.
  • Delete a file.
  • Search for files by metadata.
  • Count and order files by metadata.

Restrictions

To get the current list of restrictions go to release notes and choose the latest date. From there goto "MindAccess Developer Plan Subscribers and MindAccess Operator Plan Subscribers" and pick the IoT service you are interested in.

Example Scenario

The application developer of a brewery wants to store files associated to assets in order to provide additional meta information (e.g., images, technical descriptions, manuals, etc.).

Use the IoT File Service to upload files to an asset.

Requirements

  • Write permissions are available.
  • An asset is already created.

API Specification

Download OpenAPI Specification

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.