Files¶
The base path, referred to as {storage-resource}
below, is one of the
following depending on if a request should resolve all files or files on a
specific storage only.
/storage/{storage-id}
/storage
Operations on files, uses {file-resource}
can be one of:
{storage-resource}/file/{file-id}
{storage-resource}/file/path/{path}
{storage-resource}/file/uri/{uri}
Information about files in storage¶
List files in storage¶
New in version 4.1.2.
-
GET
{storage-resource}/file
¶ Query Parameters: - id – Optional, if multiple
id
query parameters are specified only those files are returned. If no ids are specified, all files are returned. - path –
Optional string
- path - Return files under this sub-path to storage.
/
(default) - Return all files.
- ignorecase –
true
- Search file path case insensitivelyfalse
- Search file path case sensitively
- recursive –
true
(default) - Return all files in tree.false
- Return only files directly under specified path.
- wildcard –
true
- Allow use of wildcards in path.false
(default) - No wildcard handling of path.
- hash – Optional list of hash values. Only return files with specific hash value.
- algorithm – Optional hash algorithm. Search for hash values used by specified algorithm
- count –
true
(default) - Return total number of hits in resultfalse
- Do not return total number of hits in result, in order to produce results faster
- state –
Optional string to filter results by file state. Can be used multiple times to select several states.
New in version 4.7.
- methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
methodType
. see Storage methods. - storageType – Only return URIs for files from storages of this type. See Storages.
- methodMetadata – Optional metadata used with storage method. See Storages.
- scheme – URI scheme to return.
Matrix Parameters: - first – Optional integer. From total list of files, start return list from specified number. Default is
0
. - number – Optional integer. Return a maximum of specified number of files. Default is
10
. - sort –
Optional comma-separated list.
fileId
[asc
(default) |desc
] (default) - Order results by file idsize
[asc
(default) |desc
] - Order results by file size (bytes)state
[asc
(default) |desc
] - Order results by File Statestimestamp
[asc
(default) |desc
] - Order results by file timestampfilename
[asc
(default) |desc
] - Order results by filenameextension
[asc
(default) |desc
] - Order results by file extension.New in version 4.2.1.
- storage – Optional list of storage ids. Return only files from specific storages.
Same as
storage-id
in URL, but can be specified multiple times - filter –
all
(default) - Return all filesitem
Only return files associated with an item.noitem
Only return files not associated with any item.
- excludeQueued –
true
(default if searching importable files) - Exclude the files that are queued for importfalse
(default if searching all files) - Do not exclude the files that are queued for import
- includeItem –
true
- Return associated items, shapes, and components.false
(default) - Do not return any information about associated items, shapes, and components.
Produces: - application/xml, application/json – FileListDocument
- text/plain – CRLF-delimited list of file ids
Role: _file_read
- id – Optional, if multiple
Tip
There is a limit on how many files that can be returned for each call to this method. To get all files, iterate the calls.
Example¶
For examples on how recursive
and
wildcard
works together, see the following table:
Path | Recursive | Wildcard | File on storage | Note | |||
foo |
foo/bar |
foo/bar/baz |
foo/bar/?az |
||||
false |
- | Y | N | N | N | (1) | |
true |
- | Y | Y | Y | Y | ||
/ |
false |
- | Y | N | N | N | |
/ |
true |
- | Y | Y | Y | Y | |
/foo |
false |
- | Y | N | N | N | |
/foo |
true |
- | Y | Y | Y | Y | |
foo |
false |
- | Y | N | N | N | (2) |
foo |
true |
- | Y | Y | Y | Y | |
/foo/ |
false |
- | N | Y | N | N | |
/foo/ |
true |
- | N | Y | Y | Y | |
/foo/bar |
false |
- | N | Y | N | N | |
/foo/bar |
true |
- | N | Y | Y | Y | |
/foo/bar/ |
- | - | N | N | Y | Y | |
\foo\bar\ |
- | - | N | N | N | N | (3) |
/foo/bax///../bar/./ |
- | - | N | N | Y | Y | |
/foo/b?r |
false |
true |
N | Y | N | N | (4) |
/foo/b??r |
false |
true |
N | N | N | N | |
/foo/*r |
false |
true |
N | Y | N | N | (5) |
/foo/**r |
false |
true |
N | Y | N | N | |
/foo/bar/?az |
false |
false |
N | N | N | Y | (6) |
/foo/bar/?az |
false |
true |
N | N | Y | Y | |
/foo/bar/\?az |
false |
false |
N | N | N | N | (7) |
/foo/bar/\?az |
false |
true |
N | N | N | Y | (8) |
Notes:
- Empty string =
/
. - The initial
/
is implicit. /
is the path delimiter in Vidispine, also on Windows.?
= exactly one.*
= 0 or more?
is not officially supported, see URI’s, URL’s, and Special Characters.- With wildcard=false,
\
is literal. However,\
is not officially supported, see URI’s, URL’s, and Special Characters. - With wildcard=true, use
\
to quote (”\
” has to be quoted).
Legend:
- -
- Does not matter for this example
- Y
- is included in search result
- N
- is not include in search result
Get status of file in storage¶
-
GET
{file-resource}
¶ Query Parameters: - methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
methodType
. see Storage methods. - storageType – Only return URIs for files from storages of this type. See Storages.
- methodMetadata – Optional metadata used with storage method. See Storages.
- scheme – URI scheme to return.
Matrix Parameters: - includeItem –
true
- Return associated items, shapes, and components.false
(default) - Do not return any information about associated items, shapes, and components.
Produces: - application/xml, application/json – FileDocument
- text/plain – Tabbed tuples of file id, file path, file size, file status, timestamp
Role: _file_read
- methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
Upload file to storage¶
New in version 4.1.2.
-
POST
{storage-resource}/file/data
¶ Query Parameters: - transferId – An id to assign the transfer to be able to refer to it. Mandatory for chunked and passkey imports.
- transferPriority – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers (optional). A transfer with a high priority value is considered more important than a transfer with a low priority value.
- path –
The path of the file on the storage (optional).
New in version 4.7.
- uri –
The absolute file URI (optional and should be relative to the URI of a storage method).
New in version 4.7.
- state –
The state of the file (optional).
New in version 4.7.
Status Codes: - 400 –
If the amount of data received does not match the given Content-Length header.
New in version 4.2.3.
Accepts: - application/octet-stream – The raw essence data.
Produces: - application/xml, application/json –
New in version 4.7.
- text/plain – file id
Role: _file_write
File data¶
Get file data¶
-
GET
{file-resource}/data
¶ Produces: - application/octet-stream – The raw file data.
Role: _file_read
Upload file data¶
New in version 4.1.2.
-
POST
{file-resource}/data
¶ Query Parameters: - transferId – An id to assign the transfer to be able to refer to it. Mandatory for chunked and passkey imports.
- transferPriority – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers (optional). A transfer with a high priority value is considered more important than a transfer with a low priority value.
Status Codes: - 400 –
If the amount of data received does not match the given Content-Length header.
New in version 4.2.3.
Accepts: - application/octet-stream – The raw file data.
Produces: - application/xml, application/json – FileDocument
Role: _file_write
Importable files¶
Get files that can be imported¶
-
GET
{storage-resource}/importable
¶ Retrieves a list of files, together with any found metadata, for files that do not belong to any component.
Query Parameters: - auto –
true
- Return files that will be automatically imported due to auto-import rules.false
(default) - Do not return files that will be automatically imported.
- id – Optional, if multiple
id
query parameters are specified only those files are returned. If no ids are specified, all files are returned. - path –
Optional string
- path - Return files under this sub-path to storage.
/
(default) - Return all files.
- ignorecase –
true
- Search file path case insensitivelyfalse
- Search file path case sensitively
- recursive –
true
(default) - Return all files in tree.false
- Return only files directly under specified path.
- wildcard –
true
- Allow use of wildcards in path.false
(default) - No wildcard handling of path.
- hash – Optional list of hash values. Only return files with specific hash value.
- algorithm – Optional hash algorithm. Search for hash values used by specified algorithm
- count –
true
(default) - Return total number of hits in resultfalse
- Do not return total number of hits in result, in order to produce results faster
- state –
Optional string to filter results by file state. Can be used multiple times to select several states.
New in version 4.7.
- methodType – Return URIs from storage methods with a particular type.
By default, return URLs with empty
methodType
. see Storage methods. - storageType – Only return URIs for files from storages of this type. See Storages.
- methodMetadata – Optional metadata used with storage method. See Storages.
- scheme – URI scheme to return.
Matrix Parameters: - first – Optional integer. From total list of files, start return list from specified number. Default is
0
. - number – Optional integer. Return a maximum of specified number of files. Default is
10
. - sort –
Optional comma-separated list.
fileId
[asc
(default) |desc
] (default) - Order results by file idsize
[asc
(default) |desc
] - Order results by file size (bytes)state
[asc
(default) |desc
] - Order results by File Statestimestamp
[asc
(default) |desc
] - Order results by file timestampfilename
[asc
(default) |desc
] - Order results by filenameextension
[asc
(default) |desc
] - Order results by file extension.New in version 4.2.1.
- storage – Optional list of storage ids. Return only files from specific storages.
Same as
storage-id
in URL, but can be specified multiple times - filter –
all
(default) - Return all filesitem
Only return files associated with an item.noitem
Only return files not associated with any item.
- excludeQueued –
true
(default if searching importable files) - Exclude the files that are queued for importfalse
(default if searching all files) - Do not exclude the files that are queued for import
Produces: - application/xml, application/json – An ImportableFileListDocument describing the job.
Role: _storage_read
Same query and matrix parameters as for List files in storage.
- auto –
Importing a file from a storage¶
Start an import job¶
-
POST
{file-resource}/import
¶ Starts a an import job that will import the specified file. Only files that do not belong to any components can be imported.
Query Parameters: - filename – The original filename of the file.
- allowReimport –
true
- Import the file to this shape even if the file is already importing or is already part of another item.false
(default) Reject the request if the file with the given id has already been imported or is currently importing.
- id – A comma-delimited list of external ids to assign to the item.
- tag – An optional list of shape tags to use for transcoding.
- original – An optional tag, if specified it should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
- createThumbnails –
true
(default) - Generate thumbnails as per defined by shape tag.false
- Disable thumbnail generation.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- createPosters – An optional list of time codes to use for creating posters.
- no-transcode –
true
- Will disable transcoding even if thetags
parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.false
(default) - Normal transcode.
- overrideFastStart –
true
(default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.false
- Do not use the transcoder’s estimate of the duration.
- requireFastStart –
true
(default) - Try to put the index tables (header) in front of the file.false
- Put header at end of file.
- fastStartLength – Optional estimated duration of the clip in seconds.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
- settings – Pre-configured import settings. See Import settings
Accepts: - application/xml, application/json – MetadataDocument, initial metadata that is given to the imported item.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Start an import job of an IMF package¶
-
POST
{file-resource}/import/assetmap
¶ Starts a an import job that will import an
ASSETMAP
file (SMPTE ST 429-9). Files pointed to by the assetmap (DCP/InterOp or SMPTE) has to be stored in the same directory.Query Parameters: - allowReimport –
true
- Import the file to this shape even if the file is already importing or is already part of another item.false
(default) Reject the request if the file with the given id has already been imported or is currently importing.
- id – A comma-delimited list of external ids to assign to the item.
- tag – An optional list of shape tags to use for transcoding.
- original – An optional tag, if specified it should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
- createThumbnails –
true
(default) - Generate thumbnails as per defined by shape tag.false
- Disable thumbnail generation.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- createPosters – An optional list of time codes to use for creating posters.
- no-transcode –
true
- Will disable transcoding even if thetags
parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.false
(default) - Normal transcode.
- overrideFastStart –
true
(default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.false
- Do not use the transcoder’s estimate of the duration.
- requireFastStart –
true
(default) - Try to put the index tables (header) in front of the file.false
- Put header at end of file.
- fastStartLength – Optional estimated duration of the clip in seconds.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
- settings – Pre-configured import settings. See Import settings
Accepts: - application/xml, application/json – MetadataDocument, initial metadata that is given to the imported item.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
- allowReimport –
Start an import job from path¶
New in version 4.10.
-
POST
{storage-resource}/file/import
¶ Starts a an import job that will import the specified file. Only files that do not belong to any components can be imported.
Query Parameters: - path – The path of the file on the storage. Mandatory.
- uri – The absolute file URI (should be relative to the URI of a storage method).
- state – The state of the file. Default is
CLOSED
. - createOnly –
true
- Fail if a file with that path already exists.false
(default) - Update the existing file if one exists, else create a new file entity.
- filename – The original filename of the file.
- allowReimport –
true
- Import the file to this shape even if the file is already importing or is already part of another item.false
(default) Reject the request if the file with the given id has already been imported or is currently importing.
- id – A comma-delimited list of external ids to assign to the item.
- tag – An optional list of shape tags to use for transcoding.
- original – An optional tag, if specified it should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
- createThumbnails –
true
(default) - Generate thumbnails as per defined by shape tag.false
- Disable thumbnail generation.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- createPosters – An optional list of time codes to use for creating posters.
- no-transcode –
true
- Will disable transcoding even if thetags
parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.false
(default) - Normal transcode.
- overrideFastStart –
true
(default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.false
- Do not use the transcoder’s estimate of the duration.
- requireFastStart –
true
(default) - Try to put the index tables (header) in front of the file.false
- Put header at end of file.
- fastStartLength – Optional estimated duration of the clip in seconds.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
- settings – Pre-configured import settings. See Import settings
Accepts: - application/xml, application/json – MetadataDocument, initial metadata that is given to the imported item.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Start an import job of an IMF package from path¶
New in version 4.10.
-
POST
{storage-resource}/file/import/assetmap
¶ Starts a an import job that will import an
ASSETMAP
file (SMPTE ST 429-9). Files pointed to by the assetmap (DCP/InterOp or SMPTE) has to be stored in the same directory.Query Parameters: - path – The path of the file on the storage. Mandatory.
- uri – The absolute file URI (should be relative to the URI of a storage method).
- state – The state of the file. Default is
CLOSED
. - createOnly –
true
- Fail if a file with that path already exists.false
(default) - Update the existing file if one exists, else create a new file entity.
- allowReimport –
true
- Import the file to this shape even if the file is already importing or is already part of another item.false
(default) Reject the request if the file with the given id has already been imported or is currently importing.
- id – A comma-delimited list of external ids to assign to the item.
- tag – An optional list of shape tags to use for transcoding.
- original – An optional tag, if specified it should be one of the tags specified in the tag parameter. Specifies that the original shape tag will be reset to the shape created to this tag.
- createThumbnails –
true
(default) - Generate thumbnails as per defined by shape tag.false
- Disable thumbnail generation.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- createPosters – An optional list of time codes to use for creating posters.
- no-transcode –
true
- Will disable transcoding even if thetags
parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.false
(default) - Normal transcode.
- overrideFastStart –
true
(default) - Use transcoder’s estimate of the duration for allocating header space in MOV files and similar files.false
- Do not use the transcoder’s estimate of the duration.
- requireFastStart –
true
(default) - Try to put the index tables (header) in front of the file.false
- Put header at end of file.
- fastStartLength – Optional estimated duration of the clip in seconds.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
- settings – Pre-configured import settings. See Import settings
Accepts: - application/xml, application/json – MetadataDocument, initial metadata that is given to the imported item.
Produces: - application/xml, application/json – A JobDocument that describes the import job.
Role: _import
Move/copy/delete files from a storage¶
Create a file move/copy job¶
-
POST
{file-resource}/storage/
(target-storage-id)¶ Starts a move or copy job for the specified file.
Query Parameters: - move –
true
- Delete the original file when the copy has finished.false
- Just copy the file, and leave the original.
- filename – Optional filename, the desired target filename.
- useOriginalFilename – If set to true, the file will keep its original filename if available.
- timeRequirement – Optional number of seconds the target file is required to exist before being moved due to storage rules etc.
- limitRate – (New in 4.0.) Optional integer, throttle the rate at which the transfer takes place (bytes/second).
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
Role: _file_write
- move –
Create a file delete job¶
-
DELETE
{file-resource}
¶ Starts a delete job for the specified file.
Query Parameters: - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
Role: _file_write
Managing files¶
Create a file entity in the database¶
-
POST
{storage-resource}/file
¶ Creates a file entity in the database. Does not create any physical files. Either a storage id and path or an absolute URI may be given.
Query Parameters: - path – The path of the file on the storage.
- uri – The absolute file URI (should be relative to the URI of a storage method).
- state – The state of the file. Default is
OPEN
. - createOnly –
true
(default) - Fail if a file with that path already exists.false
- Update the existing file if one exists, else create a new file entity.
Status Codes: - 409 Conflict – If
createOnly=true
and a file with that path already exists.
Produces: - application/xml, application/json – FileDocument
- text/plain – The id of the new or updated file.
-
POST
{storage-resource}/file
¶ Creates a file entity in the database. Does not create any physical files. Either a storage id and path or an absolute URI may be given.
Query Parameters: - createOnly –
true
(default) - Fail if a file with that path already exists.false
- Update the existing file if one exists, else create a new file entity.
Status Codes: - 409 Conflict – If
createOnly=true
and a file with that path already exists.
Accepts: - application/xml, application/json – FileDocument with the path or uri and file state.
Produces: - application/xml, application/json – FileDocument
- text/plain – The id of the new or updated file.
- createOnly –
Delete a file entity from the database¶
-
DELETE
{file-resource}/entity
¶ Deletes a file entity from the database. Does not touch the physical file.
Role: _file_write
Set new file path¶
-
POST
{file-resource}/path
¶ Query Parameters: - storage – Optional storage id. The new storage, if omitted, the same storage.
- path – The new path. Required.
- state – Optional new state of the file. (OPEN, CLOSED, etc).
- duplicate –
true
- The file at the target path is a duplicate of this file. The old file entity will NOT be removed.false
(default) - This target path is the new location. This old file entity will be removed.
New in version 4.2.12.
Produces: - application/xml, application/json – FileDocument
- text/plain – File id
Role: _file_write
Semantics¶
This command is used when a file is moved manually (without Vidispine), and caller wants to register the new path.
The path of file entities in Vidispine is immutable. The command above registers a new file, with the new path, and change all relevant components to point to the new file instead. The old file is marked for deletion. Hence, caller should first do the physical move, then issue this command.
New in version 4.2.12: Use the duplicate
parameter to add another file as a duplicate. The
file at the new location will be added to all components that the file
is already a part of. No file entities will be removed.
Set file state¶
-
PUT
{file-resource}/state/
(state)¶ Parameters: - state – The new state of the file.
Produces: - application/xml, application/json – The resulting FileDocument
- text/plain – The id of the file.
Example:
PUT /storage/file/VX-12/state/CLOSED
<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<id>VX-432</id>
<path>sample.mov</path>
<uri>file:///srv/media1/sample.mov</uri>
<state>CLOSED</state>
<size>7889811</size>
<hash>5eb9646332c96c738b4cacf7bc110d4cd8523ed5</hash>
<timestamp>2016-03-24T17:02:53.796+01:00</timestamp>
<refreshFlag>1</refreshFlag>
<storage>VX-1</storage>
</FileDocument>
Unassociate a file with an item¶
-
PUT
{file-resource}/abandon
¶ Unassociates (disconnects) the physical file from the item. The shape which the file resided in will still exist, but there is no longer any connection between the file and the shape or item.
Query Parameters: - item – The item from which the file in unassociated
Role: _file_write
Re-index file¶
-
PUT
{file-resource}/re-index
¶ Queues a single file for re-index.
Produces: - text/plain –
See Re-indexing metadata if you wish to reindex all files in the system.