vCloud API Operations
The following sections describe commonly used vCloud API operations using vCloud SDK for .NET. The API descriptions in this chapter do not provide complete backup/restore implementation details, but focus instead on identifying a set of vCloud API methods that facilitate certain operations that use vCloud Director.
You should be familiar with vCloud Director and vCloud API concepts. Every resource in vCloud Director can be accessed using either its unique ID or HREF (the reference URL) in the vCloud API. The .NET SDK provides wrapper utility classes for commonly-used resources to make the programming easier.
The operations described in the following sections are:
■
Getting Access to vCloud Director – Shows how to connect and authenticate with the vCloud API.
■
Inventory Access – Shows how to retrieve data for different Organization types.
■
Retrieving Catalog information – Shows how to retrieve Catalog entries for backup.
■
Retrieving vApp Configuration – Shows how to list virtual machines and vApp configuration data.
■
Preventing Updates to a vApp During Backup or Restore – Shows how to use maintenance mode to quiesce vApp configuration.
■
Associating vCloud Resources with vSphere Entities – Shows how to get Managed Object References of virtual machines and storage resources from vCloud Director.
■
Restoring vApps – Shows how to import virtual machines into vApps.
Getting Access to vCloud Director
The backup/restore software component must use system administrator privileges to connect to vCloud Director, so that it can access any Organization. The system administrator always logs into the System organization. When Administrator@System is used as the user name for the API, Administrator is the login name and System is the System Organization name.
Using system administrator privileges to connect to vCloud Director also allows the backup/restore software to access additional information relating a vApp to the corresponding resources in vSphere. This is described in Inventory Access.
Example: vCloud Director login code sample using Administrator@System/<password> shows how to log in using C# with the vCloud SDK for .NET. After logging in, the code shows how to access Organization data.
Example: vCloud Director login code sample using Administrator@System/<password>
using com.vmware.vcloud.sdk;
using com.vmware.vcloud.api.rest.schema;
 
public static vCloudClient client = null;
client = new vCloudClient(vCloudURL, com.vmware.vcloud.sdk.constants.Version.V1_5);
client.Login(username, password);
// Get references to all Organizations:
Dictionary<string,ReferenceType> organizationsMap = client.GetOrgRefsByName();
// Get reference to a specific Organization:
string orgName = "Org1";
ReferenceType orgRef = client.GetOrgRefByName(orgName);
// Convert Organization reference to Organization object:
Organization org = Organization.GetOrganizationByReference(client, orgRef);
 
Inventory Access
In general, you locate a desired vApp for backup in the context of a given Organization and VDC. To locate a vApp that you want to back up, you first need a reference to its parent Organization.
You use the Organization reference to get the Organization object, which you use to get a list of references to the VDCs that belong to the Organization. You use a VDC reference to get a VDC object, which you then use to get a list of references to the vApps that belong to the Organization. You convert the desired vApp reference to a vApp object, which you use to list the virtual machines that belong to the vApp.
Example: vCloud Director login code sample using Administrator@System/<password> shows how to get a reference to the user view of an Organization. Example: Get Admin Org and Admin VDC shows how to get a reference to the admin view of an Organization and a VDC.
Example: Get Admin Org and Admin VDC
public static vCloudClient client = null;
// Login
…
// Get admin view of Org
VcloudAdmin admin = client.GetVcloudAdmin();
string orgName = "Org1";
ReferenceType orgRef = admin.GetAdminOrgRefByName(orgName);
AdminOrganization adminOrg = Organization.AdminGetOrgByReference(client, orgRef);
 
// Get admin vDC
string vdcName = "VDC1";
ReferenceType vdcRef = adminOrg.GetAdminVdcRefByName(vdcName);
…
AdminVdc adminVdc = AdminVdc.GetAdminVdcByReference(client, vdcRef);
 
