Operations

appliance

appliance access

consolecli

dcui

shell

ssh

appliance health

applmgmt

databasestorage

load

mem

softwarepackages

storage

swap

system

monitoring

appliance networking

appliance networking dns

domains

hostname

servers

interfaces

appliance recovery

appliance recovery backup

job

parts

appliance recovery restore

job

appliance system

storage

time

uptime

version

appliance techpreview

appliance techpreview localaccounts

user

appliance techpreview monitoring

snmp

appliance techpreview networking

appliance techpreview networking firewall addr

inbound

ipv4

ipv6

proxy

routes

appliance techpreview ntp

server

appliance techpreview services

status

shutdown

appliance techpreview system

update

timesync

appliance vmon

service

cis

session

• The create operation creates session token in exchange for another authentication token.
• The delete operation invalidates a session token.
• The get retrieves information about a session token.

The call to the create operation is part of the overall authentication process for API clients. For example, the sequence of steps for establishing a session with SAML token is:

• Connect to lookup service.
• Discover the secure token service (STS) endpoint URL.
• Connect to the secure token service to obtain a SAML token.
• Authenticate to the lookup service using the obtained SAML token.
• Discover the API endpoint URL from lookup service.
• Call the create operation. The create call must include the SAML token.

See the programming guide and samples for additional information about establishing API sessions.

Execution Context and Security Context

To use session based authentication a client should supply the session token obtained through the create operation. The client should add the session token in the security context when using SDK classes. Clients using the REST API should supply the session token as a HTTP header.

Session Lifetime

A session begins with call to the create operation to exchange a SAML token for a API session token. A session ends under the following circumstances:

• Call to the delete operation.
• The session expires. Session expiration may be caused by one of the following situations:
  • Client inactivity - For a particular session identified by client requests that specify the associated session ID, the lapsed time since the last request exceeds the maximum interval between requests.
  • Unconditional or absolute session expiration time: At the beginning of the session, the session logic uses the SAML token and the system configuration to calculate absolute expiration time.

When a session ends, the authentication logic will reject any subsequent client requests that specify that session. Any operations in progress will continue to completion.

Error Handling

The cis.session returns the following errors:

• vapi.std.errors.unauthenticated error for any errors related to the request.
• vapi.std.errors.service_unavailable error for all errors caused by internal service failure.

cis tagging

category

tag

tag association

content

configuration

The configuration settings are used by the Content Library Service to control the behavior of various operations.

content library

content library item

download session

A download session is an object that tracks the download of content (that is, downloading content from the Content Library Service) and acts as a lease to keep the download links available.

The content.library.item.downloadsession.file service provides access to the download links.

content library item downloadsession

file

After a download session is created against a library item, the file service can be used to retrieve all downloadable content within the library item. Since the content may not be available immediately in a downloadable form on the server side, the client will have to prepare the file and wait for the file status to become PREPARED.

See content.library.item.download_session.

file

storage

update session

An update session is a resource which tracks changes to content. An update session is created with a set of files that are intended to be uploaded to a specific content.library.item_model, or removed from an item. The session object can be used to track the uploads and inspect the changes that are being made to the item by that upload. It can also serve as a channel to check on the result of the upload, and status messages such as errors and warnings for the upload.

Modifications are not visible to other clients unless the session is completed and all necessary files have been received.

The management of the files within the session is done through the content.library.item.updatesession.file service.

content library item updatesession

file

After an update session is created against a library item, the file service can be used to make changes to the underlying library item metadata as well as the content of the files. The following changes can be made:

• deleting an existing file within the library item. This deletes both the metadata and the content.
• updating an existing file with new content.
• adding a new file to the library item.

The above changes are not applied or visible until the session is completed. See content.library.item.update_session.

subscribed item

local library

The local_library service provides support for creating and maintaining local library instances. A local library may also use the content.library service to manage general library functionality.

subscribed library

type

A library item has an optional type which can be specified with the content.library.item_model.type field. For items with a type that is supported by a plugin, the Content Library Service may understand the files which are part of the library item and can produce metadata for the item.

In other cases, uploads may require a process in which one upload implies subsequent uploads. For example, an Open Virtualization Format (OVF) package is composed of an OVF descriptor file and the associated virtual disk files. Uploading an OVF descriptor can enable the Content Library Service to understand that the complete OVF package requires additional disk files, and it can set up the transfers for the disks automatically by adding the file entries for the disks when the OVF descriptor is uploaded.

