Key-value metadata [VC 21.3.1 GEN]

Some resources support basic key-value metadata (not to be confused with item metadata). This metadata is not indexed nor is it revision controlled. The role required to use the metadata depends on the resource.

Keys can be hierarchical, meaning the key can include the slash character.

Changed in version 4.16: Support for key-value metadata was added to shape-tags, libraries and task-definitions.

Supported resources

The resources that support key-value metadata, and the roles required to read and write to them can be seen in the table below. These are referred to as {key-value-metadata-resources}.

Resource	URI	Read role	Write role
Groups	`/group/{group-name}/metadata`	`_group_read`	`_group_write`
Users	`/user/{username}/metadata`	`_admininstrator` (or none for user’s own data)	`_administrator` (or `_user_metadata_write` for user’s own data)
Storages	`/storage/{storage-id}/metadata`	`_storage_read`	`_storage_write`
Storage methods	`/storage/{storage-id}/method/{method-id}/metadata`	`_storage_read`	`_storage_write`
Storage groups	`/storage/storage-group/{storagegroup-name}/metadata`	`_storage_group_read`	`_storage_group_write`
Metadata fields	`/metadata-field/{field-name}/metadata`	`_metadata_field_read`	`_metadata_field_write`
Metadata field groups	`/metadata-field/field-group/{group-name}/metadata`	`_metadata_field_group_read`	`_metadata_field_group_write`
Shapes	`/item/{item-id}/shape/{shape-id}/metadata`	`_shape_read`	`_shape_write`
Shape components	`/item/{item-id}/shape/{shape-id}/component/{component-id}/metadata`	`_shape_read`	`_shape_write`
Files	`/storage/{storage-id}/file/{file-id}/metadata`	`_file_read`	`_file_write`
Task groups	`/task-group/{groupname}/metadata`	`_admininstrator`	`_admininstrator`
Libraries	`/library/{library-id}/metadata`	`_library_read`	`_library_write`
Shape tags	`/shape-tag/{tag-name}/metadata`	`_shape_tag_read`	`_shape_tag_write`
Task definitions	`/task-definition/{task-id}/metadata`	`_taskdefinition_read`	`_taskdefinition_write`

Managing key-value metadata

Retrieve all metadata

GET {key-value-metadata-resource}

Retrieves all key-value pairs associated with the specified entity.

Produces:

application/xml, application/json – A SimpleMetadataDocument containing all key-value pairs.

Example

NONE

GET /user/myuser/metadata

HTML/XML

<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>occupation</key>
    <value>developer</value>
  </field>
  <field>
    <key>location</key>
    <value>London</value>
  </field>
</SimpleMetadataDocument>

Retrieve all metadata for a subtree

GET {key-value-metadata-resource}/(keypath)

Retrieves all key-value pairs associated with the specified key path. The key path can contain \* for a wildcard segment, or \*\* for any number of arbitrary segments.

Produces:

application/xml, application/json – A SimpleMetadataDocument containing all key-value pairs matching.

Example

NONE

GET /user/myuser/metadata/**/id

Create multiple key-value pairs

PUT {key-value-metadata-resource}

Sets all the specified key-value pairs.

Accepts:

application/xml, application/json – SimpleMetadataDocument

PUT {key-value-metadata-resource}/(prefix)

Sets all the specified key-value pairs, prefixed by key path. Key path may not contain wildcards.

Accepts:

application/xml, application/json – SimpleMetadataDocument

Example

NONE

PUT /user/myuser/metadata
Content-Type: application/xml

<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>occupation</key>
    <value>developer</value>
  </field>
  <field>
    <key>location</key>
    <value>London</value>
  </field>
</SimpleMetadataDocument>

NONE

200 OK

Delete all key-value pairs

DELETE {key-value-metadata-resource}: Clears all key-value pairs for the specified entity.

Example

NONE

DELETE /user/myuser/metadata

NONE

200 OK

Retrieve the metadata for a specific key

GET {key-value-metadata-resource}/(keypath)

Retrieves the value of a specific key. If a key path is specified, exactly one key-value pair must match the key path, else an error is returned.

Key paths can also be specified as well as specific keys.

Produces:

text/plain – The raw string value.

Example

NONE

GET /user/myuser/metadata/location

PYTHON

London

Set the value for a specific key

PUT {key-value-metadata-resource}/(keypath)

Sets the value for a specific key. The key path may not contain wildcards.

Accepts:

text/plain – The raw string value.

Example

NONE

PUT /user/myuser/metadata/location
Content-Type: text/plain

Stockholm

NONE

200 OK

Delete key-value pairs

DELETE {key-value-metadata-resource}/(keypath)

Deletes the key-value pair with the specified key. If a key path is given, it may include wildcards for deleting multiple keys.

Key paths can also be specified as well as specific keys.

Example

NONE

DELETE /user/myuser/metadata/location

NONE

200 OK