Admin Views
The admin view of resources such as Organization, VDC, and vApp provides extra information that is useful to users with administrative privileges. For example, in the case of a vApp, admin view provides information about vCenter and the virtual machines that belong to the vApp. The admin view provides information such as Managed Object References that vCenter uses for those entities. See Associating vCloud Resources with vSphere Entities for more information about getting vCenter Managed Object References.
To access admin views, you use a method of the client connection object to create an admin client proxy. The admin proxy has methods similar to those of the client connection object to get references to Organizations and other vCloud objects. However, the objects you get from the admin proxy have additional properties not present in user objects.
Admin Extensions
Similar to the admin views, you can use a different method of the client connection object to create an admin extension client proxy. You use the admin extension proxy to find provider VDC. A provider VDC includes one or more resource pools and allocates resources from those pools to the Org VDCs that it supports.
Example: Get Provider VDC shows how to get a Provider VDC.
Example: Get Provider VDC
// Login
…
// Get dictionary of Provider vDCs:
AdminExtension.VcloudAdminExtension adminExt = client.GetVcloudAdminExtension();
string pvdcName = "ProvVDC1";
Dictionary<string, ReferenceType> refs = adminExt.GetVMWProviderVdcRefsByName();
…
// Get reference for pvdcName -> pvdcRef
ReferenceType pvdcRef = refs[pvdcName];
VMWProviderVdc vmwPvdc = VMWProviderVdc.GetVMWProviderVdcByReference(client, pvdcRef);
 
Using the vCloud SDK for .NET allows you to access vCloud Director from a C# development environment. These examples show how to use .NET methods. The vCloud SDK for .NET simplifies access to the vCloud API. For more information about using the SDK, see the vCloud SDK for .NET Developer's Guide.
The vCloud API is REST-based. For more information about the vCloud API, see the vCloud API Programming Guide. Example: REST API Calls To Get Provider VDC shows the REST API calls that accomplish the tasks shown in Example: vCloud Director login code sample using Administrator@System/<password>, Example: Get Admin Org and Admin VDC, and Example: Get Provider VDC, after logging in.
Example: REST API Calls To Get Provider VDC
GET https://vCloud/api/admin
GET https://vCloud/api/admin/org/id
GET https://vCloud/api/admin/vdc/id
 
GET https://vCloud/api/admin/extension
GET https://vCloud/api/admin/extension/providervdc/id
 
In general, if you do not need admin views or provider views, you can use an Organization reference to get a VDC reference, and you can use the VDC reference to get a list of vApps belonging to the VDC. Example: List vApps in a VDC for a Given Organization shows how to list the hierarchy of Organizations, VDCs, and vApps known to vCloud Director. This example assumes you have already logged in to vCloud Director.
Example: List vApps in a VDC for a Given Organization
Dictionary<string, ReferenceType> organizationsMap = client.GetOrgRefsByName();
if (organizationsMap != null)
{
   foreach (string organizationName in organizationsMap.Keys)
   {
      ReferenceType organizationReference = organizationsMap[organizationName];
      Organization org = Organization.GetOrganizationByReference(client, organizationReference);
      string OrgID = org.Resource.id;
      Console.WriteLine("Organization Name:" + organizationName);
      Console.WriteLine("Organization Id :" + OrgID);
   }
   foreach (ReferenceType orgRef in organizationsMap.Values)
   {
      Organization org = Organization.GetOrganizationByReference(client, orgRef);
 
      foreach (ReferenceType vdcRef in org.GetVdcRefs())
      {
         Vdc vdc = Vdc.GetVdcByReference(client, vdcRef);
         string vdcId = vdc.Resource.id;
         Console.WriteLine("Org vDC Id:" + vdcId);
         Console.WriteLine("Org vDC Name:" + vdc.Reference.name);
         foreach (ReferenceType vAppRef in Vdc.GetVdcByReference(client, vdcRef).GetVappRefs())
         {
            Vapp vapp = Vapp.GetVappByReference(client, vAppRef);
            Console.WriteLine("vApp Id:" + vapp.Resource.id);
            Console.WriteLine("vApp Name:" + vapp.Resource.name);
            List<VM> vms = new List<VM>();
            try
            {
               vms = vapp.GetChildrenVms();
            }
            catch
            {
               // Handle exception here
            }
            foreach (VM vm in vms)
            {
               Console.WriteLine("VM Id : " + vm.Resource.id);
               Console.WriteLine("VM Name : " + vm.Resource.name);
            }
         }
      }
   }
}
 
