Secured Content Storage Service

File storage management, upload and retrieval service.

This service is natively used by:
- TSDB (timeseries database) service to export archived files.
- Device2 (device connectivity) to save file uploaded by devices.
The maximum file size is according to system administrator configuration, the default is 512MB(536870912 bytes)

The Content service enables applications and devices connected to the West Connectivity to host and share binary files.

Files are not stored withing the Content service itself but relies on an external file storage infrastructure service. File storage system exposes a secured API compatible with Amazon Web Services S3 (Simple Storage Service) to provide file storage and for user to interact with the files. Other compatible solutions are available to avoid hard dependency on Amazon products. Therefore, storage management, including backup, security and encryption is the responsibility of the File storage system.

Files are stored in logical folder per IoT Solutions to ensure file isolation between namespaces.

Operations

• Content.clear() - Delete all content
• Content.count() - Count the files regarding the specific type
• Content.delete() - Delete content
• Content.deleteMulti() - Delete multiple files
• Content.download() - Download URL for content
• Content.downloadAll() - Download all content in this context
• Content.info() - Get information about uploaded content
• Content.list() - List uploaded content
• Content.updateTags() - Update a content service file's tags
• Content.updateTagsMulti() - Update multiple files' tags
• Content.upload() - Upload URL for content

---

Configuration parameters

Please note that bold arguments are required, while italic arguments are optional.

Name	Type	Description
enable_backup	boolean	Config enables backup storage to automatically backup all content from current location to the backup location (both current and backup storage location are predefined during platform installation)
retention_policy	[ object ]	Retention policy to delete files
retention_policy[].ttl	^[0-9]+[dy]$	Time to live, based on when the files are uploaded/updated, should be days or years, eg: 1d, 30d
retention_policy[].name	string	The name of this policy
retention_policy[].prefix	^(?!daily_archive).*	Use 'device2' as prefix to set retention for device files. If empty, will apply to all.
whitelisted_file_types	string	Comma separated file types such as "csv, jpg, zip". If file restriction is not needed, use wildcard * instead. Default: "bin, bmp, csv, doc, docx, html, jpeg, jpg, json, md, onnx, png, rar, tar, txt, xls, xlsx, xml, yaml, yml, zip"
total_file_quota	integer	Total number of files allowed to be uploaded in a solution namespace. After the number of files has exceeded the quota, the service will block future uploads. Maximum: 100000000 Minimum: 1 Default: 100

---

Operations

Please note that bold arguments are required, while italic arguments are optional.

clear

Deletes all the content for the given context/solution; All regular and device2 files will be deleted and daily archives are excluded.

SRS-ID: S-CONTENT-INT-001

Responses

Code	Body Type	Description
200	nil	All content items are deleted; The deleted details are not listed due to the large number of content items.

Example

local res = Content.clear()
print(res)

count

Get the amount of files in regard to the specific file type(regular, device2 and daily_archive)

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
prefix	string	Only returns items starting with the given prefix.
start_time	integer	The beginning of datetime(unix timestamp in second)
end_time	integer	The end of datetime(unix timestamp in second)

Responses

Code	Body Type	Description
200	[ integer ]	The amount of the files

Example

local res = Content.count({})
print(res)

delete

Delete the given content item

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	The content unique ID

Responses

Code	Body Type	Description
200	object	The content item was deleted
400	object	Invalid content key or solution id

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item

Object Parameter of 400 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local res = Content.delete({
  id = 'image.png',
})
print(res)

deleteMulti

Delete multiple files in a solution

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
body	[ string ]	The list of files user wants to delete

Responses

Code	Body Type	Description
200	object	Number of deletion
404	object	Content not found

Object Parameter of 200 response:

Name	Type	Description
deleted_count	integer	Number of deletion

Object Parameter of 404 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local res = Content.deleteMulti({body = {"file1", "file2"}})
print(res)

download

Get the download URL for the specified content item

