Metadata Controller handles all metadata for a mediacontainer, e.g. container_title, meta_productionCountry, etc.
Metadata can originate from automatic processing (e.g. after uploading an image, IPTC metadata will be extracted from image).
Metadata is multi-lingual.
Reference
Find metadata
Find all metadata for a given mediaContainerId. If the mediaContainerId is a public area then also the metadata for the mediaContainers related to that public area are returned (e.g. the title of videos in the public area which could differ from the “original” title).
Additionally all metadata for this mediacontainer in channels (which could be different from the metadata of the original mediacontainer) are in the response.
Create metadata
Create a new metadate element/entry for a given mediacontainer or channel.
If the metadata already exists, this call works like metadata.update.
If customer has set individualConfiguration.mediaContainer.prettifyContainerName=true metadata with title “container_name” will be prettified (e.g. “IMG_0453_New York” will become “IMG 0453 New York”)
Metadata create can automatically translate from an existing field using translate parameter. Azure translation must be enabled for the customer.
| Field | Type | Required | Description |
|---|---|---|---|
| channelId | integer | ✓ | channelId of metadata. Required if no mediaContainerId is set. |
| content | any | ✓ | language of metadata |
| flag | integer | ✗ | Set to 10, if this entry is automatically created (e.g. by the uploader and not by the user) allowed values: 010 |
| language | string | ✓ | language of metadata |
| linked_mediaContainerId | integer | ✗ | linked_mediaContainerId of metadata |
| mediaContainerId | integer | ✓ | mediaContainerId of metadata. Required if no channelId is set. |
| settings | object | ✗ | settings for metadata |
| └ lock | boolean | ✗ | If true, metadata cannot be changed/updated, e.g. for read-out GPS data |
| └ origin | string | ✗ | Identifies where the metadata originated, e.g. IPTC |
| └ linkedToOriginal | boolean | ✗ | Identifies if metadata of a mediacontainer is linked to metadata of that mediacontainer in a project/publicarea |
| title | string | ✓ | title of metadata |
| translate | string | ✗ | Language to use as translation base for Azure automatic translation. Requires contractConfiguration.azure.textTranslation.enabled Beta |
| Field | Type | Description |
|---|---|---|
| channelId | integer | channelId of metadata. Required if no mediaContainerId is set. |
| content | any | content of metadata |
| flag | integer | Set to 10, if this entry is automatically created (e.g. by the uploader and not by the user) allowed values: 010 |
| language | string | language of metadata |
| linked_mediaContainerId | integer | linked_mediaContainerId of metadata |
| mediaContainerId | integer | mediaContainerId of metadata. Required if no channelId is set. |
| settings | object | settings for metadata |
| └ lock | boolean | If true, metadata cannot be changed/updated, e.g. for read-out GPS data |
| └ origin | string | Identifies where the metadata originated, e.g. IPTC |
| └ linkedToOriginal | boolean | Identifies if metadata of a mediacontainer is linked to metadata of that mediacontainer in a project/publicarea |
| title | string | title of metadata |
| translate | string | Language to use as translation base for Azure automatic translation. Requires contractConfiguration.azure.textTranslation.enabled Beta |
Update metadata
Updates an existing metadata entry.
| Field | Type | Required | Description |
|---|---|---|---|
| channelId | integer | ✓ | channelId of metadata. Required if no mediaContainerId is set. |
| content | any | ✓ | content of metadata |
| flag | integer | ✗ | allowed values: 010 |
| ignoreConflict | boolean | ✗ | If you sent timestamp and receive a conflict, you can ignore this conflict by setting this parameter to true. |
| language | string | ✓ | language of metadata |
| linked_mediaContainerId | integer | ✗ | linked_mediaContainerId of metadata |
| mediaContainerId | integer | ✓ | mediaContainerId of metadata. Required if no channelId is set. |
| metadataId | integer | ✗ | id of this metadata entry. Is no longer required. Sending mediaContainerId is sufficient. Deprecated |
| settings | object | ✗ | |
| └ lock | boolean | ✗ | If true, metadata cannot be changed/updated, e.g. for read-out GPS data |
| └ origin | string | ✗ | Identifies where the metadata originated, e.g. IPTC |
| └ linkedToOriginal | boolean | ✗ | Identifies if metadata of a mediacontainer is linked to metadata of that mediacontainer in a project/publicarea |
| timestamp | integer | ✗ | Send the timestamp you've received with the find call in the header X-AdmiralCloud-TS to check whether the data has been changed in between |
| title | string | ✗ | title of metadata |
| translate | string | ✗ | Beta |
| Field | Type | Description |
|---|---|---|
| channelId | integer | channelId of metadata. Required if no mediaContainerId is set. |
| content | any | content of metadata |
| flag | integer | allowed values: 010 |
| language | string | language of metadata |
| linked_mediaContainerId | integer | linked_mediaContainerId of metadata |
| mediaContainerId | integer | mediaContainerId of metadata. Required if no channelId is set. |
| settings | object | |
| └ lock | boolean | If true, metadata cannot be changed/updated, e.g. for read-out GPS data |
| └ origin | string | Identifies where the metadata originated, e.g. IPTC |
| └ linkedToOriginal | boolean | Identifies if metadata of a mediacontainer is linked to metadata of that mediacontainer in a project/publicarea |
| title | string | title of metadata |
| translate | string | Beta |
BatchUpdate metadata
Updates (or creates if necessary) metadata for a bunch of mediacontainers. You can update multiple metadata at once per mediacontainer. The API checks if a metadata field is applicable for the given mediacontainer type. For more details on metadata field configuration, please refer to Metadata Form Controller
Metadata batchupdate also support sophisticated placeholders including search and replace operations. You can use every existing metadata fields in a template.
// Example that updates existing mediacontainer title with a production date (meta_productionDate) and replaces a typo
{
"ids": [123,456,789]
"metadata": [{
"title": "container_name",
"content": "{{field:meta_productionDate:YYYY-MM-DD}} {{current_value}} {{replace:Tom:Tim}}"
"language": "uni"
}],
"ignoreConflict": true
}
// existing title: Documentation Tom Taylor
// after replacement: 1998-10-20 Documentation Tim TaylorIf the metadata already exists and ignoreConflict is not set, return these values without updating.
If access to one of the mediacontainers is not granted or metadata is not valid, it will be silently ignored.
Returns the jobId to use to fetch the result later (after activities are 100%). If you send a payload with less that 200 updates, e.g. 50 ids with 4 metadata, the batchUpdate runs immediately, not in the background, and returns the result (identical to requesting the job result from Activity Controller
| Field | Type | Required | Description |
|---|---|---|---|
| content | any | ✗ | content of metadata to update |
| controlGroupIds | array | ✗ | Array of control group IDs for filtering mediacontainers |
| controlGroupIdsAll | array | ✗ | Array of control group IDs where mediacontainer must belong to all specified groups |
| controlGroupIdsNot | array | ✗ | Array of control group IDs to exclude from batch update |
| field | string | ✗ | Specific field to search in when using searchTerm |
| flags | array | ✗ | Array of flags for filtering mediacontainers in batch update |
| ids | array | ✓ | Array of mediaContainer IDs to update with metadata |
| ignoreConflict | boolean | ✗ | If you sent updatedAt and receive a conflict, you can ignore this conflict by setting this parameter to true. |
| language | string | ✗ | language of metadata to update |
| languages | array | ✗ | languages to (additonally) search in. If not set, the user's uiLanguage is used. |
| └ lang | string | ✗ | language in iso2 |
| └ boost | float | ✗ | factor to boost the language – if not set, defaults to 1 |
| metadata | array | ✓ | Array of metadata objects to update for the specified mediacontainers |
| └ title | string | ✓ | Title of metadata to update |
| └ language | string | ✓ | Language of metadata to update allowed values: aaabafaksqamaranhyasavaeayazbabmeubebnbhbibobsbrbgmycacschcezhcucvkwcocrcycsdadedvnldzeleneoeteueefofafjfifrfrfyffkadegdgaglgvelgnguhthahehzhihohrhuhyigisioiiiuieiaidikisitjvjaklknkskakrkkkmkirwkykvkgkokjkulolalvlilnltlblulgmkmhmlmimrmsmkmgmtmnmimsmynanvnrndngnenlnnnbnonyocojoromospafapiplptpsqurmrorornrusgsasiskskslsesmsnsdsostessqscsrsssuswsvtytatttetgtlthbotitotntstktrtwugukuruzvevivocywawoxhyiyozazhzuuni |
| └ content | string | ✓ | Content of metadata to update. Send null to remove metadata entry |
| query | object | ✗ | Elasticsearch query object for selecting mediacontainers to update |
| searchTerm | string | ✗ | Search term for finding mediacontainers to update using Elasticsearch |
| size | integer | ✗ | Limit the number of results (development only) |
| timestamp | integer | ✗ | Unix timestamp from the metadata find call for conflict detection in batch updates |
| title | string | ✗ | title of metadata to update |
| Field | Type | Description |
|---|---|---|
| conflict | array | Array of items with conflict |
| └ id | integer | ID of the mediaContainer that was affected |
| └ message | string | Message about the conflict reason |
| └ additionalInfo | object | Additional information about the ignored item |
| error | array | Array of items with error |
| └ id | integer | ID of the mediaContainer that was affected |
| └ message | string | Message about the error reason |
| └ additionalInfo | object | Additional information about the ignored item |
| ids | array | Array of mediaContainer IDs to update with metadata |
| ignored | array | Array of ignored items (e.g. no access) |
| └ id | integer | ID of the mediaContainer that was ignored |
| └ message | string | Message about the ignored item |
| └ additionalInfo | object | Additional information about the ignored item |
| jobId | string | ID of the job that was processed or queued. Use this ID to query the job status via Activity.jobResult |
| payloadSize | integer | Total size (ids x metadata) of the payload that was processed or queued. |
| processImmediately | boolean | If true, the job was processed immediately, not via background job |
| processed | array | Array of processed item |
| └ id | integer | ID of the mediaContainer that was processed |
| └ message | string | Message about the processing result |
| size | integer | Number of mediaContainerIds that were processed or queued. |
| Event | Result | IgnoreConflict | Notes |
|---|---|---|---|
| mediaContainerAccessNotGranted | ignored | Access to MediaContainer not granted | |
| mediaContainerIsLocked | ignored | MediaContainer is locked | |
| notAvailableForPublicAreas | ignored | MediaContainer type and metadata do not match e.g. updating meta_productionCountry for type dropsite | |
| name_tooLong | ignored | content length is bigger than maxLength | |
| metadataAlreadyExists | conflict | overwrite | Metadata already exists |
| updatingMetadataFailed | error | Technical problem updating metadata | |
| mediaContainerIsInTrash | error | e.g. MediaContainer is deleted |