The .NET SDK code in Example: List vApps in a VDC for a Given Organization translates to the API calls shown in Example: REST API Calls To List vApps in a VDC for a Given Organization
Example: REST API Calls To List vApps in a VDC for a Given Organization
GET https://vCloud/api/admin
GET https://vCloud/api/admin/org/id
GET https://vCloud/api/admin/vdc/id
 
GET https://vCloud/api/admin/extension
GET https://vCloud/api/admin/extension/providervdc/id
 
You can use a provider VDC reference to enumerate its associated datastores, as shown in Example: List Datastores. This example assumes you have already logged in to vCloud Director.
Example: List Datastores
/// <summary>
/// Returns list of Provider vDCs.
/// </summary>
/// <returns>ReferenceType</returns>
public static List<ReferenceType> GetProviderVdc()
{
   List<ReferenceType> vdcRefList = new List<ReferenceType>();
   foreach (ReferenceType vdcRef1 in
      client.GetVcloudAdminExtension().GetVMWProviderVdcRefsByName().Values)
   {
      vdcRefList.Add(vdcRef1);
   }
   return vdcRefList;
}
 
/// <summary>
/// Returns the list of DataStores
/// </summary>
/// <returns>ReferenceType</returns>
public static List<ReferenceType> GetDataStore()
{
   extension = client.GetVcloudAdminExtension();
   List<ReferenceType> vmDatastorelist = new List<ReferenceType>();
   foreach (ReferenceType datastoreRef in extension.GetVMWDatastoreRefs())
   {
      vmDatastorelist.Add(datastoreRef);
   }
   return vmDatastorelist;
}
 
// Get the datastores for the list of Provider vDCs.
 
foreach (ReferenceType providerVdcRef in GetProviderVdc())
{
   string providerVdcId = GetId(providerVdcRef.href);
   Console.WriteLine("Provider vDC Id:" + providerVdcId);
   Console.WriteLine("Provider vDC Name:" + providerVdcRef.name);
   foreach (string morefitem in
      VMWProviderVdc.GetResourcePoolsByMoref(client, providerVdcRef).Keys)
   {
      Console.WriteLine("Moref :" + morefitem);
   }
   foreach (VMWProviderVdcResourcePoolType VcResourcePool in
      VMWProviderVdc.GetResourcePoolsByMoref(client, providerVdcRef).Values)
   {
      string VcResourcePoolId = GetId(VcResourcePool.ResourcePoolVimObjectRef.VimServerRef.href);
      Console.WriteLine("VcResourcePoolId :" + VcResourcePoolId);
   }
}
foreach (ReferenceType item in GetDataStore())
{
   string DatastoreId = GetId(item.href);
   Console.WriteLine("Data Store ID:" + DatastoreId);
   Console.WriteLine("DataStore:" + item.name);
}
 
