Storing custom metadata with HSwift
With the HSwift API, you use X-Object-Meta-
request headers to specify custom metadata. You can use these headers when you store or copy an object. With the X-Object-Meta-
request headers, 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 2015
, you would specify these headers:
X-Object-Meta-department: Sales&Mktg X-Object-Meta-year: 2015
HCP stores the custom metadata you specify with HSwift 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[2015]]></meta-year> </metapairs>
The root element in the .metapairs annotation is metapairs
.
For each property/value pair, the name of the corresponding element in the .metapairs XML annotation is the concatenation of 'meta-' and the metadata key, 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 for 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 custom metadata property/value pair, the value is enclosed in a CDATA section. This makes the property become the value of the corresponding element.
If you specify an X-Object-Meta-
header with no value, HCP doesn't store an element for the property named in the header. If all the X-Object-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-Object-Meta-
property multiple times with different values. In the same .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-Object-Meta-author: P.D Grey X-Object-Meta-author: Morgan White X-Object-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-Object-Meta-
headers result in three separate XML elements: X-Object-Meta-date_written
, X-Object-Meta-Date_Written
, and X-Object-Meta-DATE_WRITTEN
.