An administrator or the owner of an object can create, retrieve, or update the object's Metadata element. This element contains all object metadata. Operations that modify it merge the modifications with existing contents.
When you create an object, its representation contains an empty Metadata element. An administrator or the object owner can add metadata by updating the Metadata element with new MetadataEntry elements. Each of these elements contains a Key and a TypedValue. The contents of the Key element define the key name, which must be unique within the scope of the object's metadata. You can modify the value associated with an existing key. See Retrieve or Update a Metadata Value.
■
|
Verify that you are logged in to the vCloud API as an administrator or the object owner. |
■
|
Retrieve the object's Metadata element. See Retrieve or Update a Metadata Element |
1 | Retrieve the representation of the object. Examine the response to find its metadata link. This example shows the metadata link from an AdminOrg. <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/admin/vApp/vapp-7/metadata"/> |
2 | Retrieve the Metadata element. If the object has no metadata, the element contains only a rel="add" link that you can use to add metadata and a rel="up" link that references the containing object, as shown in this example. <Metadata xmlns="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" /> <Link rel="add" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" /> </Metadata> |
3 | Modify the retrieved Metadata element. You can add new MetadataEntry elements or modify existing ones. If you modify existing ones, your modifications are merged into the object's Metadata following the rules listed in vCloud API Object Metadata Contents. |
4 | POST the Metadata element to the rel="add" link described in Step 2. |
This example updates the empty Metadata element shown in Step 2 to create two MetadataEntry elements.
In this example, the Metadata element contains MetadataEntry elements for which the Domain is SYSTEM. Only the system administrator can update these elements.
POST https://vcloud.example.com/api/admin/vApp/vapp-7/metadata Content-Type: application/vnd.vmware.vcloud.metadata+xml ... <?xml version="1.0" encoding="UTF-8"?> <Metadata xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="application/vnd.vmware.vcloud.metadata+xml"> <MetadataEntry type="application/vnd.vmware.vcloud.metadata.value+xml"> <Domain visibility="READONLY">SYSTEM</Domain> <Key>Organization Web Page</Key> <TypedValue xsi:type="MetadataStringValue"> <Value>http://internal.example.com/orgs/Finance</Value> </TypedValue> </MetadataEntry> <MetadataEntry type="application/vnd.vmware.vcloud.metadata.value+xml"> <Domain visibility="PRIVATE">SYSTEM</Domain> <Key>LOS</Key> <TypedValue xsi:type="MetadataStringValue"> <Value>bronze</Value> </TypedValue> </MetadataEntry> </Metadata>
<Task xmlns="http://www.vmware.com/vcloud/v1.5" status="running" ... operationName="metadataUpdate" operation="Updating metadata for vApp (7)" ... > ... </Task>
After the task is complete, the Metadata element is updated to contain the entries specified in the request, along with links that you can use to retrieve or update individual MetadataEntry elements.
GET https://vcloud.example.com/api/admin/vApp/vapp-7/metadata ... <Metadata xmlns="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" ... > <Link rel="add" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" /> <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" /> <MetadataEntry> <Link rel="edit" type="application/vnd.vmware.vcloud.metadata.value+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata/SYSTEM/Organization+Web+Page" /> <Link rel="remove" type="application/vnd.vmware.vcloud.metadata.value+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata/SYSTEM/Organization+Web+Page" /> <Link rel="up" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" /> <Domain visibility="READONLY">SYSTEM</Domain> <Key>Organization Web Page</Key> <TypedValue xsi:type="MetadataStringValue"> <Value>http://internal.example.com/orgs/Finance</Value> </TypedValue> </MetadataEntry> <MetadataEntry> <Link rel="edit" type="application/vnd.vmware.vcloud.metadata.value+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata/SYSTEM/LOS" /> <Link rel="remove" type="application/vnd.vmware.vcloud.metadata.value+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata/SYSTEM/LOS" /> <Link rel="up" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata" /> <Domain visibility="PRIVATE">SYSTEM</Domain> <Key>LOS</Key> <TypedValue xsi:type="MetadataStringValue"> <Value>bronze</Value> </TypedValue> </MetadataEntry> </Metadata>