Retrieving Catalog information
Catalogs on vCloud Director store vApp templates and ISO images as Catalog items. Backup solutions can be asked to back up the items in the Catalog for a given Organization. Catalogs can be shared or private. A user can choose to back up all items or only selected items in the given catalog. For this it is necessary to traverse the given Catalog in an Organization to access the contents and extract the various metadata associated with the vApp.
Example: List Catalogs and Catalog Items for a Given Organization shows inventory traversal to access the Catalog items in a given Organization, and assumes you have already logged in to vCloud Director and obtained a map of Organizations, as in Example: vCloud Director login code sample using Administrator@System/<password>.
Example: List Catalogs and Catalog Items for a Given Organization
Console.WriteLine();
if (organizationsMap != null && organizationsMap.Count > 0)
{
   foreach (string organizationName in organizationsMap.Keys)
   {
      ReferenceType organizationReference = organizationsMap[organizationName];
      Console.WriteLine(organizationName);
      Console.WriteLine(organizationReference.href);
      Organization organization = Organization.GetOrganizationByReference(client, organizationReference);
      List<ReferenceType> catalogLinks = organization.GetCatalogRefs();
      if (catalogLinks != null && catalogLinks.Count > 0)
      {
         foreach (ReferenceType catalogLink in catalogLinks)
         {
            Catalog catalog = Catalog.GetCatalogByReference(client, catalogLink);
            CatalogType catalogType = catalog.Resource;
            Console.WriteLine("   " + catalogType.name);
            Console.WriteLine(“   " + catalogLink.href);
            List<ReferenceType> catalogItemReferences = catalog.GetCatalogItemReferences();
            if (catalogItemReferences != null && catalogItemReferences.Count > 0)
            {
               foreach (ReferenceType catalogItemReference in catalogItemReferences)
               {
                  Console.WriteLine(“   " + catalogItemReference.name);
                  Console.WriteLine("   " + catalogItemReference.href);
               }
               Console.WriteLine();
            }
            else
            {
               Console.WriteLine( "No CatalogItems Found");
            }
         }
         Console.WriteLine();
      }
      else
      {
         Console.WriteLine( "No Catalogs Found");
      }
   }
}
else
{
   Console.WriteLine("No Organizations");
}
 
Example: REST API Calls To List Catalog Items shows the REST API calls that accomplish some of the tasks shown in Example: List Catalogs and Catalog Items for a Given Organization.
Example: REST API Calls To List Catalog Items
GET https://vCloud/api/catalog/id
GET https://vCloud/api/catalog/id/catalogItems
GET https://vCloud/api/catalogitem/id
 
Retrieving vApp Configuration
For a typical user, a vApp is the basic unit of backup specified in vCloud Director. The current generation of backup software maps vApps to their associated virtual machines in vSphere, and thus the virtual machine becomes an actual artifact. Virtual disk and virtual machine configuration files need to be stored in a backup. Along with the associated virtual machine artifacts, the user needs to back up the metadata and properties associated with every vApp to successfully restore it in vCloud Director when needed.
When a vApp is lost or deleted from vCloud Director, backup software can restore the vApp by composing a new vApp using virtual machines restored in vSphere. In such a case it becomes imperative to restore the properties and metadata associated with the vApp in vCloud Director.
The SDK includes a number of methods that you can use to get vApp configuration information. Although some of this information is included in the OVF used to upload the vApp to vCloud Director, the information might have subsequently been modified either by using the vCloud API or through the user interface.
All of these methods apply to an object of type Vapp.
Methods To Retrieve vApp Configuration
■
GetChildrenVms()
Gets a list of all child virtual machines that constitute a given vApp. Returns List<VM>.
■
GetStartupSection()
Get virtual machine startup information. Returns StartupSectionType.
■
GetNetworksByName()
Get mapping of all the network sections using their name. Returns Dictionary<string, NetworkSection_TypeNetwork>.
■
GetNetworkConfigSection()
Get network configuration details for a vApp. The information typically contains IP scope (gateway, netmask, DNS settings, IP range), Parent network, Fence Mode settings, and so on. Returns NetworkConfigSectionType.
■
GetLeaseSettingSection()
Get lease settings information. It includes deployment and storage lease settings for the vApp. Returns LeaseSettingsSectionType.
■
GetOwner()
Get owner information for the vApp. Returns ReferenceType.
■
GetMetadata()
Every resource in vCloud API can be associated with user-defined metadata. This method returns user-defined metadata associated with a vApp. Returns MetadataType.
Example: REST API Calls To Get vApp Configuration shows the REST API calls used to get vApp configuration data.
Example: REST API Calls To Get vApp Configuration
GET https://vCloud/api/vapp/id
GET https://vCloud/api/vapp/id/startupSection
GET https://vCloud/api/vapp/id/networkConnectionSection
GET https://vCloud/api/vapp/id/networkConfigSection
GET https://vCloud/api/vapp/id/leaseSettingsSection
GET https://vCloud/api/vapp/id/owner
GET https://vCloud/api/vapp/id/metadata
 
Virtual Machine Information
vCloud Director also stores virtual machine configuration information uploaded from an OVF file into a vApp template. If you have not modified a virtual machine configuration since uploading, you can use this information to verify the configuration of the virtual machine before restoring it.
The following methods, applied to an object of type VM, retrieve configuration data structures from vCloud Director.
Configuration Data for a Virtual Machine
■
GetVirtualHardwareSection()
Get hardware requirements of the virtual machine. Returns VirtualhardwareSection_Type.
■
GetOperatingSystemSection()
Get information about the guest operating system installed on this virtual machine. Returns OperatingSystemSectionType.
■
GetNetworkConnectionSection()
Get information about virtual network devices used by this virtual machine. Returns NetworkConnectionSectionType.
■
GetRuntimeInfoSection()
Get version of VMware Tools installed on the virtual machine. Returns RuntimeInfoSectionType.
Example: REST API Calls To Get Virtual Machine Configuration Data shows the REST API calls corresponding to the virtual machine configuration sections available from the SDK for .NET.
Example: REST API Calls To Get Virtual Machine Configuration Data
 
GET https://vCloud/api/vapp/id/virtualhardwaresection
GET https://vCloud/api/vapp/id/operatingSystemSection
GET https://vCloud/api/vapp/id/networkConnectionSection
GET https://vCloud/api/vapp/id/runtimeInfoSection
 
Preventing Updates to a vApp During Backup or Restore
While you are backing up or restoring a vApp, you need to prevent updates to the vApp configuration and metadata so that the vApp remains internally consistent. To prevent updates during the backup/restore process, the vCloud API allows the vApp to be placed in maintenance mode, which rejects any new updates to the configuration and metadata.
The backup software must select maintenance mode for the vApp before starting backup or restore operations, and deselect maintenance mode for the vApp after the operations are completed. Example: Protecting a vApp with Maintenance Mode shows how to select and deselect maintenance mode for a vApp.
Example: Protecting a vApp with Maintenance Mode
using com.vmware.vcloud.sdk;
using com.vmware.vcloud.api.rest.schema;
…
VApp vapp; // VApp utility class from vCloud SDK
// Identify vApp
 
vapp.EnableMaintenance(); // Enter maintenance mode
 
// Perform backup/restore here
 
vapp.DisableMaintenance(); // Exit maintenance mode
 
Example: REST API Calls To Protect a vApp with Maintenance Mode shows the corresponding REST API calls to select and deselect maintenance mode for a vApp.
Example: REST API Calls To Protect a vApp with Maintenance Mode
POST https://vCloud/api/vapp/id/action/enterMaintenancemode
POST https://vCloud/api/vapp/id/action/exitMaintenanceMode
 
Note Selecting maintenance mode does not affect current or pending tasks associated with the vApp. Current or pending tasks will run to completion concurrent with the backup or restore operation. If these tasks involve configuration changes, they could result in an inconsistent vApp configuration. The backup system must ensure that such tasks are complete before storing the vApp properties and metadata.
Associating vCloud Resources with vSphere Entities
The admin view of vCloud Director resources provides additional information about the corresponding entities relevant to the vSphere platform. This information is available only when administrative credentials are used to log in to vCloud Director. The additional information does not replace the use of the vSphere API to provide comprehensive information about the entities. It merely provides the bridge between the vCloud and vSphere by mapping the IDs known to the respective systems.
For example, any given virtual machine is known in vCloud Director by a URN that contains the UUID and resource type. The same resource is identified in vSphere using its native identification, a MoRef (Managed object reference). Additional information provided in the vCloud API makes the necessary link between the two entities by mapping their ID in the two systems. The mapping context is shown in Mapping to a Virtual Machine from a vApp.
Mapping to a Virtual Machine from a vApp
The vCloud API describes the mapping in terms of XML elements, shown in Example: XML Mapping a Virtual Machine URL to a MoRef. The box in the example highlights XML data that maps a virtual machine from vCloud Director to vSphere. The MoRef of the virtual machine is in bold type.The object type is shown as VIRTUAL_MACHINE.
Example: XML Mapping a Virtual Machine URL to a MoRef
<Vm needsCustomization="false" deployed="false" status="3" name="RedHat6" id="urn:vcloud:vm:f487ba71-058a-47a9-9e9a-def458c63fd5" type="application/vnd.vmware.vcloud.vm+xml" href="https://10.20.140.167/api/vApp/vm-f487ba71-058a-47a9-9e9a-def458c63fd5">
   <VCloudExtension required="false">
      <vmext:VmVimInfo>
 
 
         <vmext:VmVimObjectRef>
            <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="dao_w2k8_vc" href="https://10.20.140.167/api/admin/extension/vimServer/e7026985-19f6-4b9a-9d0d-588629e63347"/>
               <vmext:MoRef>vm-63</vmext:MoRef>
               <vmext:VimObjectType>VIRTUAL_MACHINE</vmext:VimObjectType>
         </vmext:VmVimObjectRef>
         <vmext:DatastoreVimObjectRef>
            <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="dao_w2k8_vc" href="https://10.20.140.167/api/admin/extension/vimServer/e7026985-19f6-4b9a-9d0d-588629e63347"/>
            <vmext:MoRef>datastore-29</vmext:MoRef>
            <vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
         </vmext:DatastoreVimObjectRef>
         <vmext:HostVimObjectRef>
            <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="dao_w2k8_vc" href="https://10.20.140.167/api/admin/extension/vimServer/e7026985-19f6-4b9a-9d0d-588629e63347"/>
            <vmext:MoRef>host-28</vmext:MoRef>
            <vmext:VimObjectType>HOST</vmext:VimObjectType>
         </vmext:HostVimObjectRef>
         <vmext:VirtualDisksMaxChainLength>1</vmext:VirtualDisksMaxChainLength>
      </vmext:VmVimInfo>
   </VCloudExtension>
…
</Vm>
 
Besides the virtual machine object itself, the VmVIMInfo element encapsulated in the VCloudExtension element of Example: XML Mapping a Virtual Machine URL to a MoRef lists a datastore object and a host object. Each section provides the vSphere entity reference (MoRef) for the corresponding entity, along with its type. The types are DATASTORE and HOST, respectively. In vCloud Director, the virtual machine can be described as virtual machine vm-63 stored in datastore datastore-29 and managed by vCenter Server dao_w2k8_vc.
In a similar way, Example: XML Mapping a Datacenter URL to a MoRef shows the administrative view of a VDC wherein the VCloudExtension element provides additional information about the corresponding entities in vSphere. In this particular case, the VDC in the example is based on a resource pool configured in vCenter Server, named dao_w2k8_vc. More information on this server can be obtained by using the vCloud API and its reference URL, which is available as the href property. The MoRef element provides the ID of the resource pool that backs the given VDC, as known to vSphere. Since a MoRef is treated as an opaque value, the VimObjectType element specifies the type of object that the MoRef points to. Combining these elements enables you to use the vSphere API and to locate the Resource Pool served by the specified vCenter Server.
 
Example: XML Mapping a Datacenter URL to a MoRef
<AdminVdc … >
<VCloudExtension required="false">
<vmext:VimObjectRef>
<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="dao_w2k8_vc" href="https://10.20.140.167/api/admin/extension/vimServer/e7026985-19f6-4b9a-9d0d-588629e63347"/>
<vmext:MoRef>resgroup-52</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</VCloudExtension>
…
</AdminVdc … >
 
Example: Using the SDK for .NET To Access MoRefs shows how to use SDK helper methods to access the vSphere specific information for the virtual machines of a given vApp.
The return value of the methods has type VimObjectRefType, which provides a reference to a vCenter Server, a MoRef to the vSphere entity, and the type of the entity it is referring to.
Example: Using the SDK for .NET To Access MoRefs
using com.vmware.vcloud.sdk;
using com.vmware.vcloud.api.rest.schema;
…
// Log in with admin privileges and get admin view of vDC containing the vApp.
…
 
VApp vapp; // VApp utility class from vCloud SDK
// Identify vApp.
…
 
List<VM> Vms;
// Get list of children VM(s)
Vms = vapp.GetChildrenVms();
foreach (VM vm in Vms)
{
  Console.WriteLine();
// Access vSphere information for VM
…
// VM Info from vSphere
  VimObjectRefType vmRef = vm.GetVMVimRef();
  Console.WriteLine(“VirtualMachine: “ + vmRef.moRefField);
 
// Datastore Info from vSphere for VM
  VimObjectRefType datastoreRef = vm.GetVMDatastoreVimRef();
  Console.WriteLine(“Datastore: “ + datastoreRef.moRefField);
 
// Host info form vSphere for VM
  VimObjectRefType hostRef = vm.GetVMHostVimRef();
  Console.WriteLine(“Host: “ + hostRef.moRefField);
}
 
Restoring vApps
During the restore process, the backup software typically restores a virtual machine in vSphere using the virtual machine configuration and disk files. In situations where the vApp has been lost from the vCloud Director inventory, the backup software needs to first restore the virtual machine in vSphere, and then import the virtual machine into vCloud Director.
Although the vApp may contain multiple virtual machines in the view of vCloud Director, the virtual machines are known individually to vSphere. To complete the restore operation, the backup software needs to re-create the restored vApp so that all the member virtual machines are created as child virtual machines of the vApp.
To re-create the vApp using the vCloud SDK for .NET, the backup software must use two method calls: ImportVmAsVapp and ImportVmIntoVapp. Use the ImportVmAsVapp method to create a vApp from any one of the child virtual machines. Then call the ImportVmIntoVapp method once for each remaining child virtual machine.
Example: Importing Virtual Machines into vApps shows how to use both methods to create a vApp using the vCloud SDK.
Example: Importing Virtual Machines into vApps
/// <summary>
/// Reference to hold the vCloud Client reference
/// </summary>
private static VcloudAdminExtension extension = null;
 
vcloudClient.login(user, password);
extension = vcloudClient.getVcloudAdminExtension();
 
// Get references for known VIM Servers
Dictionary<string, ReferenceType> vimServerRefsByName = extension.GetVMWVimServerRefsByName();
 
// Select VIM Server Reference
VMWVimServer vimServer = VMWVimServer.GetVMWVimServerByReference(
vcloudClient, vimServerRefsByName[vimServerName]);
…
// Import first VM from VIM server as vApp:
ImportVmIntoVAppParamsType importVmIntoVAppParamsType = new ImportVmIntoVAppParamsType();
importVmIntoVAppParamsType.vmMoRefField = moref; // vSphere ID from backup data.
importVmIntoVAppParamsType.vdcField = vdcRef; // vDC where the new vApp will be created.
Vapp vapp = vimServer.ImportVmAsVApp(importVmAsVAppParamsType); // Task is embedded in vapp.
...
foreach (VM vm in vms)
{
   // Import remaining VMs from VIM Server into existing vApp:
   …
   importVmIntoVAppParamsType.vmMoRefField = moref; // vSphere ID from backup data.
   importVmIntoVAppParamsType.vAppField = vapp; // vApp to hold restored VMs.
   Task task = vimServer.ImportVmIntoVApp(importVmIntoVAppParamsType);
   …
};
…
 
Example: REST API Calls To Restore a vApp shows the corresponding REST API calls used to rebuild a vApp in vCloud Director.
Example: REST API Calls To Restore a vApp
POST https://vCloud/api/admin/extension/vimServer/id/importVmAsVApp
POST https://vCloud/api/admin/extension/vimServer/id/importVmIntoExistingVApp
 
Help us improve this information. Send feedback to [email protected].