When a type is not supported by a plugin, or the type is not specified, the Content Library Service can handle a library item in a default way, without adding metadata to the item or guiding the upload process.

vapi metadata authentication

To calculate the effective authentication information for an operation element, you should first see if there is an authentication scheme specified for the operation element. If it is not specified, then authentication scheme for the service element that contains this operation element is used. If it is not specified for the service element as well, then the authentication scheme for the package element that contains this service element is used.

component

A component element is said to contain authentication information if any one of package elements contained in it has authentication information.

package

A package element is said to contain authentication information if there is a default authentication assigned to all service elements contained in the package element or if one of the service element contained in this package element has authentication information.

vapi metadata authentication service

operation

An operation element is said to contain authentication information if authentication schemes are specified in the authentication definition file.

source

The interface definition language infrastructure provides tools to generate various kinds of metadata in JSON format from the interface definition files and additional properties files. One of the generated files contains authentication information. The generated file can be registered as a source of metadata.

The authentication file contains all the data present in the interface definition files. Each authentication file contains data about one component element. When a authentication file is added as a source, each source contributes only one component element's metadata.

Authentication metadata can also be discovered from a remote server that supports the authentication metadata services (see vapi.metadata.authentication). Since multiple components can be registered with a single metadata server, when a remote server is registered as a source, that source can contribute more than one component.

vapi metadata cli

command

namespace

source

The interface definition language infrastructure provides tools to generate various kinds of metadata in JSON format from the interface definition files and additional properties files. One of the generated files contains CLI information.

A CLI metadata file contains information about one component element. When a CLI metadata file is added as a source, each source contributes only one component element's metadata.

CLI metadata can also be discovered from a remote server that supports the CLI metadata services (see vapi.metadata.cli) API. Since multiple components can be registered with a single metadata server, when a remote server is registered as a source, that source can contribute more than one component.

vapi metadata metamodel

Metamodel metadata is organized into an hierarchy of elements. The main elements are:

• Enumeration: An enumeration element that has a list of enumeration value elements.
• Constant: A constant element has a name and a value.
• Structure: A structure element can have field elements, constant elements and enumeration elements.
• Operation: An operation has a list of parameter elements, result element and error elements.
• Service: A service is a collection of operation elements, structure elements, enumerated elements and constant elements.
• Package: A package is a collection of service elements, structure elements and enumeration elements.
• Component: A component is a collection of package elements.

• A client can retrieve the exact pieces of information it requires using the various granularities the API supports (that is vapi.metadata.metamodel.component, vapi.metadata.metamodel.package, vapi.metadata.metamodel.service, vapi.metadata.metamodel.structure, vapi.metadata.metamodel.enumeration and vapi.metadata.metamodel.service.operation). In this case, it doesn't cache any information locally and always invokes operations to get the metamodel information it requires.
• A client can retrieve all the metamodel information in fewer operation invocations using the vapi.metadata.metamodel.component service and cache the output locally. It can then poll on the fingerprint information exposed by the vapi.metadata.metamodel.component service to monitor changes in API definition.

component

A component defines a set of functionality that is deployed together and versioned together. For example, all the services that belong to VMware Content Library are part of a single component. A component element describes a component. A component element contains one or more package elements.

The operations for package elements are provided by service vapi.metadata.metamodel.package.

enumeration

The enumeration has a list of enumeration value elements.

package

A package is a logical grouping of services, structures and enumerations. A package element describes the package. It contains the service elements, structure elements and enumeration elements that are grouped together.

vapi metadata metamodel resource

model

A structure is used as a model if it is used for persisting data about an entity. Some of the fields in the model structure are also used for creating indexes for querying.

One or more services can operate on the same resource type. One or more services can provide the model structure for an entity of this resource type. Using model service you can retrieve the list of all the structure elements that are model structures for a given resource type.

vapi metadata metamodel service

operation

source

The interface definition language infrastructure provides tools to generate various kinds of metadata in JSON format from the interface definition files and additional properties files. One of the generated files contains metamodel information. The generated file can be registered as a source of metadata.

