Retrieve or Update a Metadata Element

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.

Note: The Key element cannot contain a semicolon character (;). In addition, several other character sequences are not allowed, or not allowed in certain positions.

Table 1. Content Restrictions for Key
Cannot Contain	Cannot Start with	Cannot End with
`/../`	`./`	`/.`
`/./`	`../`	`/..`

Prerequisites

Verify that you are logged in to the VMware Cloud Director API as an administrator or the object owner. Verify that you are logged in to the vCloud Air Compute Service as a Virtual Infrastructure Administrator or the End User who owns this object.
Retrieve the object's Metadata element. See Retrieve or Update a Metadata Element

Procedure

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"/>

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>

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 VMware Cloud Director API Object Metadata Contents.
POST the Metadata element to the rel="add" link described in Step 2.
See Update a Metadata Element.

Example: Update a Metadata Element

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.

Request:

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>

Request:

POST https://vcloud.example.com/api/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">
      <Key>PenTested</Key>
      <TypedValue
         xsi:type="MetadataBooleanValue">
         <Value>false</Value>
      </TypedValue>
   </MetadataEntry>
   <MetadataEntry
      type="application/vnd.vmware.vcloud.metadata.value+xml">
      <Key>OSL</Key>
      <TypedValue
         xsi:type="MetadataStringValue">
         <Value>none</Value>
      </TypedValue>
   </MetadataEntry>
</Metadata>

The response is a Task.

Response:

<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>

GET https://vcloud.example.com/api/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/PenTested" />
      <Link
         rel="remove"
         type="application/vnd.vmware.vcloud.metadata.value+xml"
         href="https://vcloud.example.com/api/vApp/vapp-7/metadata/PenTested" />
      <Link
         rel="up"
         type="application/vnd.vmware.vcloud.metadata+xml"
         href="https://vcloud.example.com/api/vApp/vapp-7/metadata" />
      <Key>PenTested</Key>
      <TypedValue
         xsi:type="MetadataBooleanValue">
         <Value>false</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/OSL" />
      <Link
         rel="remove"
         type="application/vnd.vmware.vcloud.metadata.value+xml"
         href="https://vcloud.example.com/api/vApp/vapp-7/metadata/OSL" />
      <Link
         rel="up"
         type="application/vnd.vmware.vcloud.metadata+xml"
         href="https://vcloud.example.com/api/vApp/vapp-7/metadata" />
      <Key>OSL</Key>
      <TypedValue
         xsi:type="MetadataStringValue">
         <Value>none</Value>
      </TypedValue>
   </MetadataEntry>
</Metadata>