Read Files
-
Can return file information stored in the context of objects.
-
Is able to fetch file data stored in different file stores.
-
Returns by default a flat list of file information per object.
-
Is able to return file information grouped by file stores.
-
Accepts a filter for server side filtering.
-
Supports MongoDB options
limit,skipandsort -
Required security permission -
READ. -
HTTP methods supported:
GET,POST.
Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
items |
object |
no |
An array of objects which contain a path or ID of the object to be queried for files information. |
storename |
string |
yes |
Comma separated string of file store names to define which file stores should be queried. By default all available file stores will be queried. |
include_file_store_info |
bool |
yes |
Specifies file store information needs to be returned. Setting this options changes the response structure. By default |
_id |
string |
yes |
MongoDB ObjectId of the file to retrieve. |
start_time |
string |
yes |
The start time (UTC) of the interval to retrieve files for. By default not set. |
end_time |
string |
yes |
The end time (UTC) of the interval to retrieve files for. By default not set. |
filter |
object |
yes |
Additional filter expression. The query syntax is identical to the MongoDB read operation query syntax. By default not set. |
limit |
integer |
yes |
The maximum number of file information objects per file store to return. If not supplied a default store limit can be applied. |
skip |
integer |
yes |
The number of file information objects per file store to skip from the result. By default not set. |
sort |
object |
yes |
Expression to order the files in the response. The syntax is identical to the MongoDB sort expression syntax. Has to be a JSON (dictionary). In case of a HTTP GET the value of this URL query parameter must be Base64 encoded. By default not set. |
insights |
boolean |
yes |
Indicates application insights should be included in the response. By default |
Including File Store Information
By default the response of this endpoint contains per item a files field, which contains a flat list of file information objects, including the name of the file store. By setting the option include_file_store_info to true the response will contain a file_stores object per item. This object will contain information regarding the file store and a files fields, which contains the file information objects.
Filtering
The filter parameters _id, start_time, end_time and filter are used to create an AND query to filter the files stored in the context of the provided items. In case the _id parameter is set all other filter parameters are ignored. The start_time and end_time are used to filter files based on the timestamp field in the metadata. Only files are returned of which the value of the field metadata.timestamp is greater than or equal to the start_time and less than the end_time parameter.
The syntax of the filter parameter must be conform the MongoDB read operation query syntax.
Sorting
The file information objects in the files list in the response can be sorted by setting the 'sort' option in the request.
The syntax of the sort parameter must be conform the syntax of a MongoDB sort document syntax
Examples
Single query to read file information stored in the context of an object
Example to read the information of files stored in the context of one object. By default this endpoint queries all available file stores in the system.
HTTP POST
Request body
The following example contains a read file query, which contains one single item.
{
"items": [
{
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
]
}Response body
{
"data": {
"file_data": {
"query_data": [
{
"items": [
{
"query_index": "1",
"p": "/System/Core/Examples/Demo Data/Process Data/c",
"files": [
{
"_id": "5cf0e75c84b00a016000074c",
"alias": "HTC - DC4711",
"chunk_size": 261120,
"filename": "DC4711.csv",
"length": 2727,
"metadata": {
"content-type": "text/csv",
"filepath": "C:\\Temp\\DC4711.csv",
"location": "HTC",
"ordernumber": 1234,
"path": "/System/Core/Examples/Demo Data/Process Data/DC4711",
"timestamp": 1559291739070
},
"storename": "Lab",
"upload_date": "2019-05-31T08:35:40.000Z"
}
]
}
]
}
]
}
}
}Including file store information
By setting the the URL query parameter 'include_file_store_info' to true the files in the response will be grouped by the file store in which the files are stored.
HTTP POST
Request body
The following example contains a read file query, which contains one single item.
{
"items": [
{
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
]
}Response body
{
"data": {
"file_data": {
"query_data": [
{
"items": [
{
"file_stores": [
{
"descr": "Laboratory files",
"files": [
{
"_id": "5cf0e75c84b00a016000074c",
"alias": "HTC - DC4711",
"chunk_size": 261120,
"filename": "DC4711.csv",
"length": 2727,
"metadata": {
"content-type": "text/csv",
"filepath": "C:\\Temp\\DC4711.csv",
"location": "HTC",
"ordernumber": 1234,
"path": "/System/Core/Examples/Demo Data/Process Data/DC4711",
"timestamp": 1559291739070
},
"upload_date": "2019-05-31T08:35:40.000Z"
}
],
"name": "Lab"
}
]
}
],
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
}
],
"query_index": "1"
}
}
}Advanced request
Example for retrieving file information by defining two queries in the same request to query multiple items by using different filtering and sorting options
HTTP POST
Request body
The following example contains a file query, which contains one single item.
{
"queries": [
{
"storename" : "lab,prod",
"start_time": "2019-06-01T00:00:00.000Z",
"end_time": "2029-06-07T00:00:00.000Z",
"items": [
{
"p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
},
{
"p": "/System/Core/Examples/Demo Data/Process Data/DC666"
}
],
"filter": {
"metadata.content-type": "image/jpeg"
},
"sort": {
"filename": 1
}
},
{
"storename" : "lab",
"start_time": "2019-06-01T00:00:00.000Z",
"end_time": "2029-06-07T00:00:00.000Z",
"items": [
{
"p": "/System/Core/Examples/Demo Data/Process Data/FC4711"
}
],
"filter": {
"metadata.ordernumber": "text/csv"
},
"sort": {
"metadata.timestamp": -1
},
"limit" : 100
}
]
}