The metamodel file contains all the data present in the interface definition files. Each metamodel file contains data about one component element. When a metamodel file is added as a source, each source contributes only one component element's metadata.

Metamodel metadata can also be discovered from a remote server that supports the metamodel metadata services (see vapi.metadata.metamodel). Since multiple components can be registered with a single metadata server, when a remote server is registered as a source, that source can contribute more than one component.

structure

vapi metadata privilege

An entity has a unique identifier and a resource type. An entity can either be present in one of the parameter elements or if a parameter is a structure element, it could also be present in one of the field elements.

Privileges can be assigned to either operation elements or entities used in the operation element. A list of privileges can also be applied on a package element. This list of privileges would be used as a default for all the operation elements and the entities that do not have any defined privileges.

component

A component element is said to contain privilege information if any one of package elements in it contains privilege information.

package

A package element is said to contain privilege information if there is a default privilege assigned to all service elements contained in the package element or if one of the operation elements contained in one of the service elements in this package element has privilege information.

vapi metadata privilege service

operation

An operation element is said to contain privilege information if there are any privileges assigned to the operation element or if one of the parameter elements contained in it has privileges assigned in privilege definition file.

source

The interface definition language infrastructure provides tools to generate various kinds of metadata in JSON format from the interface definition files and additional properties files. One of the generated files contains privilege information. The generated file can be registered as a source of metadata.

The privilege file contains all the data present in the interface definition files. Each privilege file contains data about one component element. When a privilege file is added as a source, each source contributes only one component element's metadata.

Privilege metadata can also be discovered from a remote server that supports the privilege metadata services (see vapi.metadata.privilege). Since multiple components can be registered with a single metadata server, when a remote server is registered as a source, that source can contribute more than one component.

vapi vcenter

activation

vcenter

cluster

datacenter

datastore

folder

host

vcenter inventory

datastore

network

vcenter iso

image

This is an API that will let its client mount or unmount an ISO image on a virtual machine as a CD-ROM.

network

vcenter ovf

It provides the ability to deploy OVF packages from the content library with support for advanced network topologies, network services, creating virtual appliances and virtual machines in hosts, resource pools or clusters. It also provides the ability to export virtual appliances and virtual machines from hosts, resource pools or clusters as OVF packages to the content library.

export flag

import flag

library item

To deploy a virtual machine or a virtual appliance from a library item:

1. Create a vcenter.ovf.library_item.deployment_target to specify the target deployment type and target deployment designation.
2. Create a vcenter.ovf.library_item.resource_pool_deployment_spec to specify the parameters for the target deployment.
3. Use the deploy operation with the created target and parameter specifications, along with the identifier of the specified source content library item. See deploy.

To create a library item in content library from a virtual machine or virtual appliance:

1. Create a vcenter.ovf.library_item.deployable_identity to specify the source virtual machine or virtual appliance to be used as the OVF template source.
2. Create a vcenter.ovf.library_item.create_target to specify the target library and library item.
3. Create a vcenter.ovf.library_item.create_spec to specify the settings for the OVF package to be created.
4. Use the create operation with the created target and parameter specifications, along with the specified source entity. See create.

resource pool

This service does not include virtual appliances in the inventory of resource pools even though part of the behavior of a virtual appliance is to act like a resource pool.

vcenter vm

VM

vcenter vm hardware

vcenter vm hardware adapter

Note that services for adapters with no configurable properties or runtime state, such as IDE and PCI adapters, are omitted.

sata

scsi

vcenter vm hardware boot

device

The boot order may be specified using a mixture of device classes and device instances, chosen from among the following:

• CDROM: Boot from a virtual CD-ROM drive; the device instance(s) will be chosen by the BIOS subsystem.
• FLOPPY: Boot from a virtual floppy drive; the device instance(s) will be chosen by the BIOS subsystem.
• DISK: Boot from a virtual disk device; the device instance is specified explicitly in vcenter.vm.hardware.boot.device.entry.disks list, and multiple instances may be specified in the list.
• ETHERNET: Boot from a virtual Ethernet adapter; the device instance is specified explicitly as vcenter.vm.hardware.boot.device.entry.nic, and multiple adapters may be specified in the boot order list.

cdrom

cpu

disk

ethernet

floppy

memory

parallel

serial

power