IoT File Service¶
Idea¶
The IoT File Service provides the user with file management for files related to assets. The service provides an interface to manage data, search files and download them to specified agents. Files can also be uploaded to a temporary storage and managed there.
Access¶
For accessing this service you need to have the respective roles listed in IoT File Service roles and scopes.
A user can only interact with files within their tenant and subtenants.
For accessing the Secure Data Sharing (SDS) protected APIs you need to have appropriate Policy Definitions in place. Please refer here for the list of supported APIs and Required Actions.
Basics¶
The service implements CRUD (create, read, update and delete) functionality and searching for files.
Each file is linked to an asset. An asset can have multiple files attached. The asset ID is required for each request.
Each file has a set of standard properties as metadata:
- File ID
- File name
- File path (location of the file in MindSphere)
- File type (e.g., image)
- File size
- Description
- Timestamps (created, updated)
The content of these files is not parsed by MindSphere and it requires custom applications or analytical tools to interpret and visualize the data.
The maximum request payload that can be stored or retrieved depends 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 results in an error 502 "Bad Gateway". If a file is too large to upload in one minute, use the multi part upload feature.
Versioning¶
The service does not provide explicit versioning. If different versions of a file need to be stored, 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 asset are automatically deleted if the asset is deleted physically.
File Search¶
Files can be queried using filtering and sorting operations. For more information refer to the Filtering documentation.
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
- Multi part upload and download
- Bulk delete of files for an asset
Limitations¶
- For security reasons, a strict timeout is enforced. Currently, this leads to the situation that the size of a file which can be uploaded/ downloaded depends on the network bandwidth at client side.
- When uploading files to the File Service, a file name cannot contain blank spaces. Blank spaces in the file name will prevent the file form being stored.
- After deleting an asset, associated files might still be accessible for up to 30 minutes as this data is deleted asynchronously.
- After deleting a file, it will take some time (up to 60 - 120 seconds) to create the file with the same name again depending on the data stored in storage.
- After creating or deleting the file, it will take some time (up to 3 seconds) to get the file in "search file" API.
- In File Service, a maximum of 100 characters are allowed for a file name.
- Using special characters like '*' or '?' can delay the search and might result in slow search performance.
All requests pass through MindSphere Gateway and must adhere to the MindSphere Gateway Restrictions.
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.).
The developer uses the IoT File Service to upload files to an asset.
Related Links¶
Any questions left?
Except where otherwise noted, content on this site is licensed under the Development License Agreement.