SRS-ID: S-CONTENT-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	The content unique ID
expires_in	^[0-9]{0,9}$	Time duration in seconds or URL validity; Expiration lasts for 5 minutes by default. Maximum: 86400 Minimum: 1

Responses

Code	Body Type	Description
200	object	The download URL
404	object	Content not found

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item
url	string	The URL to use
method	"GET"	The HTTP method to use with this URL

Object Parameter of 404 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local filename = "image.png"
local file_type = "image/png"
local expires_in = 600

local presigned_download = Content.download({
  id = filename,
  type = file_type,
  expires_in = expires_in,
})

-- Create curl download command
local curl_command = "curl --output " .. filename .. " "
curl_command = curl_command .. presigned_download.url
print(curl_command)

downloadAll

Get the download URL list for this context

SRS-ID: S-CONTENT-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
limit	integer	Number of files to query Maximum: 1000
cursor	string	Indicate the cursor when query files, normally returned by request
expires_in	^[0-9]{0,9}$	Time duration in seconds or URL validity; Expiration lasts for 5 minutes by default. Maximum: 86400 Minimum: 1

Responses

Code	Body Type	Description
200	[ object ]	The download URL list

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item
url	string	The URL to use
method	"GET"	The HTTP method to use with this URL

Example

local opts = {
  cursor = nil, -- specify the file id to start with
  limit = 5,
  expires_in = 600
}

-- This will return download urls for all files
local res = Content.downloadAll(opts)
print(res)

info

Retrieve metadata and tags associated with uploaded content

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	The content unique ID

Responses

Code	Body Type	Description
200	object	The content info
404	object	Content not found

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item
tags	object	Tags and their values for the content item
tags.***	string	Tag value
type	string	The mime type of the content item
length	integer	The content item's length in bytes
last_modified	string(dateTime)	Last modified timestamp (formatted as ISO 8601)

Object Parameter of 404 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local res = Content.info({
  id = 'image.png',
})
print(res)

list

