Information about supported interface version can be fetched calling the root endpoint of DataService:
Interface information returns the highest available minor version of each major version. This lets the user decide which features can be used. As a minor version is backwards compatible to all previous minor versions, there is no point in enumerating them all. An user want to know which revision of each major version is available as that means they can work around possible bugs of older revisions.
The service information can be fetched via the following endpoint. This endpoint doesn’t provide filter parameters.
You can can fetch information about raw data objects by using the following endpoints.
Returns a list of raw data file information entries for all entities with type :entity. You further have to and restrict the request to the entities’ uuids by adding the following uri parameter:
Parameter name | Description Example |
---|---|
uuids |
Restricts the query to the entities identified by the given uuids. Entites of type ‘Value’ are identified by a compound key, which consists of the uuid of the measurement, ‘|’ and the characteristics uuid uuids={652ae7a0-d1e1-4ee2-b3a5-d4526f6ba822|78bd15c6-dc70-4ab4-bd3c-8ab2b5780b52} |
filter |
Contains one or multiple attribute conditions to restrict the query. Details can be found below. |
Filter syntax
Basic module is expression <attribute> <operator> <value>
or <attribute> <list operator> (<value1>, <value2>, ...)
Possible <attribute> values | Description |
---|---|
MimeType |
MimeType of raw data object |
FileName |
File name of raw data object |
LastModified |
Date of last change made to raw data object |
Created |
Date of creation of raw data object |
Length |
Size of raw data object in bytes |
MD5 |
Check sum of raw data object |
Possible <operator> values | Description |
---|---|
eq |
Checks if attribute equals <value> |
ne |
Checks if attribute is not equal to <value> |
lt |
Checks if attribute is lower than <value> |
le |
Checks if attribute is equal or lower than <value> |
gt |
Checks if attribute is greater than <value> |
ge |
Checks if attribute is equal or greater than <value> |
like |
Compares attribute with a wildcard string. Character ‘*’ represents any number of any characters. Character ‘?’ represents exactly one of any characters. If you want to use one of these wildcard characters within a filter expression use ‘' to mask it. Use ‘' to mask ‘' as well. Use of like operator is only available for string attributes. |
Possible <List operator> values | Description |
---|---|
in |
Checks if attribute exists in a list of values |
notin |
Checks if attribute does not exist in a list of values |
<Value> can be formatted differently and needs to match type of attribute:
'Some Value'
or 'This string contains a single '' character.'
.'2018-01-21T16:12:30+01:00'
'-<Offset>[mhdwMy]'
where m = minutes, h = hours, d = days, w = weeks, M = months, y = years, e.g. ‘-1w’ or ‘-5d’Value list (<Value1>, <Value2>, …) contains any number of elements which need to meet the conditions described in above
Attribute conditions can be combined by logical operators and
, or
or not
:
<Condition1> and <Condition2>
<Condition1> or <Condition2>
not <Condition1>
Examples:
Filename like '*.txt' or MimeType eq 'text/plain'
Length lt 5000
(MimeType like 'text/* or Filename like '*.txt') and Length lt 5000
not MimeType like 'text/*'
Filename in ('some_file.txt', 'some_other_file.html')
Update raw data information when you want to:
An update request consists of 2 mandatory parts:
The returned objects contains the following properties:
Property | Description |
---|---|
TargetEntity target |
Specifies a concrete entity for a raw data object and consits of the entity’s type (Part, Characteristic, Measurement, Value) and guid. If raw data is attached to an entity of type Value , the uuid contains a compound key in the following format: {MeasurementUuid}|{CharacteristicUuid} |
int key |
This is a unique key that identifies this specific raw data object for a corresponding entity. An entity can have multiple raw data object that are distinct by this key. |
string fileName |
The filename of the raw data object. Please note that this filename is not unique (unlike filenames in traditional file systems). |
string mimeType |
The file’s mime type. |
DateTime lastModified |
The timestamp of the last modification of the corresponding raw data object |
DateTime created |
The timestamp of the creation of the corresponding raw data object |
int size |
The size of the raw data object in bytes |
string md5 |
The MD5-Hash of the raw data object |
You can can fetch, create, update and delete raw data objects by using the following endpoints.
The server caches raw data fetch requests. When you request a raw data file for the first time the response will contain the file itself and several HTTP headers. One of these headers is the ETag header. An ETag is a unique hash value to identify the file. It is a combination of the file’s MD5 checksum and the last modification date. If you send the ETag value in the If-None-Match header, the server can respond two different ways, depending on whether the file has been modified since the last request:
The requested raw data file
The requested thumbnail
You can attach files to all entity types: parts, characteristics, measurements and measured values.
An add request consists of 3 mandatory parts:
HTTP header variable | Description | Example Value |
---|---|---|
Content-Disposition | Includes the file name | “MetalPart.meshModel” |
Content-Length | Includes the length in bytes | 2090682 |
Content-Type | Includes file’s MIME type | “application/x-zeiss-piweb-meshmodel” |
Content-MD5 | (optional) Includes file’s MD5 hash sum in Base64 format | “vfawarMBqArlUCEIW4IDkw==” |
The allowed raw data file names (see
Content-Disposition
) can be restricted on the server.
When adding a file, you can pass the desired file key as part of the uri. If you pass -1 or no key, the next available key will automatically be assigned by the server (recommended) and can be read from the result.
If you pass a key which is already assigned to another file, this file will be replaced.
Remember, when adding a file for a measured value, you need to specify the target uuid in a compound format of measurementUuid|characteristicUuid, instead of one single uuid.
An update request consists of 3 mandatory parts:
HTTP header variable | Description | Example Value |
---|---|---|
Content-Disposition | Includes the file name | “MetalPart.meshModel” |
Content-Length | Includes the length in bytes | 2090682 |
Content-Type | Includes file’s MIME type | “application/x-zeiss-piweb-meshmodel” |
Content-MD5 | (optional) Includes file’s MD5 hash sum in Base64 format | “vfawarMBqArlUCEIW4IDkw==” |
The allowed raw data file names (see
Content-Disposition
) can be restricted on the server.
The RawDataService offers special endpoints to work with archives, including the possibility to list contents of an archive which is saved as raw data on any target entity, or retrieving only specified files of an archive instead of requesting the whole archive. This can save time and data if you only need a small portion of an archive.
Archive lookup currently works with archives of filetype
.zip
You can fetch information about the archive and included files. In this example the ExampleArchive.zip contains three files as listed in “entries”: information.txt, metal_part.meshModel and thumbnail.jpg.
The returned object contains the following properties:
Property | Description |
---|---|
RawDataInformation archiveInfo |
Information about the raw data which is an archive, the same properties as Raw Data Information. |
string[] entries |
A list of all files inside the archive, including subfolders. |
As archives can contain subfolders, the structure is present in the filename.
Since folders are also entries from the point of view of the archive, they are part of the response like Subfolder/ in above example.
Please note that these entries do not contain data, so requesting the entry Subfolder/ will result in HTTP status code 200 - OK
, but without data in the response body.
You will not receive the folders content. For this you need to explicitly fetch the files located in the subfolder with their full name, including folder structure, as shown in the next endpoint.
Once you know the contents of specified archive you can request single files with a GET request similiar to fetching normal raw data. You specify the raw data archive with :entity, :uuid and :key, and the requested file with its :filename. This endpoint offers the same caching mechanisms as the normal request for raw data.
The filename is case insensitive. Archive lookup will return the first occurence of specified file if two files with the same name exist in the same folder.
Parameter name | Description Example |
---|---|
filename |
The filename of a file which is part of specified archive, e.g. information.txt. The filename includes folder structure if the file is located in some subfolder, e.g. Subfolder/information.txt. |
You can request information and file lists for more than one archive at a time using this query endpoint.
The property selectors
can contain any number of raw data targets and the key of the raw data archive.
You can fetch multiple files of the same or different archives using the ArchiveContentQuery
endpoint.
The property selectors
contains the same information as the ArchiveEntryQuery
above, with an additional list of requested files per raw data archive.
The requested files in BSON format.
The BSON contains one entry for each requested file, with no separation between files of different raw data archives. Each entry contains
the property archiveInfo
, which again has the same structure as Raw Data Information. The entry can be identified by its
fileName
and is completed by the actual data
, the size
and an md5
checksum.
You can add more targets to selectors
to fetch files from different archives:
Archive lookup only works with supported archives, currently the .zip format. If you try to list or fetch contents of raw data in any other format you will receive HTTP status code 400 - BadRequest
and the following response: