Files

Information about files in storage

List files in storage

New in version 4.1.2.

GET /storage/(storage-id)/file
Query Parameters:
 
  • path

    Optional string

    • path - Return files under this sub-path to storage.
    • / (default) - Return all files.
  • id – Optional comma-separated list of file ids to return. If not specified, all files are returned.
  • recursive
    • true - Return all files in tree.
    • false - Return only files directly under specified path.
  • wildcard
    • true - Allow use of wildcards in path.
    • false - No wildcard handling of path.
  • type – Optional method type, see Storage methods. Return URLs with a particular methodType. By default, return URLs with empty methodType.
  • 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 result
    • false - Do not return total number of hits in result, in order to produce results faster
Matrix Parameters:
 
  • start – 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.
  • filter
    • all (default) - Return all files
    • item Only return files associated with an item.
    • noitem Only return files not associated with any item.
  • includeItem
    • true - Return associated items, shapes, and components
    • false (default) - Do not return any information about associated items, shapes, and components
  • excludeQueued
    • true (default if searching importable files) - Exclude the files that are queued for import
    • false (default if searching all files) - Do not exclude the files that are queued for import
  • ignorecase
    • true - Search file path case insensitively
    • false - Search file path case sensitively
  • sort

    Optional comma-separated list.

    • fileId [ asc (default) | desc ] (default) - Order results by file id
    • size [ asc (default) | desc ] - Order results by file size (bytes)
    • state [ asc (default) | desc ] - Order results by File States
    • timestamp [ asc (default) | desc ] - Order results by file timestamp
    • filename [ asc (default) | desc ] - Order results by filename
    • extension [ 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
Produces:
  • application/xml, application/jsonFileListDocument
  • text/plain – CRLF-delimited list of file ids
Role:

_file_read

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:

  1. Empty string = /.
  2. The initial / is implicit.
  3. / is the path delimiter in Vidispine, also on Windows.
  4. ? = exactly one.
  5. * = 0 or more
  6. ? is not officially supported, see URI’s, URL’s, and Special Characters.
  7. With wildcard=false, \ is literal. However, \ is not officially supported, see URI’s, URL’s, and Special Characters.
  8. 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 /storage/(storage-id)/file/(file-id)
Query Parameters:
 
  • methodType

    Type of access method.

    • AUTO - Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.
    • AZURE_SAS - (New in 4.0.1.) If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
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/jsonFileDocument
  • text/plainTabbed tuples of file id, file path, file size, file status, timestamp
Role:

_file_read

Upload file to storage

New in version 4.1.2.

POST /storage/(storage-id)/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.
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:
  • text/plain – file id
Role:

_file_write

Set new file path

POST /storage/(storage-id)/file/(file-id)/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/jsonFileDocument
  • 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.

Get information about item-file relationship

GET /storage/(storage-id)/file/(file-id)/item ...

Return items belonging to id. See Identifiers.

Matrix Parameters:
 
  • uri – Absolute URI to file. Must exactly match one of the method URIs defined for the storage.
  • path – Relative path to file

File data

Get file data

GET /storage/(storage-id)/file/(file-id)/data
Produces:
  • */* – Can be anything, really
Role:

_file_read

Upload file data

New in version 4.1.2.

POST /storage/(storage-id)/file/(file-id)/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 essence data.
Produces:
Role:

_file_write

Importable files

Get files that can be imported

GET /storage/importable

Retrieves a list of files, together with any found metadata, for files that do not belong to any component.

Produces:
Role:

_storage_read

Same query and matrix parameters as for List files in storage.

Importing a file from a storage

Start an import job

POST /storage/(storage-id)/file/(file-id)/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:
 
  • ids – 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.
  • thumbnails
    • 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.
  • 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
Accepts:
  • application/xml, application/jsonMetadataDocument, 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 /storage/(source-storage-id)/file/(file-id)/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
  • timeDependency – Option 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:
Role:

_file_write

Create a file delete job

DELETE /storage/(source-storage-id)/file/(file-id)

Starts a delete job for the specified file.

Query Parameters:
 
Produces:
Role:

_file_write

Delete a file entity from the database

DELETE /storage/(source-storage-id)/file/(file-id)/entity

Deletes a file entity from the database. Does not touch the physical file.

Role:_file_write

Unassociate a file with an item

PUT /storage/(source-storage-id)/file/(file-id)/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