Get the list of content items for the solution

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
full	boolean	Return complete content items instead of the id only(Default = false).
tags	string,object(json)	Both object with key values and json string with escaped double quotes are acceptable. When it is provided, returning full content properties is expected. If it is a map, the key should follow [naming rules] (https://docs.microsoft.com/en-us/rest/api/storageservices/setting-and-retrieving-properties-and-metadata-for-blob-resources#Subheading1)
op	"AND", "OR"	The operation for tags filters logic.
limit	integer	Approximate number of items to return (Default = 1000). Maximum: 2000 Minimum: 1
recursive	boolean	Return items nested in sub-folders (keys containing '/') (Default = true).
prefix	string	Only returns items starting with the given prefix. Returning regular files only by default, i.e., excluding device2 and signal daily archive content
cursor	string	Pagination cursor: The last key returned by the previous page.
sort_by	"content_id", "updated_at"	Sort key Default: "content_id"
sort_order	"asc", "desc"	Sort order Default: "asc"
page	integer	The page with files to display Maximum: 500 Minimum: 1 Default: 1
start_time	integer	The beginning of datetime(unix timestamp in second)
end_time	integer	The end of datetime(unix timestamp in second)

Responses

Code	Body Type	Description
200	[ object ]	An array of content items

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item
tags	object	Tags and their values for the content item
tags.***	string	Tag value
type	string	The mime type of the content item
length	integer	The content item's length in bytes
last_modified	string(dateTime)	Last modified timestamp (formatted as ISO 8601)

Example

local res = Content.list({
  full = true
})
-- or
res = Content.list({
  tags = to_json({mykey = "myvalue"})
})
-- or
res = Content.list({
  tags = to_json({mykey = "myvalue", mykey2 = "myvalue2"}),
  op = "OR"
})
print(res)

updateTags

Update a content service file's tags. The tags are only stored locally in content_service.

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	The content unique ID
tags	string,object(json)	Both object with key values and json string with escaped double quotes are acceptable. When it is provided, returning full content properties is expected. If it is a map, the key should follow [naming rules] (https://docs.microsoft.com/en-us/rest/api/storageservices/setting-and-retrieving-properties-and-metadata-for-blob-resources#Subheading1)
merge	boolean	By default, merge the tags on True, set to False to replace tags.

Responses

Code	Body Type	Description
200	nil	Config updated

Example

local new_tag = to_json({newkey = "newvalue"})
local res = Content.updateTags({id="file_name_in_content_service",tags=new_tag, merge =true})
print(res)      

updateTagsMulti

Update multiple files' tags in Content Service. The tags are only stored locally in Content Service.

SRS-ID: S-CONTENT-INT-001

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
tags	string,object(json)	Both object with key values and json string with escaped double quotes are acceptable. When it is provided, returning full content properties is expected. If it is a map, the key should follow [naming rules] (https://docs.microsoft.com/en-us/rest/api/storageservices/setting-and-retrieving-properties-and-metadata-for-blob-resources#Subheading1)
merge	boolean	By default, merge the tags on True, set to False to replace tags.
body	[ string ]	The list of files user wants to update tags

Responses

Code	Body Type	Description
200	nil	Config updated
400	object	Argument error
404	object	Content not found

Object Parameter of 400 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Object Parameter of 404 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local new_tag = to_json({newkey = "newvalue"})
local res = Content.updateTagsMulti({tags=new_tag, merge=true, body = {"file1", "file2"}})
print(res)      

upload

Get the upload URL for the specified content item. The content ID will be generated if not supplied, and can be generated using the key, if provided.

SRS-ID: S-CONTENT-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	The content unique ID
md5	string	The md5 sum of the content to upload
type	string	The content's type
expires_in	^[0-9]{0,9}$	Time duration in seconds or URL validity; Expiration lasts for 5 minutes by default. Maximum: 86400 Minimum: 1
tags	string,object(json)	Both object with key values and json string with escaped double quotes are acceptable. When it is provided, returning full content properties is expected. If it is a map, the key should follow [naming rules] (https://docs.microsoft.com/en-us/rest/api/storageservices/setting-and-retrieving-properties-and-metadata-for-blob-resources#Subheading1)

Responses

Code	Body Type	Description
200	object	The upload URL
400	object	Invalid file type
429	object	Exceed upload quota

Object Parameter of 200 response:

Name	Type	Description
id	string	The id of the content item
url	string	The URL to use
field	string	The name of the part containing upload data (must be LAST)
inputs	object	Additional parts expected with the upload
inputs.acl	string	Acl
inputs.key	string	Key
inputs.policy	string	Policy
inputs.x-amz-date	string	Amz date
inputs.Content-MD5	string	Content md5
inputs.content-type	string	Content type
inputs.x-amz-algorithm	string	Amz algorithm
inputs.x-amz-meta-name	string	Meta name
inputs.x-amz-signature	string	Amz signature
inputs.x-amz-credential	string	Amz credential
method	"POST"	The HTTP method to use with this URL
enctype	string	The expected form-data encoding to use

Object Parameter of 400 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Object Parameter of 429 response:

Name	Type	Description
type	string	The error message's type
message	string	The associated error message

Example

local filename = "image.png"
local file_type = "image/png"
local expires_in = 600

local presigned_upload = Content.upload({
  id = filename,
  type = file_type,
  expires_in = expires_in,
})

-- Create curl upload command
local curl_command = "curl"
for k, v in pairs(presigned_upload.inputs) do
  curl_command = curl_command .. " -F \"" .. k .. "=" .. v .."\""
end -- This assumes the file exist in the same directory as curl is being called from.
curl_command = curl_command .. " -F file=@" .. filename .. " " .. presigned_upload.url
print(curl_command)

Service Health Check

Operations

/

Enable the hosting system to check if service is active and running

SRS-ID: S-CONTENT-INT-004

Arguments

No Content

Responses

Name	Type	Description
200	string	OK

Errors

No content