Document toolboxDocument toolbox

Vidispine

Files [VC 21.3 GEN]

Owned by Andreas Schmidt
Aug 31, 2021
21 min read

Manage files on a storage.

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:

  • /file/{file-id}

  • {storage-resource}/file/{file-id}

  • {storage-resource}/file/path/{path}

  • {storage-resource}/file/uri/{uri}

Information about files in storage

List all files in a storage

GET {storage-resource}/file

Retrieves the files for all or a specific storage.

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.

Query Parameters:

  • id (string[]) – If multiple id query parameters are specified only those files are returned. If no ids are specified, all files are returned.

  • path (string) –

    • path - Return files under this sub-path to storage.

    • / (default) - Return all files.

  • prefix (boolean) –

    • true - Also include file prefixes that matches the criteria

    • false (default) - Do not include file prefixes

  • ignorecase (boolean) –

    • true - Search file path case insensitively

    • false - Search file path case sensitively

  • recursive (boolean) –

    • true (default) - Return all files in tree.

    • false - Return only files directly under specified path.

  • wildcard (boolean) –

    • true - Allow use of wildcards in path.

    • false (default) - No wildcard handling of path.

  • first (integer) – From total list of files, start return list from specified number. Default is 0.

  • cursor (string) –

    New in version 4.16.

    • * - The initial cursor.

    • string-from-search - Cursor string returned from the search results.

    If set, the cursorMark / search after features from Solr/Elasticsearch would be used to improve the deep paging performance during a search.

    When cursor is used, The value of first will be ignored.

    Changed in version 5.5.

    Starting in 5.5, cursor is returned for the end of the result instead of null to enable tailing search.

  • number (integer) – Return a maximum of specified number of files. Default is 10.

  • prefixFirst (integer) –

    From total list of prefixes, start return list from specified number. Default is 0.

    Note: this parameter has no effect if Elasticsearch is the search backend.

  • prefixNumber (integer) – Return a maximum of specified number of prefixes. Default is 10.

  • sort (string) –

    Comma-separated list. Use as: fileId desc,size desc,state desc.

    • 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 state.

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

  • storage (string[]) – List of storage ids. Return only files from specific storages. Same as storage-id in URL, but can be specified multiple times

  • storageGroup (string) – Storage group id. Return only files from storages specified in the storage group

  • filter (string) –

    • all (default) - Return all files

    • item Only return files associated with an item.

    • noitem Only return files not associated with any item.

  • hash (string[]) – List of hash values. Only return files with specific hash value.

  • algorithm (string) – Hash algorithm. Search for hash values used by specified algorithm

  • count (boolean) –

    • 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

  • state (string[]) – Filter results by file state. Can be used multiple times to select several states.

  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.

  • storageType (string) – Only return URIs for files from storages of this type.

  • methodMetadata (string[]) – metadata used with storage method.

  • scheme (string) – URI scheme to return.

  • includeItem (boolean) –

    • true - Return associated items, shapes, and components.

    • false (default) - Do not return any information about associated items, shapes, and components.

  • excludeQueued (boolean) –

    • true - Exclude the files that are queued for import

    • false (default) - Do not exclude the files that are queued for import
Produces:

  • application/xml, application/json – FileListDocument

  • text/plain – CRLF-delimited list of file ids
Role:

_file_read

File search 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

Prefix search example

Assuming there is a file app/Phone/Android/Oreo/GoolgePlay.txt inside a storage, the result of some prefix search requests will be as follows:

GET /storage/{storage-id}/file?prefix=true
<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <file>
  ...
  </file>
  <prefixes>
    <prefix>apps/Phone/Android/Oreo/</prefix>
  </prefixes>
</FileDocument>
GET /storage/{storage-id}/file?prefix=true&recursive=false
<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <file>
  ...
  </file>
  <prefixes>
    <prefix>apps/</prefix>
  </prefixes>
</FileDocument>
GET /storage/{storage-id}/file?prefix=true&recursive=false&path=apps/
<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <!-- The file list will be empty in this case -->
  <prefixes>
    <prefix>apps/Phone/</prefix>
  </prefixes>
</FileDocument>

In the case of wildcard=true and recursive=false, only the levels before the first wildcard character will be returned. So in the example below, apps/ will be returned, instead of apps/Phone/ or apps/Phone/Android/

