Set and remove metadata values
This section shows you how to use the Asset management API to set and remove metadata values on an asset from within your code.
Set metadata values
Before you assign metadata values, you must assign a metadata schema to the asset.
This function is a subset of the update asset endpoint.
Metadata fields
The Asset management API handles the metadata fields in specific ways. The Metadata fields document contains information about how the Asset management API handles the metadata JSON fields.
Command
Use the following command to update the metadata schema on an asset:
PATCH https://website.matrix.squiz.cloud/__management_api/v1/assets/<asset-id>
<asset-id> is the asset ID of the asset being updated.
Payload
Before creating this command you need to identify the fields in the metadata schema. To find the fields in the Matrix instance, right-click on the metadata schema and select Details. Scroll down to the Fields section.
The example below sets the metadata value fields for a certain metadata schema. All metadata schemas have different values, so this is a working example only.
Add the values to the payload:
"metadata_values": {
"keywords": {"value":"test keywords"}, (1)
"description": {"value":"test description"},
"right-col": {"value":"0"},
"right-col-include": {"value":""},
"show-heading": {"value":"1"}
}| 1 | Assign values to the fields of the metadata schema. Refer to the schema to see what data types are required. |
Response
The API response will contain:
{
"id": "3435",
"type": "page_standard",
"attributes": {
"name": "Home ",
"short_name": "Home"
},
"status": "under_construction",
"version": "0.0.3",
"created": {
"date_time_unix": 1646800343,
"user_id": "1227"
},
"updated": {
"date_time_unix": 1662599482,
"user_id": "1227"
},
"published": null,
"status_changed": {
"date_time_unix": 1646800343,
"user_id": "1227"
},
"metadata_schemas": [
{
"id": "5190",
"granted": true,
"cascades": true
}
],
"metadata_values": {
"keywords": {
"type": "metadata_field_text", (1)
"value": [
"test keywords"
]
},
"description": {
"type": "metadata_field_text", (2)
"value": "test description"
},
"right-col": {
"type": "metadata_field_select", (3)
"value": "0"
},
"right-col-include": {
"type": "metadata_field_related_asset", (4)
"value": ""
},
"show-heading": {
"type": "metadata_field_select", (5)
"value": "1"
}
},
"paint_layouts": {
"asset_level": null,
"asset_level_override": null,
"url_based": {
"domainname.matrix.squiz.cloud/test-site/home": {
"regular": null,
"override": null
}
},
"user_defined": {
"domainname.matrix.squiz.cloud/test-site/home": null
}
},
"web_paths": [
"home"
],
"urls": [
{
"path": "domainname.matrix.squiz.cloud/test-site/home",
"schemes": [
"https"
]
}domainname
],
"external_id": ""
}| 1 | Value from the payload shown in the keywords field. |
| 2 | Value from the payload shown in the description field |
| 3 | Default values from payload. |
| 4 | Default values from payload. |
| 5 | Default values from payload. |
Remove metadata values
To remove metadata values from an asset, PATCH the property with a value of null. In the following example, the value of "description" is being removed.
PATCH /__management_api/v1/assets/123456 HTTP/1.1
Host: matrix.labs.squiz.test
Authorization: Bearer ... change me ...
Content-Type: application/json
Content-Length: 62
{
"metadata_values": {
"description": null
}
}Be aware that in the front end, the property might still have a value that is derived from the default value of the field defined in the schema. Read Metadata fields - Use default for more information about the Use Default option.
| Only fields which are a part of an applied metadata schema can be set and unset. |