Retrieve or Modify Groups of Related Sections in a Virtual Machine

The VMware Cloud Director API provides links that you can use to retrieve or update groups of sections that define related hardware items such as disks, media devices, and network cards in a Vm element.

As shown in Configuration Links in a Vm Element, Link elements for disks, media devices, and network cards are grouped at the end of the VirtualHardwareSection. These links have content type application/vnd.vmware.vcloud.rasdItemsList+xml, and reference a RasdItemsList element in the VirtualHardwareSection of a Vm. The VMware Cloud Director API uses the RasdItemsList element to aggregate related elements in a VirtualHardwareSection. This approach simplifies retrieval and modification of Item elements that are typically viewed or modified as a group.

Prerequisites

This operation requires the rights included in the predefined vApp Author role or an equivalent set of rights.Verify that you are logged in to the vCloud Air Compute Service as an End User.

Procedure

1. Retrieve the RasdItemsList from a Vm.
   Make a GET request to the URL in the link where type="application/vnd.vmware.vcloud.rasdItemsList+xml" and rel="down". See Retrieve the Hard Disks and Controllers in a Virtual Machine.
2. Modify the items in the retrieved list.

   Request bodies must contain all required elements and attributes, even if you are not changing their values. Because optional elements and attributes typically revert to default values if they are omitted or empty, it is a best practice to include optional elements in request bodies that modify existing objects. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes are read-only and cannot be modified. See the schema reference for details.

3. Update the sections with your modifications.
   Make a PUT request to the URL in the link where type="application/vnd.vmware.vcloud.rasdItemsList+xml" and rel="edit", and supply the modified section as the request body.
   The response to this request is a Task element that tracks the update operation. When the task is complete, the section is updated.

Example: Retrieve the Hard Disks and Controllers in a Virtual Machine

This example uses the virtualHardwareSection/disks link shown in Configuration Links in a Vm Element to retrieve the list of hard disks and hard disk controllers for a virtual machine.

Request:

GET https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/disks

Response:

200 OK
Content-Type: application/vnd.vmware.vcloud.rasdItemsList+xml
...
<RasdItemsList
   xmlns="http://www.vmware.com/vcloud/v1.5"
   xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
   type="application/vnd.vmware.vcloud.rasdItemsList+xml"
   href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/disks" ... >
   <Link
      rel="edit"
      type="application/vnd.vmware.vcloud.rasdItemsList+xml"
      href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/disks" />
   <Item>
      <rasd:Address>0</rasd:Address>
      <rasd:Description>SCSI Controller</rasd:Description>
      <rasd:ElementName>SCSI Controller 0</rasd:ElementName>
      <rasd:InstanceID>2</rasd:InstanceID>
      <rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
      <rasd:ResourceType>6</rasd:ResourceType>
   </Item>
   <Item>
      <rasd:AddressOnParent>0</rasd:AddressOnParent>
      <rasd:Description>Hard disk</rasd:Description>
      <rasd:ElementName>Hard disk 1</rasd:ElementName>
      <rasd:HostResource
         xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
         vcloud:capacity="1024"
         vcloud:busSubType="lsilogic"
         vcloud:busType="6"></rasd:HostResource>
      <rasd:InstanceID>2000</rasd:InstanceID>
      <rasd:Parent>2</rasd:Parent>
      <rasd:ResourceType>17</rasd:ResourceType>
   </Item>
   <Item>
      <rasd:AddressOnParent>1</rasd:AddressOnParent>
      <rasd:Description>Hard disk</rasd:Description>
      <rasd:ElementName>Hard disk 2</rasd:ElementName>
      <rasd:HostResource
         xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
         vcloud:capacity="2048"
         vcloud:busSubType="lsilogic"
         vcloud:busType="6"></rasd:HostResource>
      <rasd:InstanceID>2001</rasd:InstanceID>
      <rasd:Parent>2</rasd:Parent>
      <rasd:ResourceType>17</rasd:ResourceType>
   </Item>
   <Item>
      <rasd:Address>0</rasd:Address>
      <rasd:Description>IDE Controller</rasd:Description>
      <rasd:ElementName>IDE Controller 0</rasd:ElementName>
      <rasd:InstanceID>3</rasd:InstanceID>
      <rasd:ResourceType>5</rasd:ResourceType>
   </Item>
</RasdItemsList>