Storing custom metadata with the S3 compatible API
With the S3 compatible API, you use x-amz-meta-
request headers to specify custom metadata. You can use these headers when you store or copy an object.
With the x-amz-meta-
header, you specify custom metadata as property/value pairs. You append the property name to the header and specify the value of the property as the value of the header. For example, to give an object a department
property with a value of Sales&Mktg
and a year property with a value of 2020
, you would specify these headers:
x-amz-meta-department: Sales&Mktg x-amz-meta-year: 2020
HCP stores the custom metadata you specify with the S3 compatible API as an annotation named .metapairs. In this annotation, the property/value pairs are stored as well-formed XML in which each property is represented by an element. For example, the XML stored for the headers shown above is:
<metapairs version="600"> <meta-department><![CDATA[Sales&Mktg]]></meta-department> <meta-year><![CDATA[]]></meta-year> </metapairs>2020
The root element in the .metapairs
annotation is metapairs
.
For each property/value pair, the name of the corresponding element is the concatenation of meta-
and the property name, modified if necessary to be a valid XML element name. Valid XML element names can contain alphanumeric characters, periods (.), hyphens (-), underscores (_), and colons (:). When creating element names from property names, HCP changes any other character to an underscore. For example, the property name city/town becomes the element name city_town
.
For each property/value pair, the property value becomes the value of the corresponding element. This value is enclosed in a CDATA section.
If you specify an x-amz-meta- header with no value, HCP doesn’t store an element for the property named in the header. If all the x-amz-meta-
headers you specify have no value, HCP doesn’t create a .metapairs
annotation for the object.
In a request to store or copy an object, you can specify the same x-amz-meta- property multiple times with different values. In the .metapairs
annotation XML, these values are stored as comma-separated values for a single element.
Here’s an example that shows three occurrences of the same property along with the resulting XML:
x-amz-meta-author: P.D. Grey x-amz-meta-author: Morgan White x-amz-meta-author: Paris Black <metapairs> <meta-author> <![CDATA[P.D. Grey,Morgan White,Paris Black]]> </meta-author> </metapairs>
Property names are case sensitive, so names that differ only in case correspond to separate XML elements. For example, these x-amz-meta-
headers result in three separate XML elements: x-amz-meta-date_written
, x-amz-meta-Date_Written
, and x-amz-meta-DATE_WRITTEN.