GET /storage/{storage-id}/file?prefix=true&recursive=false&wildcard=true&path=app/*Oreo*
<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <file>
  ...
  </file>
  <prefixes>
    <prefix>apps/</prefix>
  </prefixes>
</FileDocument>

Retrieve a file

GET {file-resource}

Retrieves the information, such as file size, status and checksum, of a specific file.

Query Parameters:

  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.

  • storageType (string) – Only return URIs for files from storages of this type.

  • methodMetadata (string[]) – metadata used with storage method.

  • scheme (string) – URI scheme to return.

  • includeItem (boolean) –

    • true - Return associated items, shapes, and components.

    • false (default) - Do not return any information about associated items, shapes, and components.

  • includeShapes (boolean) –

    New in version 5.3.

    • true - Include shapes deduced by File Analyze Jobs. A ShapeListDocument will be included in the metadata with key faj_included_shapes. The format of the document respects the Accept header.

    • false (default) - Do not include shapes.
Produces:

  • application/xml, application/json – FileDocument

  • text/plain – Tabbed tuples of file id, file path, file size, file status, timestamp
Role:

_file_read

Upload a file to a storage

POST {storage-resource}/file/data

Creates a new file on a specific storage, with the given file data.

Query Parameters:

  • transferPriority (integer) – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers. A transfer with a high priority value is considered more important than a transfer with a low priority value.

  • transferId (string) – An id to assign the transfer to be able to refer to it.

  • path (string) – The path of the file on the storage.

  • uri (string) – The absolute file URI (should be relative to the URI of a storage method).

  • state (string) – The state of the file.
Status Codes:

  • 400 – If the amount of data received does not match the given Content-Length header.
Accepts:

  • application/octet-stream – The raw essence data.
Produces:

  • application/xml, application/json – FileDocument

  • text/plain – file id
Role:

_file_write

File data

Retrieve the file data

GET {file-resource}/data

Retrieves the raw file data.

Produces:

  • application/octet-stream – The raw file data.
Role:

_file_read

Update or create file data

POST {file-resource}/data

Uploads the file data for a specific file, overwriting any existing file data for the file.

Query Parameters:

  • transferPriority (integer) – An integer between 1 and 1000 that indicates what priority the transfer should be given in relation to other transfers. A transfer with a high priority value is considered more important than a transfer with a low priority value.

  • transferId (string) – An id to assign the transfer to be able to refer to it.
Status Codes:

  • 400 – If the amount of data received does not match the given Content-Length header.
Accepts:

  • application/octet-stream – The raw file data.
Produces:
Role:

_file_write

Generate temporary credentials

New in version 4.15.

POST {file-resource}/uri

Generates temporary access credentials that give either READ or WRITE access directly to the file. By default, if the file is on S3 or Azure, this will try to create a read-only pre-signed URL for the file; if this fail or if the file is on another type of storage, it will try to create a proxy URL (with direct access to the file).

Please note that these generated credentials will only allow access to the exact same key / filename, to use the examples below it would be image.jpg. You will not be able to read or write another key / filename using these credentials.

Amazon S3

When using the s3 scheme there are certain prerequisites that need to be met regarding policies and trust relationships with the account in use.

  • If you specify which role to use by setting the stsAssumeRole property, you must make sure that this role have the permission policy to be able to assume the role (sts:AssumeRole) and that the policy allows to get the role (iam:GetRole).

  • If you want to rely on Vidispine to find a role attached to an EC2 instance profile (by leaving the stsAssumeRole property unset), you must make sure that the policy allows for getting the EC2 instance profile (iam:GetInstanceProfile) and to get the attached role (iam:GetRole) and also the permission to assume this role (sts:AssumeRole).

The permission policy for the role will only require s3:GetObject and s3:PutObject permissions to use the basic features. If you intend to use this for multipart uploads you might also want to add the permissions for s3:ListMultipartUploadParts and s3:AbortMultipartUpload. Finally this role will also need a trust relationship with an account with access to the storage(s) as an intersection is made to decide permissions in the end.

Vidispine will then create a custom policy to limit the credentials to either GET or PUT as requested.

When using s3 scheme, by default, the duration of the temporary security credentials for the role in AWS lasts for one hour. In order to use longer durations, the maximum session duration in AWS has to be increased. To learn how to view the maximum value for your role, see View the Maximum Session Duration Setting for a Role in the IAM User Guide.

If the s3 scheme is used, any transfer in progress when the duration ends will be interrupted, unlike pre-signed s3 URL’s that would allow the file to be fully downloaded even if the duration would expire during transfer.

Query Parameters:

  • scheme (string) –

    Determines which type of URL / URI to be returned.

    • s3 Utilize AWS’s AssumeRole to generate a temporary URI giving access to only the specific file. Can be used either by setting the stsAssumeRole property to specify which role to assume when generating the credentials OR by leaving this unset which will make Vidispine try to use a role from an EC2 instance profile. These will also look at the configuration property for stsRegion and use that region when making the call to the STS API.

    • https (default) - Generates a temporary pre-signed HTTPS URL for either S3 or Azure, or a proxy URL (based on the configuration property apiNoauthUri) if on another type of storage.

    • http - Same as https but will also allow HTTP URL’s to be returned.

  • write (boolean) –

    Sets permission to either READ or WRITE.

    • true - Will give credentials with access to write. This would also enable the optional permissions for s3:ListMultipartUploadParts and s3:AbortMultipartUpload if used together with the s3 scheme.

    • false (default) - Will give credentials with access to read.

  • duration (integer) –

    Optional, sets the duration of the temporary credentials in minutes. Default is set to 15 minutes and the maximum is 720.

    Changed in version 4.17.7: The minimum duration for pre-signed URLs is 1 minute and when using the S3 scheme the minimum is 15 minutes.

  • sse-kms (boolean) –

    New in version 5.6.

    Set this to enable the pre-signed url to write a SSE-KMS encrypted file. Please note that this will only work together with the https scheme.

    • true - Enable SSE-KMS for the written file. The AWS managed CMK for S3 will be used to encrypt the file unless a kmsKeyId is specified.

    • false (default) - The file will be written without SSE-KMS.

  • kmsKeyId (string) –

    New in version 5.6.

    The id of a customer managed CMK to use in SSE-KMS
Produces:
Role:

_file_write

Examples

To generate a writeable S3 URL with temporary credentials:

The user id and secret key will be replaced with the generated temporary credentials in the returned URI.

POST /storage/file/VX-56/uri?scheme=s3&write=true
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>s3://ASIA....:...@example/image.jpg?sessionToken=...</uri>
</URIListDocument>

To generate a pre-signed HTTPS URL (or proxy URL depending on the type of storage):

POST /storage/file/VX-98/uri?scheme=https&write=true
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>https://example.blob.core.windows.net/image.jpg?sig=...</uri>
</URIListDocument>

Importable files

List all 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.

Same query parameters as for GET {storage-resource}/file.

Query Parameters:

  • auto (boolean) –

    • true - Return files that will be automatically imported due to auto-import rules.

    • false (default) - Do not return files that will be automatically imported.

  • excludeQueued (boolean) –

    • true (default) - Exclude the files that are queued for import

    • false - Do not exclude the files that are queued for import

  • id (string[]) – If multiple id query parameters are specified only those files are returned. If no ids are specified, all files are returned.

  • path (string) –

    • path - Return files under this sub-path to storage.

    • / (default) - Return all files.

  • prefix (boolean) –

    • true - Also include file prefixes that matches the criteria

    • false (default) - Do not include file prefixes

  • ignorecase (boolean) –

    • true - Search file path case insensitively

    • false - Search file path case sensitively

  • recursive (boolean) –

    • true (default) - Return all files in tree.

    • false - Return only files directly under specified path.

  • wildcard (boolean) –

    • true - Allow use of wildcards in path.

    • false (default) - No wildcard handling of path.

  • first (integer) – From total list of files, start return list from specified number. Default is 0.

  • cursor (string) –

    New in version 4.16.

    • * - The initial cursor.

    • string-from-search - Cursor string returned from the search results.

    If set, the cursorMark / search after features from Solr/Elasticsearch would be used to improve the deep paging performance during a search.

    When cursor is used, The value of first will be ignored.

    Changed in version 5.5.

    Starting in 5.5, cursor is returned for the end of the result instead of null to enable tailing search.

  • number (integer) – Return a maximum of specified number of files. Default is 10.

  • prefixFirst (integer) –

    From total list of prefixes, start return list from specified number. Default is 0.

    Note: this parameter has no effect if Elasticsearch is the search backend.

  • prefixNumber (integer) – Return a maximum of specified number of prefixes. Default is 10.

  • sort (string) –

    Comma-separated list. Use as: fileId desc,size desc,state desc.

    • 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 state.

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

  • storage (string[]) – List of storage ids. Return only files from specific storages. Same as storage-id in URL, but can be specified multiple times

  • storageGroup (string) – Storage group id. Return only files from storages specified in the storage group

  • filter (string) –

    • all (default) - Return all files

    • item Only return files associated with an item.

    • noitem Only return files not associated with any item.

  • hash (string[]) – List of hash values. Only return files with specific hash value.

  • algorithm (string) – Hash algorithm. Search for hash values used by specified algorithm

  • count (boolean) –

    • 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

  • state (string[]) – Filter results by file state. Can be used multiple times to select several states.

  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.

  • storageType (string) – Only return URIs for files from storages of this type.

  • methodMetadata (string[]) – metadata used with storage method.

  • scheme (string) – URI scheme to return.
Produces:
Role:

_storage_read

Importing a file from a storage

Import a file

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 (string) – The original filename of the file.

  • allowReimport (boolean) –

    • 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 (string) – Comma-delimited list of external ids to assign to the item.

  • tag (string[]) – A list of shape tags to use for transcoding.

  • original (string) – If specified, 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 (boolean) –

    • true (default) - Generate thumbnails as per defined by shape tag.

    • false - Disable thumbnail generation.

  • thumbnailService (string) – Identifies which thumbnail resource that should be used.

  • createPosters (string) – A list of time codes to use for creating posters.

  • no-transcode (boolean) –

    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.

    • false (default) - Normal transcode.

  • resourceId (string) – The transcoder resource to use to execute the transcode.

  • overrideFastStart (boolean) –

    • 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 (boolean) –

    • true (default) - Try to put the index tables (header) in front of the file.

    • false - Put header at end of file.

  • fastStartLength (string) – Estimated duration of the clip in seconds.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.

  • settings (string) – Pre-configured import settings.

  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
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

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

Changed in version 5.3: IMF packages will now be validated using Photon and results saved as metadata on the item. Can be disabled with jobMetadata parameter.

Query Parameters:

  • allowReimport (boolean) –

    • 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 (string) – Comma-delimited list of external ids to assign to the item.

  • tag (string[]) – A list of shape tags to use for transcoding.

  • original (string) – If specified, 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 (boolean) –

    • true (default) - Generate thumbnails as per defined by shape tag.

    • false - Disable thumbnail generation.

  • thumbnailService (string) – Identifies which thumbnail resource that should be used.

  • createPosters (string) – A list of time codes to use for creating posters.

  • no-transcode (boolean) –

    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.

    • false (default) - Normal transcode.

  • overrideFastStart (boolean) –

    • 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 (boolean) –

    • true (default) - Try to put the index tables (header) in front of the file.

    • false - Put header at end of file.

  • fastStartLength (string) – Estimated duration of the clip in seconds.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.

  • settings (string) – Pre-configured import settings.

  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
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

The IMF import job accepts certain special jobMetadata parameters:

skipImpValidation

If set to true, do not perform Photon IMF package validation.

New in version 5.3.

Import a file using a path

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 (string) – Required. The path of the file on the storage.

  • uri (string) – The absolute file URI (should be relative to the URI of a storage method).

  • state (string) – The state of the file. Default is CLOSED.

  • createOnly (boolean) –

    • 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 (string) – The original filename of the file.

  • allowReimport (boolean) –

    • 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 (string) – Comma-delimited list of external ids to assign to the item.

  • tag (string[]) – A list of shape tags to use for transcoding.

  • original (string) – If specified, 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 (boolean) –

    • true (default) - Generate thumbnails as per defined by shape tag.

    • false - Disable thumbnail generation.

  • thumbnailService (string) – Identifies which thumbnail resource that should be used.

  • createPosters (string) – A list of time codes to use for creating posters.

  • no-transcode (boolean) –

    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.

    • false (default) - Normal transcode.

  • resourceId (string) – The transcoder resource to use to execute the transcode.

  • overrideFastStart (boolean) –

    • 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 (boolean) –

    • true (default) - Try to put the index tables (header) in front of the file.

    • false - Put header at end of file.

  • fastStartLength (string) – Estimated duration of the clip in seconds.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.

  • settings (string) – Pre-configured import settings.

  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
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

Import an IMF package using a path

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.

Changed in version 5.3: IMF packages will now be validated using Photon and results saved as metadata on the item. Can be disabled with jobMetadata parameter.

Query Parameters:

  • path (string) – Required. The path of the file on the storage.

  • uri (string) – The absolute file URI (should be relative to the URI of a storage method).

  • state (string) – The state of the file. Default is CLOSED.

  • createOnly (boolean) –

    • 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 (boolean) –

    • 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 (string) – Comma-delimited list of external ids to assign to the item.

  • tag (string[]) – A list of shape tags to use for transcoding.

  • original (string) – If specified, 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 (boolean) –

    • true (default) - Generate thumbnails as per defined by shape tag.

    • false - Disable thumbnail generation.

  • thumbnailService (string) – Identifies which thumbnail resource that should be used.

  • createPosters (string) – A list of time codes to use for creating posters.

  • no-transcode (boolean) –

    • true - Will disable transcoding even if the tags parameter is set. Rather, the specified tag will be used to determine cropping, scaling etc. of thumbnails.

    • false (default) - Normal transcode.

  • overrideFastStart (boolean) –

    • 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 (boolean) –

    • true (default) - Try to put the index tables (header) in front of the file.

    • false - Put header at end of file.

  • fastStartLength (string) – Estimated duration of the clip in seconds.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.

  • settings (string) – Pre-configured import settings.

  • importTag (string[]) – A list of shape tags that the created shape will be associated with. Default is original.
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

The IMF import job accepts certain special jobMetadata parameters:

skipImpValidation

If set to true, do not perform Photon IMF package validation.

New in version 5.3.

Move/copy/delete files from a storage

Move/copy a file to another storage

POST {file-resource}/storage/(target-storage-id)

Starts a move or copy job for the specified file.

Query Parameters:

  • move (boolean) –

    • true - Delete the original file when the copy has finished.

    • false - Just copy the file, and leave the original.

  • filename (string) – The desired target filename.

  • useOriginalFilename (boolean) – If set to true, the file will keep its original filename if available. Default is false.

  • timeRequirement (integer) – Number of seconds the target file is required to exist before being moved due to storage rules etc.

  • limitRate (integer) – Throttle the rate at which the transfer takes place (bytes/second).

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_file_write

Delete a file

DELETE {file-resource}

Starts a delete job for the specified file.

Query Parameters:

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_file_write

Managing files

Register a 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:

  • path (string) – The path of the file on the storage.

  • uri (string) – The absolute file URI (should be relative to the URI of a storage method).

  • state (string) – The state of the file. Default is OPEN.

  • createOnly (boolean) –

    • 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 (boolean) –

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

Unregister a file

DELETE {file-resource}/entity

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

Role:

_file_write

Register a new file path

POST {file-resource}/path

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.

The path of file entities in Vidispine is immutable. This command is used when a file is moved manually (without Vidispine), and caller wants to register the new path.

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.

Query Parameters:

  • storage (string) – The new storage, if omitted, the same storage.

  • path (string) – Required. The new path.

  • state (string) – New state of the file. (OPEN, CLOSED, etc).

  • duplicate (boolean) –

    • 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.
Produces:

  • application/xml, application/json – FileDocument

  • text/plain – File id
Role:

_file_write

Update the file state

PUT {file-resource}/state/(state)

Changes the state of the specified file to the given state.

Can for example be used after writing a file to a storage, to immediately mark it as CLOSED and no longer growing.

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>

Remove a file from an item

PUT {file-resource}/abandon

Disassociates (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 (string) – The item from which the file in unassociated
Role:

_file_write

Set file hash

New in version 5.0.

PUT {file-resource}/hash/(hash)

Set a new hash value of a file.

Query Parameters:

  • algorithm (string) – Hash algorithm of the new hash. If omitted, the default SHA-1 hash is set.
Role:

_file_write

Re-index a 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.

Shape deduction on files

Perform shape deduction on a file

POST {file-resource}/analyze

New in version 5.3.

Start a job that will deduce the shape of a file without importing it. The resulting shape can be found as a ShapeDocument in the jobmetadata and can be retrieved from the file when the job has completed. Shape deduction will still run as normal during import of the file even if it has already been performed on the file through this job. Running this job will not affect any shapes associated with this file that have been created trough other means (e.g. shape created by import). Note that the result from this shape deduction job is not as extensive as running an analyze job on an imported shape. See Shape analysis.

Query Parameters:

  • resourceId (string) – The transcoder resource to use to execute the analysis.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_job_write
Role:

_file_write

Perform shape deduction on an IMF package

POST {file-resource}/analyze/imp

New in version 5.3.

Start a job that will deduce the shape of an IMF package without importing it. The file resource must be the ASSETMAP.xml. Files pointed to by the ASSETMAP has to be stored in the same directory. Multiple CPLs will produce multiple shapes. The resulting shapes can be found as a ShapeListDocument in the jobmetadata and can be retrieved from the ASSETMAP file and CPL files when the job has completed. Shape deduction will still run as normal during import of the file even if it has already been performed on the file through this job. Running this job will not affect any shapes associated with this file that have been created trough other means (e.g. shape created by import). Note that the result from this shape deduction job is not as extensive as running an analyze job on an imported shape. See Shape analysis.

Query Parameters:

  • resourceId (string) – The transcoder resource to use to execute the analysis.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_job_write
Role:

_file_write

Get shapes for a file

GET {file-resource}/shape

New in version 5.3.

Retrieve shapes that have been created by a shape deduction analysis of the file.

Produces:

  • application/xml, application/json – ShapeListDocument
Role:

_file_read