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, skip and sort

  • Required security permission - READ.

  • HTTP methods supported: GET, POST.

Description

This endpoint allows to read information of files stored in the context of objects.

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 false.

_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 Base64 encoded JSON (dictionary). By default not set.

insights

boolean

yes

Indicates application insights should be included in the response. By default false.

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 GET

Request URL
  • /api/v2/readfile?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711

HTTP POST

Request URL
  • /api/v2/readfile

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 GET

Request URL
  • /api/v2/readfile?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711&include_file_store_info=true

HTTP POST

Request URL
  • /api/v2/readfile?include_file_store_info=true

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 URL
  • /api/v2/readfile

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
        }
    ]
}