Custom metadata usage considerations

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

The following considerations apply to using custom metadata with the S3 compatible API.

Custom metadata and object versions

Custom metadata is specific to the object version for which it's stored:

  • If you store an object without custom metadata and then store a new version of the object with custom metadata, the custom metadata is not added to the old version of the object.
  • If you store an object with custom metadata and then store a new version of the object without custom metadata, the old version of the object has custom metadata, but the new version does not.

You cannot add or replace custom metadata for an old version of an object.

Property names

When naming custom metadata properties, you should use names that, when concatenated with meta-, result in valid XML element names. That way, the x-amz-meta- headers returned when you retrieve or check the existence of an object match the x-amz-meta- headers you specified when you stored or copied the object.

If HCP has to modify a property name to create a valid element name, the returned x-amz-meta- header won’t match the x-amz-meta- header specified when the object was stored or copied. For example, if the specified header is x-amz-meta-city/town, the returned header is x-amz-meta-city_town.

.

Custom metadata size

When you use the S3 compatible API to store or copy an object, you can specify at most two kilobytes of custom metadata. The size of the custom metadata you specify is the sum of the number of bytes in the UTF-8 encoding of each property name and value.

Allowed operations

Whether you can add, replace, or delete custom metadata for objects under retention depends on a bucket setting. When you create a bucket, it’s set to allow only the addition of custom metadata for objects under retention. You cannot use the S3 compatible API to change this setting. However, tenant administrators can change this setting for the buckets you create.

.metapairs annotations with unexpected content

You should not use HCP interfaces other than the S3 compatible API to store annotations named .metapairs. However, HCP does not prevent you from doing this. As a result, annotations named .metapairs are not guaranteed to be compatible with the S3 compatible API.

Here are some ways in which HCP responds to S3 compatible requests for objects that have .metapairs annotations with unexpected content:

  • If the .metapairs annotation doesn’t contain valid XML or if the first line in the annotation doesn’t begin with the metapairs element, HCP returns an x-amz-missing-meta header with a value of 1 (one) and does not return any x-amz-meta- headers.
  • If an element name doesn’t start with meta-, HCP doesn’t return an x-amz-meta- header for the element.
  • If a meta- element has no value, HCP doesn’t return an x-amz-meta- header for the element.
  • If a meta- element has an attribute, HCP ignores the attribute and returns the applicable x-amz-meta- header.
  • If the XML contains nested elements and the lowest-level element is a meta- element, HCP returns an x-amz- header for that element. It does not return x-amz- headers for any other elements in that nested structure.