Working With Object Metadata
The VMware Cloud Director API provides a general-purpose facility for associating user-defined metadata with an object. An administrator or object owner can use the metadata link in the object's representation to access an object's metadata.
Object metadata gives cloud
operators and tenants a flexible way to associate user-defined properties
(name=value
pairs)
with objects. Object metadata is preserved when objects are copied, and can be
included in query filter expressions (see
Add a Metadata Filter to a Query).
VMware Cloud Director API Object Metadata Links
<Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/vApp/vapp-7/metadata"/>
The following elements can include a link to a Metadata element.
- Catalog
- CatalogItem
- Disk
- Media
- OrgVdcNetwork
- ProviderVdc
- ProviderVdcStorageProfile
- VApp
- VAppTemplate
- Vdc
- VdcStorageProfile
- Vm
A
Metadata element can
contain up to 1024
MetadataEntry elements
(name=value
pairs)
that the object owner or an administrator can create, retrieve, update, and
delete.
It also
contains a group of
name=value
pairs
that are under the control of the system administrator.
VMware Cloud Director API Object Metadata Contents
Each
MetadataEntry includes
a single
name=value
pair,
represented in its
Key
and
TypedValue elements.
Key names are specified by
Key
element contents. A key name is a UTF-8 (Unicode) string encoded as described
in RFC3986 (pct-encoded
).
<Metadata ... <MetadataEntry> <Domain visibility="READONLY">SYSTEM</Domain> <Key>Foo</Key> ... </MetadataEntry> <MetadataEntry> <Key>Foo</Key> ... </MetadataEntry> </Metadata>See Access Control for VMware Cloud Director API Object Metadata for more information about the Domain element.
The type of a Value is expressed in the xsi:type attribute of the containing TypedValue element. Values have various restrictions, based on their type.
Type Name | Restrictions on Value | Size of Value |
---|---|---|
MetadataStringValue | UTF-8 character set. Strings longer than 1000 characters cannot be searched for in a query. | Depends on length of string. |
MetadataNumberValue | Must be a signed 8-byte integer. | 8 bytes |
MetadataDateTimeValue | UTC date and time in the format defined by
http://www.w3.org/TR/xmlschema-2/#dateTime.
For example,
2012-06-18T12:00:00-05:00
|
8 bytes |
MetadataBooleanValue | Must be one of: 1, 0, true, false | 1 byte |
The following rules apply when you update a Metadata element.
- When the content of a Key element in the update does not match the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is added to the Metadata element.
- When the content of Key element in the update matches the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is replaced.
Access Control for VMware Cloud Director API Object Metadata
The Domain element of a MetadataEntry controls access to that entry by users and system administrators. There are two access domains, only one of which can be specified explicitly.
- GENERAL
- This is the default access domain for metadata, and cannot be explicitly specified in a Domain element. A MetadataEntry that does not include a Domain element is considered to be in the GENERAL domain. User access to metadata in the GENERAL domain is controlled by the user's rights to the object to which the Metadata is attached. The owner of the object can create, read, update, or delete any MetadataEntry in the GENERAL domain.
- SYSTEM
- To be placed in the
SYSTEM domain, a
MetadataEntry must
include a
Domain element with a
value of
SYSTEM. Metadata in the
SYSTEM domain can be
created, updated, and deleted only by a system administrator. User access to
metadata in the
SYSTEM domain is
controlled by the value of the
visibility attribute of
the
Domain element.
Table 2. Domain Visibility Attribute Values Value Meaning PRIVATE The metadata is visible to system administrators only. READONLY the metadata is visible to system administrators and the object owner. - VCENTER
- Object metadata in the
VCENTER domain can be
applied to
Vm
objects, including
Vm
objects contained in
VAppTemplate objects,
by users in roles that have the right
vApp: Allow metadata mapping domain to vCenter
. The system uses metadata in this domain to deploy virtual machines on specific ESXi hosts that have been configured by your service provider. Your service provider establishes the set of legal values for metadata in this domain. See Specifying Advanced Virtual Machine Settings with ExtraConfig Elements.Note: Object metadata in the VCENTER domain is not displayed in the VMware Cloud Director Web Console.
VMware Cloud Director API Object Metadata Limits
- Metadata key size
- The contents of a Key element in a MetadataEntry cannot exceed 256 UTF-8 characters.
- Metadata size
- The size of all Metadata for an object, computed as the sum of all Key and TypedValue UTF-8 strings in all MetadataEntry elements in the GENERAL domain, cannot exceed 128 KB. An additional 16KB of MetadataEntry content can be created in the SYSTEM domain.
- MetadataEntry limit
- The total metadata associated with an object cannot exceed 1024 MetadataEntry elements in the GENERAL domain and 128 MetadataEntry elements in the SYSTEM domain.