Key-value metadata¶
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.
Changed in version 4.16: Support for key-value metadata was added to shape-tags, libraries and task-definitions.
Changed in version 4.12: Keys can now be hierarchical, meaning the key can include the slash character.
Supported resources¶
The resources that support key-value metadata can be seen in the table
below. These are referred to as {key-value-metadata-resource}
the the
definitions below.
Resource | URI | Read role | Write role |
---|---|---|---|
Groups | /group/{group-name}/metadata |
_group_read |
_group_write |
Users | /user/{username}/metadata |
_admininstrator |
_administrator |
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¶
Retrieving 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¶
GET /user/myuser/metadata
<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>
Retrieving all metadata for a subtree¶
New in version 4.12.
-
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¶
GET /user/myuser/metadata/**/id
Setting 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.
New in version 4.12.
Accepts: - application/xml, application/json – SimpleMetadataDocument
Example¶
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>
200 OK
Clearing all key-value pairs¶
-
DELETE
{key-value-metadata-resource}
¶ Clears all key-value pairs for the specified entity.
Retrieving 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.
Changed in version 4.12: Key paths can now be specified as well as specific keys.
Produces: - text/plain – The raw string value.
Setting 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.
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.
Changed in version 4.12: Key paths can now be specified as well as specific keys.