VMware vSphere Web Services SDK - 6.0 Programming Guide

vSphere Web Services SDK

Programming Guide

vSphere Web Services SDK 6.0

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.

EN-001411-02

vSphere Web Services SDK Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

[e-mail]

Copyright © 2011-2015 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

VMware, Inc.

3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

2	VMware, Inc.

Contents

About This Book		11
1 VMware vSphere and vSphere Management APIs												13
Virtualization and VMware vSphere Components										13
vSphere Development Tools				14
vSphere Web Services SDK					14
CIM APIs	14
vSphere SDK for Perl 14
vSphere PowerCLI			14
VIX API	14
SDK Developer Setup			15
SDK Samples	15
UML Diagrams Used in This Guide							15
2 vSphere API Programming Model								17
vSphere Client-Server Architecture						17
vSphere API as a Web Service					18
WSDL Files and the Client-Side Proxy Interface											18
Network Access to the vSphere Web Service										19
Language-Specific Classes and Methods									19
Mapping XML Data Types to Java and C# Data Types												20
Access to Managed Objects				21
Access to vSphere Server Data					21
Obtaining Information from a Server								22
Working with Data Structures						22
Accessing Property Values					22
Unset Optional Properties					25
Escape Character in Name and Path Properties											25
3 Client Applications			27
vCenter Server Connections				27
Establishing a Single Sign On Session with a vCenter Server 28
LoginByToken (C# Example) 28
LoginByToken (Java Example)						33
Establishing a Session with Username and Password Credentials 38
Overview of a Java Sample Application									38
Web Server Session Token				41
Accessing the HTTP Endpoint with JAX-WS										42
Accessing the vSphere Server						43
Closing the Connection				44
Using the Java Samples as Reference								44
Multiple Versions of the vSphere API							45
Identifying the API Version Supported by the Server											46
Java and C# Sample Applications						46
Java Samples		46
C# Samples		46
VMware, Inc.												3

vSphere Web Services SDK Programming Guide

4 Datacenter Inventory		49
Inventory Overview		49
Inventory Hierarchies and ServiceInstance				50
Folders in the Hierarchy			50
ESXi Inventory Hierarchy 51
Accessing Inventory Objects			51
Creating Inventory Objects			52
Privileges Required for Inventory Management 52
Privileges	53
Permissions	53
Managed and Standalone ESX/ESXi Hosts				54

5 Property Collector	57
Introduction to the PropertyCollector 57
Data Retrieval	58
Inventory Traversal and Object Selection			58
vSphere Data Objects for Property Collection			58
vSphere Methods for Property Collection 58
PropertyCollector Example (RetrievePropertiesEx)				59
Inventory Traversal	66
TraversalSpec Traversal		66
SelectionSpec Traversal		72
Client Data Synchronization (WaitForUpdatesEx)				77
Property Filters	77
WaitForUpdatesEx 77
Server Data Transmission		79
PropertyCollector Performance 79
SearchIndex 79

6 Authentication and Authorization 81
Objects for Authentication and Authorization Management						81
Authentication and Authorization for ESXi and vCenter Server							82
ESXi User Model 82
vCenter Server User Model		83
vSphere Security Model	83
Setting Up Users, Groups, and Permissions			84
Obtaining User and Group Information from UserDirectory						85
Managing ESXi Users with HostLocalAccountManager					86
Managing Roles and Permissions with AuthorizationManager							86
Using Roles to Consolidate Sets of Privileges				88
Modifying Sample Roles to Create New Roles				89
Granting Privileges Through Permissions			89
Authenticating Users Through SessionManager				91
Using VMware Single Sign On for vCenter Server Sessions							91
Using the Credential Store for Automated Login				91
Credential Store Methods	92
Credential Store Backing File		92
Credential Store Samples	93
Specifying Roles and Users with the Credential Store					93
Managing Licenses with LicenseManager 94

7 Hosts 95

Host Management Objects	95
Retrieving Host Information	95
4	VMware, Inc.

Contents

	Configuring and Reconfiguring Hosts							96
	Managing the Host Lifecycle				97
	Reboot and Shutdown			97
	Using Standby Mode			97
	Disconnecting and Reconnecting Hosts								97
	Querying and Changing the Host Time							98
	Querying Virtual Machine Memory Overhead									98
8	Storage 99
	Storage Management Objects				99
	Introduction to Storage		100
	How Virtual Machines Access Storage								100
	Datastores 101
	Choosing the Storage API to Use						102
	Configuring Disk Partitions				103
	Multipath Management		104
	Configuring iSCSI Storage			104
	Creating and Managing Datastores						106
	Accessing Datastores			107
	Creating and Modifying a VMFS Datastore									107
	Removing and Updating Datastores							109
	Managing VMFS Datastores with HostStorageSystem												109
	Managing VMFS Volume Copies (Resignaturing)										109
	Managing Diagnostic Partitions					110
	Retrieving Diagnostic Partition Information										111
	Creating a Diagnostic Partition						111
	Sample Code Reference		111
9	vSphere Networks 113
	Virtual Switches	113
	Using a Distributed Virtual Switch						114
	Distributed Virtual Switch Configuration									115
	Backup, Rollback, and Query Operations									116
	VMware Standard Virtual Switch						116
	vNetwork Standard Switch Environment									117
	Setting Up Networking with vSS 118
	Defining the Host Network Policies							120
	NIC Teaming	120
	Setting Up IPv6 Networking					121
	Adding Networking Services						122
	Sample Code Reference		122
10	Virtual Machine Configuration						125
	VirtualMachine Management Objects and Methods											125
	Creating Virtual Machines and Virtual Machine Templates												126
	Creating a Virtual Machine Using VirtualMachineConfigSpec 126
	Creating Virtual Machine Templates							127
	Cloning a Virtual Machine					127
	Converting a Template to a Virtual Machine										128
	Accessing Information About a Virtual Machine											128
	Configuring a Virtual Machine					129
	Name and Location		130
	Hardware Version 130
	Boot Options	131
VMware, Inc.													5

vSphere Web Services SDK Programming Guide

Operating System 131
CPU and Memory Information	132
Networks 133
Fibre Channel NPIV Settings	133
File Locations 134

	Adding Devices to Virtual Machines							134
	Performing Virtual Machine Power Operations										135
	Registering and Unregistering Virtual Machines										136
	Customizing the Guest Operating System									137
	Installing VMware Tools			137
	Upgrading a Virtual Machine					138
11	Virtual Machine Management						139
	Virtual Machine Migration				139
	Cold Migration	140
	Migration with VMotion				140
	Using Storage VMotion				140
	Snapshots 140
	Creating a Snapshot			141
	Reverting to a Snapshot				141
	Deleting a Snapshot			142
	Linked Virtual Machines			142
	Linked Virtual Machines and Disk Backings										142
	Creating a Linked Virtual Machine								143
	Removing Snapshots and Deleting Linked Virtual Machines 144
	Relocating a Virtual Machine in a Linked Virtual Machine Group 144
	Promoting a Virtual Machine's Disk								145
	Performing Advanced Manipulation of Delta Disks 145
12	Virtual Applications		147
	About Virtual Applications				147
	Management Overview				147
	Direct and Linked Children						148
	OVF Packages	148
	Creating a VirtualApp		149
	Managing VirtualApp Children						149
	Exporting a Virtual Application						150
	VirtualApp and OvfManager Methods									150
	VirtualApp Data Structures						151
	OvfManager Data Structures						152
	Example of Generating an OVF Package									152
	Importing an OVF Package				154
	Virtual Application Life Cycle					154
	Powering a Virtual Application On or Off 154
	Unregistering a Virtual Application								155
	Suspending a Virtual Application								155
	Destroying a Virtual Application							155
13	Resource Management			157
	Resource Management Objects					157
	Introduction to Resource Management								158
	Resource Allocation	158
	Resource Pool Hierarchies					158
	Resource Pool Management Guidelines									159
6											VMware, Inc.

Contents

Cluster Overview 159
Creating and Configuring Resource Pools				160
Understanding Expandable Reservation				160
Deleting Child Resource Pools			161
Moving Resource Pools or Virtual Machines Into a Resource Pool 162
Introduction to VMware DRS and VMware HA Clusters 162
VMware DRS	162
VMware HA	162
Creating and Configuring Clusters			163
Creating a Cluster		163
Adding a Host to a Cluster 164
Reconfiguring a Cluster 164
Managing DRS Clusters		164
Managing HA Clusters		165
Using VMware HA and DRS Together				166

14 Tasks and Scheduled Tasks		167
Creating Tasks 167
Session Persistence	167
Cancelling a Task	168
Using TaskInfo to Determine Task Status				168
Monitoring TaskInfo Properties			169
Accessing and Manipulating Multiple Tasks				170
Gathering Data with a ViewManager Object					170
Gathering Data with a TaskManager Interface					177
Understanding the ScheduledTaskManager Interface 179
Scheduling Tasks	180
Cancelling a Scheduled Task 182
Using a TaskHistoryCollector		183
Creating a TaskHistoryCollector Filter 183
Managing the HistoryCollector			183
Sample Code Reference 184

15 Events and Alarms 185
Event and Alarm Management Objects				185
Understanding Events	185
Managing Events with EventManager 186
Event Data Objects	187
Formatting Event Message Content				187
Creating Custom Events		188
Using an EventHistoryCollector 188
Creating an EventHistoryCollector Filter 188
Managing the HistoryCollector			189
Using Alarms 189
Obtaining a List of Alarms		189
Creating an Alarm	190
Defining Alarms Using the AlarmSpec Data Object 190
Specifying Alarm Trigger Conditions with AlarmExpression 191
Specifying Alarm Actions		192
Deleting or Disabling an Alarm			193
Sample Code Reference	193

16 vSphere Performance 195

vSphere Performance Data Collection	195
VMware, Inc.	7

vSphere Web Services SDK Programming Guide

PerformanceManager Objects and Methods	197
Retrieving vSphere Performance Data 198
Performance Counter Example (QueryPerf) 199
Large-Scale Performance Data Retrieval	206
Using the QueryPerf Method as a Raw Data Feed 206
Comparison of Query Methods 207
Retrieving Summary Performance Data	207
Performance Counter Metadata 208
Performance Intervals 208

	vSphere Performance and Data Storage							210
	Modifying Historical Intervals						210
	Modifying Performance Counter Collection Levels											210
	Sample Code Reference		211
A	Diagnostics and Troubleshooting							213
	Troubleshooting Best Practices					213
	Overview of Configuration Files and Log Files										214
	ESX/ESXi Log File		214
	Virtual Machine Log Files					215
	vCenter Server Log Files				216
	Modifying the Log Level to Obtain Detailed Information 216
	Setting the Log Level on ESX/ESXi Systems										216
	Generating Logs	217
	Setting the Log Level on vCenter Server Systems											217
	Using DiagnosticManager			217
	Using the MOB to Explore the DiagnosticManager 219
	Generating Diagnostic Bundles					220
B	Managed Object Browser				221
	Using the MOB to Explore the Object Model									221
	Accessing the MOB		221
	Using the MOB to Navigate the VMware Infrastructure Object Model 222
	Using the MOB to Invoke Methods						222
	Passing Primitive Datatypes to Method								222
	Passing Arrays of Primitives to Methods									223
	Passing Complex Structures to Methods									223
C HTTP Access to vSphere Server Files									227
	Introduction to HTTP Access					227
	URL Syntax for HTTP Access					228
	Datastore Access (/folder)					228
	Host File Access (/host)			229
	Update Package Access (/tmp)						230
	Privilege Requirements for HTTP Access									230
D Privileges Reference			231
	Privileges Required to Invoke Operations								231
	Privileges Required to Read Properties							239
	Privileges Defined for the Administrator Role									240
E	Sample Program Overview					245
	Java Sample Programs (JAXWS Bindings)								245
	C# Sample Programs	249
	Axis 4.1 252
8												VMware, Inc.

Contents

Index 255

VMware, Inc.

9

vSphere Web Services SDK Programming Guide

10	VMware, Inc.

About This Book

The vSphere Web Services SDK Programming Guide provides information about developing applications using theVMware® vSphere Web Services SDK 6.0.

VMware provides different APIs and SDKs for various applications and goals. The vSphere Web Services SDK targets developers who create client applications for managing VMware® vSphere components available on VMware ESX/ESXi and VMware vCenter Server systems.

To view the current version of this book as well as all VMware API and SDK documentation, go to http://www.vmware.com/support/pubs/sdk_pubs.html.

Revision History

This book is revised with each release of the product or when necessary. A revised version can contain minor or major changes. Table 1 summarizes the significant changes in each version of this book.

Table 1. Revision History

Revision Date Description

04Sep2015 Updated information about migrating VMs with VMotion across data centers.

12Mar2015 vSphere 6.0 - Rewrote “Exporting a Virtual Application” section in Virtual Applications chapter.

19Sep2013 vSphere 5.5 – Added a C# example of using LoginByToken; clarified limitation for HA clusters.

10Sep2012 vSphere 5.1 – Added information about using the SessionManager.LoginByToken method; added information about distributed virtual switches.

24AUG2011 vSphere 5.0 - Revised performance manager chapter. Added information about: unset properties, using vCenter to access host data, and using the QueryConfigOption to add devices; emphasized ListView instead of TaskManager; clarified limits and limitations of Linked Virtual Machines; updated samples in chapters 3,5,14, and 16; replaced information about Axis bindings with JAX-WS; and updated paths to samples supplied with SDK.

13JUL2010 Restructured manual and added chapters about host, storage, and networking. Revised property collector chapter and added appendix about HTTP access.

07MAY2009 vSphere Web Services SDK 4.0 Programming Guide.

Intended Audience

This book is intended for anyone who needs to develop applications using the vSphere Web Services SDK. Developers typically create client applications using Java or C# (in the Microsoft .NET environment) targeting VMware vSphere. An understanding of Web Services technology and some programming background in one of the stub languages (C# or Java) is required.

VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.

VMware, Inc.

11

vSphere Web Services SDK Programming Guide

Document Feedback

VMware welcomes your suggestions for improving our documentation. Send your feedback to [e-mail].

12	VMware, Inc.

VMware vSphere and vSphere	1
Management APIs

VMware vSphere supports robust, fault-tolerant virtualized applications, networking, and storage. vSphere offers many optional components and modules such as VMware High Availabiltiy and VMware VMotion. The VMware vSphere Web Services SDK gives Web services developers programmatic access to vSphere components.

The chapter includes the following topics:

“Virtualization and VMware vSphere Components” on page 13

“vSphere Development Tools” on page 14

“SDK Developer Setup” on page 15

“SDK Samples” on page 15

“UML Diagrams Used in This Guide” on page 15

Virtualization and VMware vSphere Components

VMware software products virtualize computing resources, including CPU, memory, storage, and networks. Virtualization provides an abstraction layer between computing resources, physical storage, and networking hardware, and the applications that use the resources.

VMware vSphere includes ESXi, vCenter Server, and several additional server products. The base products support running and managing virtual machines. With additional licenses, you can take advantage of the vSphere distributed resource management (DRS), disaster recovery, and high availability (HA) features.

The ESXi hypervisor is capable of supporting multiple virtual machines and other virtual components, such as storage and networks.

vCenter Server provides central management for all of the components of a virtualized environment, including multiple ESX/ESXi host systems, clusters, storage, and distributed virtual switches. It is distributed in two package formats:

Windows-based software services.

Linux-based VMware vCenter Server Appliance.

vSphere Web Client is a GUI to manage vSphere. It provides the UI platform that you use to integrate your solution with vSphere. The vSphere Web Client also includes a server-side Java platform. You can develop Java plugins that use the vSphere Web Services SDK to communicate with vSphere servers. See the vSphere Web Client SDK for more information about building UI and service plugins for the vSphere Web Client.

For more information about ESXi and vCenter Server, see the VMware vSphere documentation page on the VMware Web site. If you are new to VMware vSphere or new to the vSphere Web Services SDK, see one of these vSphere administrator documents for background information about vSphere:

vSphere Virtual Machine Administration Guide

VMware, Inc.

13

vSphere Web Services SDK Programming Guide

vCenter Server and Host Management Guide

vSphere Resource Management Guide

vSphere Development Tools

VMware supports SDKs and scripting tools for managing vSphere.

vSphere Web Services SDK

The vSphere Web Services SDK is the most comprehensive of the available management APIs. The SDK works against both ESX/ESXi and vCenter Server systems. As a Web Services SDK, the SDK is language neutral. The SDK includes stubs and examples for Java and C# and a comprehensive documentation set including an API Reference generated from the source.

CIM APIs

The VMware CIM APIs provide a CIM (Common Information Model) interface for developers building management applications. With the VMware CIM APIs, developers can use standards-based CIM-compliant applications to manage ESX/ESXi hosts.

The CIM APIs include:

CIM SMASH/Server Management API – profiles compatible with the DMTF System Management Architecture for Server Hardware (SMASH) initiative. SMASH profiles allow CIM clients to monitor system health of a managed server.

CIM Storage Management API – profiles compatible with the Storage Management Initiative Specification (SMI-S) of the Storage Network Industry Association. SMI-S profiles allow CIM clients to explore the virtual machines on an ESX/ESXi host, and associated storage resources.

vSphere SDK for Perl

The vSphere SDK for Perl is an easy-to-use Perl scripting interface to the vSphere API. Administrators and developers can work with vSphere API objects using vSphere SDK for Perl subroutines. Administrators can use the utility applications included with vSphere SDK for Perl.

The vSphere SDK for Perl also includes the Web Services for Management component for writing scripts that retrieve CIM data from the ESX/ESXi host using CIMOM, a service that provides standard CIM management functions. The vSphere SDK for Perl also includes subroutines for managing the VMware Credential Store and an example application that illustrates credential store use.

vSphere SDK for Perl is bundled with the vSphere Command-Line Interface (vSphere CLI). The vSphere CLI command set allows you to run common system administration commands against ESX/ESXi systems from an administration server of your choice.

vSphere PowerCLI

VMware vSphere PowerCLI provides a Windows PowerShell interface to the vSphere API. vSphere PowerCLI includes PowerShell Cmdlets for administering vSphere components. In addition, the vSphere PowerCLI package includes the vSphere SDK for .NET for developers who want to create their own applications.

VIX API

The VIX API is a library for writing scripts and programs to manipulate virtual machines. It is high-level, easy to use, and practical for both script developers and application programmers. This API is well suited for dedicated IT personnel in an organization building their own in-house tools. It might also be used by software vendors using VIX to integrate VMware products with their own products or to build management products for virtual machines.

14	VMware, Inc.

Chapter 1 VMware vSphere and vSphere Management APIs

Figure 1-1 gives an overview of the different vSphere APIs and CLIs and illustrates how they fit into the virtual infrastructure.

Figure 1-1. vSphere APIs and CLIs

SDK Developer Setup

Before you can start developing applications with the vSphere Web Services SDK, you must download the software and set up your system. The Developers Setup Guide has complete instructions for Java and C# development and discusses a simplified secure setup for development environments.

SDK Samples

The SDK includes a set of samples that illustrate much of the SDK features. Two sample sets are available:

Java samples use the generated Java stubs that are shipped with the SDK.

C# samples use the generated C# stubs that are shipped with the SDK.

Both sample sets include a set of utility applications that are used by the sample code.

The code fragments in this guide are in part based on the Java sample applications, but present code that does not require utility applications to run.

See Appendix E, “Sample Program Overview,” on page 245 for lists of samples for the two languages and a brief explanation of what each sample does.

UML Diagrams Used in This Guide

This guide uses UML (unified modeling language) diagrams to illustrate the API objects and their relationships. The guide includes class diagrams and instance diagrams. Figure 1-2 shows the UML notation used for managed objects and data objects. The diagrams use a tilde (~) if an object has no properties or methods. Ellipses (...) means some properties or methods are omitted.

Figure 1-2. Legend for UML Class Diagrams

VMware, Inc.

15

vSphere Web Services SDK Programming Guide

16	VMware, Inc.

vSphere API Programming Model	2

The vSphere API is implemented as a language-neutral Web service. The API is based on a remote procedure call mechanism that client applications use to access services and components on ESX, ESXi, and vCenter Server systems.

This chapter includes the following topics:

“vSphere Client-Server Architecture” on page 17

“vSphere API as a Web Service” on page 18

“Access to Managed Objects” on page 21

“Access to vSphere Server Data” on page 21

vSphere Client-Server Architecture

VMware vSphere client applications participate in a distributed architecture that uses an asynchronous communications model. This architecture is based on server-side managed objects, client-side managed object references, and data objects.

Managed objects exist on a vSphere server (ESX/ESXi or vCenter Server system). They represent vSphere services and components. Services include PropertyCollector, SearchIndex, PerformanceManager, and ViewManager. Components include inventory objects such as VirtualMachine, Datastore, and

Folder.

Managed object references are client application references to server-side managed objects. Your client application uses ManagedObjectReference objects when it invokes operations on a server. A ManagedObjectReference is guaranteed to be unique and persistent during an object's lifetime. The reference persists after an object has moved within the inventory, across sessions, and across server restarts. If you remove an object, for example, a virtual machine, from the inventory, and then put it back, the reference changes.

Data objects contain information about managed objects. Your client application sends data objects to and receives data objects from a vSphere server. Examples are the different specification and capability objects such as VirtualMachineConfigSpec and HostCapability.

Figure 2-1 shows a vSphere server and client application. The client has a managed object reference to a virtual machine on the server, and a copy of the GuestInfo data object for the virtual machine. A client must maintain its copy of a data object because, depending on the type of client request, a vSphere server might send property data for a data object as a set of name-value pairs associated with a managed object reference. See the description of the ObjectContent data object in the vSphere API Reference.

VMware, Inc.

17

vSphere Web Services SDK Programming Guide

Figure 2-1. vSphere Server and Client

vSphere server

vSphere client application

data objects

managed object

VirtualMachine

reference to a

managed object

VirtualMachine

network

connection

GuestInfo

GuestInfo

data object

data object

The VMware vSphere application model uses an asynchronous client-server communication model in most cases. Methods are nonblocking and return a reference to a Task managed object. See Chapter 14, “Tasks and Scheduled Tasks,” on page 167.

vSphere API as a Web Service

The vSphere API is a language-neutral Web service that runs on ESX/ESXi and vCenter Server systems. The vSphere API complies with the Web Services Interoperability Organization (WS-I) Basic Profile 1.0. The WS-I Basic Profile 1.0 includes support for:

XML Schema 1.0

SOAP 1.1

WSDL 1.1

For information about the WS-I Basic Profile 1.0, go to the Web Services Interoperability Organization (WS-I) Web site at http://www.ws-i.org.

Web services support operations, which are the same as methods in other programming languages. The vSphere API Web service provides access to all operations necessary for monitoring and managing vSphere components, such as compute resources, virtual machines, networks, storage, and so on.

WSDL Files and the Client-Side Proxy Interface

The vSphere Web Services SDK provides a set of WSDL (Web Services Description Language) files that define the vSphere Web Services API. Web-services development tools such as JAX-WS wsimport, or Microsoft .NET wsdl.exe use these WSDL files to generate client-side proxy code (stubs).

The client proxy provides a language-specific vSphere API, for example, using Java or C#. The proxy facilitates remote method invocation, organization of object data, and other aspects of distributed, object-oriented, applications programming. Your client application calls proxy interface methods. The client proxy uses SOAP (Simple Object Access Protocol) to exchange WSDL messages with a vSphere server.

Figure 2-2 is a representation of a client application that uses the client proxy interface to call a method. The client proxy interface is based on the WSDL definitions.

18	VMware, Inc.

Chapter 2 vSphere API Programming Model

Figure 2-2. Client-Server Communication Through a Client Proxy Interface

WSDL		WSDL2Java,
		wsdl.exe, or
files
		other tool

client application
			client				vSphere Server
			proxy
			interface		SOAP-encoded WSDL
method			(Java, C#,				method
			or other)		network
invocation							execution
					connection

To use the VMware client proxy interface, you must import the vSphere API client libraries in to your client application using the following Java and C# statements.

C#	using VimApi;
Java	import com.vmware.vim25.*;

IMPORTANT The vSphere Web Services SDK includes Java client-side proxy code that was generated using the JAX-WS toolkit. If the versions of Java and JAX-WS on your development platform are the same as those used to generate the proxy interface shipped in the SDK, you do not have to generate client-side proxy code from the WSDL. See the Developer’s Setup Guide for information about configuring a development environment for the vSphere Web Services SDK.

Network Access to the vSphere Web Service

Your client application can use the vSphere API to communicate with vSphere servers over HTTPS (HTTP over an encrypted Secure Sockets Layer connection) at port 443. HTTPS is the default protocol. You can configure the server to support HTTP. Use HTTP access only for test or development environments, not for production. See the Developer’s Setup Guide for details.

Language-Specific Classes and Methods

The SOAP tools generate language-specific classes and methods that match the WSDL definitions. The tools also produce objects and methods that are not in the WSDL files.

Generated objects. The additional objects provide access to the vSphere Web Service to establish the client-server connection (VimServiceLocator, AppUtil) and declare the methods defined for the vSphere API (VimPortType, VimService).

Generated methods. The additional methods are accessor (getter) and mutator (setter) methods for properties. For Java, the method names are constructed by adding get and set prefixes to a property name, and changing the first character of the property name to upper case.

VMware, Inc.

19

vSphere Web Services SDK Programming Guide

Table 2-1 identifies client proxy definitions for the vSphere Web Services SDK WSDL.

Table 2-1. Client Proxy Definitions

Element Access	Java	C#
Access to vSphere	VimServiceLocator class	AppUtil class
Web service
(HTTPS/HTTP)
Access to vSphere	VimPortType class	VimService class
API methods
Access to vSphere	getPropertyName and setPropertyName	get and set methods defined for properties
API properties	methods defined for data objects
vSphere API data	Data objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxy
objects	interface

The following code fragments show getter and setter method declarations for the

AfterStartupTaskScheduler.minute property.

Java

public int getMinute() { return minute; }

public void setMinute(int minute) { this.minute = minute; }

C#

public int minute { set; get; }

You can extrapolate the getter and setter methods that are available in the client proxy interface from the vSphere API Reference. For example, the ScsiLun data object has a displayName property. For the Java API, you can use a setDisplayName method to assign a string value to the property, and obtain the string value by using the getDisplayName method. The vSphere Web Services SDK includes Java and C# sample code that illustrates using the proxy interfaces. See Chapter 3, “Client Applications,” on page 27.

Mapping XML Data Types to Java and C# Data Types

In this guide, the UML class and object diagrams use the primitive data type names such as string and integer, without the XML Schema definition namespace prefix (xsd:). The vSphere API Reference contains the complete data type name, such as xsd:string. The data types map to the primitive data types of the programming language used for the client application.

Table 2-2 lists some of the more common XML primitive data type mappings.

Table 2-2. Standard XML Schema Primitives to Java and .NET Data Type Mappings

XML Schema	Java	.NET Data Type
xsd:base64binary	byte[]	Byte[]
xsd:boolean	boolean	Boolean
xsd:byte	byte	SByte
xsd:dateTime	java.util.Calendar	DateTime
xsd:decimal	java.math.BigDecimal	Decimal
xsd:double	double	Double
xsd:float	float	Single
xsd:int	int	Int32
xsd:string	java.lang.String	String

20	VMware, Inc.

Chapter 2 vSphere API Programming Model

Access to Managed Objects

Your client application obtains access to managed objects through the ServiceInstance managed object and its associated ServiceContent data object. The ServiceContent data object contains managed object references to services and manager entities, and to the root folder of the inventory.

The ServiceInstance managed object is the root object of the inventory on both ESX/ESXi and vCenter Server systems. The server creates the ServiceInstance, and creates the manager entities that provide services in the virtual environment. Examples of manager entities are LicenseManager,

PerformanceManager, and ViewManager.

The ServiceInstance is the primary point of access to the server inventory. Your client application starts by connecting to a server and creating a reference to the ServiceInstance. After you have connected to the server, you can call the ServiceInstance.RetrieveServiceContent method to a ServiceContent data object. ServiceContent provides access to the vSphere managed object services. See “Overview of a Java Sample Application” on page 38 for an example of connecting to a server and using the ServiceInstance reference to retrieve the ServiceContent object.

Figure 2-3 shows the object model for the ServiceInstance and ServiceContent objects. The figure shows some of the ServiceContent managed object references and the target objects of the references. Each managed object reference identifies a specific managed object on the server with its type and a value. (The value property is an opaque string.)

Figure 2-3. ManagedObjectReference Data Object

Access to vSphere Server Data

To obtain information about the virtual infrastructure, you retrieve managed object properties. Managed object properties can be simple data types, such as integer or string data, or they can be complex types such as data objects that contain sets of properties.

VMware, Inc.

21

vSphere Web Services SDK Programming Guide

Obtaining Information from a Server

With a reference to a managed object, you can obtain information about the state of the server-side inventory objects and populate client-side data objects based on the values. You can use one of the following approaches:

Use an accessor (getter) method. The client proxy interface provides accessor methods for each data object property. You can use these accessor methods to obtain the values of the object. See “Language-Specific Classes and Methods” on page 19 for information about client proxy interface accessor methods.

Use a PropertyCollector to navigate to a selected point on the server and obtain values from specific properties. See Chapter 5 for more information about PropertyCollector.

Use the SearchIndex managed object to obtain a managed object reference to the managed entity of interest. The SearchIndex can return managed object references to specific managed entities—ComputeResource, Datacenter, Folder, HostSystem, ResourcePool,

VirtualMachine—given an inventory path, IP address, or DNS name.

IMPORTANT You can use API methods to operate on managed objects in the vSphere inventory. A method that updates properties in one managed object may also update properties in other managed objects. The Server performs asynchronous updates to the inventory. There is no guarantee that the inventory will be completely updated when the method returns to the caller. Use the PropertyCollector method WaitForUpdatesEx to obtain property changes.

Working with Data Structures

Properties contain information about the server-side objects at a given point in time. The value of a property can be of one of the following types:

Simple data types, such as a string, boolean, or integer (or other numeric) audiotape. For example, the ManagedEntity managed object has a name property that takes a string value.

Arrays of simple data types or data objects. For example, a HostSystem managed object contains an array of managed object references (a type of data object) to virtual machines hosted by that physical machine. As another example, the SessionManager managed object has a sessionList property that is an array of UserSession data objects.

Enumerated types (enumeration, enum) of predefined values. The values can be a collection of simple data types or data objects. For example, a virtual machine's power state can be one of three possible string values—poweredOn, poweredOff, or suspended.

The type of a property is often a string, but the property actually expects one of the values an enumeration encapsulates. For example, when you set VirtualMachineConfigSpec.guestid you can specify one of the elements of the VirtualMachineGuestOSIdentifier as a string.

Complex (or composite) data types. For example, the HostProfileConfigInfo object contains data objects, an array of data objects, and an array of strings.

Accessing Property Values

To use the composite data structures and arrays that contain Server data:

Use dot notation to access nested properties in composite data structures.

Cast unconstrained property values (xsd:anyType) to array types.

Use keys or index values as appropriate to access array values.

Nested Properties and Property Paths in Composite Data Structures

vSphere Data objects can include properties that are defined as composite data types, such as data objects. The embedded data objects can also contain properties that are data objects. Properties can nest to several levels.

22	VMware, Inc.

Chapter 2 vSphere API Programming Model

For example, the following figure shows a UML class diagram of the VirtualMachine managed object, which has a runtime property that is defined as an xsd:dateTime data type. VirtualMachine also has a summary property that is a VirtualMachineSummary data object. The VirtualMachineSummary data object contains a config property that is a VirtualMachineConfigSummary data object.

Figure 2-4. VirtualMachine Managed Object and Nested Properties

To refer to a nested property, use dot notation to separate the object names in the sequence that defines the path to the property. Your code must handle the type referenced at the end of the sequence.

For example, you can compare the property referenced by the path summary.config.guestId (a string value) to the property referenced in the path summary.config (the complete VirtualMachineSummary data object).

Table 2-3 shows examples of property references and the corresponding data types for some of the properties of the VirtualMachine managed object shown in Figure 2-4.

Table 2-3. Nested Properties and Data Types

Reference	Data Type
summary	VirtualMachineSummary data object
summary.config	VirtualMachineConfigSummary data object
summary.config.guestID	string

xsd:anyType Arrays

The vSphere API uses xsd:anyType unconstrained type declarations. A vSphere client must map values of xsd:anyType to explicit data types. An xsd:anyType value can represent a single data value or it can represent an array. The WSDL for the vSphere API defines array types for all of the data values that a vSphere client can send or receive as arrays. The array types use the prefix "ArrayOf". An example of an array type is ArrayOfString for string values.

When a client sends data to a vSphere Server, the client must use explicit datatypes. For example, a client can define a MethodAction for a ScheduledTask. The vSphere API defines arguments to the action (the MethodActionArgument.value property) as type xsd:anyType. If the action takes an array argument, the client must set the corresponding MethodAction.argument[].value to the appropriate ArrayOf... type.

When a client receives xsd:anyType data from a vSphere Server, it must cast the data to an explicit type. For example, the PropertyCollector method RetrievePropertiesEx returns a set of ObjectContent data objects. The ObjectContent.propSet property is a list of DynamicProperty objects that contains the requested property values. Each DynamicProperty object contains a name-value pair. The value property (DynamicProperty.val) is of type xsd:anyType. It can represent a single object or an array of objects.

When the returned value is a single object such as an Event, ManagedObjectReference, or String, you can cast it directly to a variable of the appropriate type. However, when the value is an array of objects you cannot cast the anyType value directly to an array variable.

VMware, Inc.

23

vSphere Web Services SDK Programming Guide

When the PropertyCollector returns array data, it sends it as an xsd:anyType value. The language-specific bindings contain definitions for array objects such as ArrayOfEvent, ArrayOfManagedObjectReference, and ArrayOfString, and corresponding "get" methods. To extract the actual array from a property of type xsd:anyType, cast DynamicProperty.val to the appropriate array type and use the matching get method – for example, getEvent(), getManagedObjectReference(), or getString().The following sections provide examples of how to cast returned values for a few of the array types. The code uses the JAX-WS-generated Java bindings for the VMware vSphere Web Services SDK WSDL. Each of the code fragments uses this logic:

Use the DynamicProperty.getVal() method to retrieve the anyType property value.

Specify the appropriate array type to cast the anyType value.

Use the corresponding get method to assign the result of the cast operation to a list variable.

Event Array Example

/*

*Handling arrays of Event objects.

*Cast the return value to ArrayOfEvent and use getEvent().

*/

List[] eventList = ((ArrayOfEvent) dynamicProp.getVal()).getEvent();

ManagedObjectReference Array Example

/*

*Handling arrays of ManagedObjectReference objects.

*Cast the return value to ArrayOfManagedObjectReference and use getManagedObjectReference().

*/

List[] morList = ((ArrayOfManagedObjectReference)dynamicProp.getVal()).getManagedObjectReference();

String Array Example

/*

*Handling arrays of strings.

*Cast the return value to ArrayOfString and use getString().

*/

List[] stringList = ((ArrayOfString) dynamicProp.getVal()).getString();

Indexed Array and Key-Based Array Properties

The VMware vSphere data structures include array properties, which can be indexed arrays or key-based arrays.

Indexed arrays are accessed by using an index integer. Indexed arrays are used for arrays of data types whose positions in the array do not change. For example, the roleList property of the AuthorizationManager managed object is an array of authorization roles. Adding a new role to the array does not change the position of existing elements in the array.

Key-based arrays are used for information whose position is subject to change. A key-based array (same basic concept as a Perl hash or a Python dictionary) uses a unique, unchanging value as a key to access an element’s value. Typically, the key is a string, but integers can also be used. For example, Event arrays use integers as keys. Nested properties can also refer to entries in a key-based array. For example, a.b.c["xyz"] refers to the property c that has the key value of xyz.

The vSphere management object model uses key-based arrays to track managed object references. The contents of a key-based array property are accessed by the value of either the key property or, in the case of a managed object reference, its value property. The value of these fields is unique across all of the components of an array.

24	VMware, Inc.

Chapter 2 vSphere API Programming Model

Unset Optional Properties

Many of the Data Objects in the vSphere Web Services SDK have optional properties that may be set by your client application or by a Server process or event. If you retrieve a data object that has a optional property that is unset, the Server will not return a value for the optional property. If you call an accessor function to retrieve the property value, the value returned by the function depends on the programming language that you are using.

For example, if you are programming in Java or C#, the value you will receive for an unset property is “null”.

Figure 2-5 shows part of the Properties table for the HostFirewallInfo Data Object in the vSphere Web Services SDK API Reference. When you look at properties in the vSphere Web Services SDK API Reference, you can see that optional properties are marked with a red asterisk.

In this example, that the defaultPolicy property is always returned, but the ruleset property will be returned as a null value if it has not been set.

Figure 2-5. Data Object - HostFirewallInfo Properties

Since Data Objects are part of many different constructs, there is no standard scenario for when an optional property should be set, what will happen if an optional property is left unset, or what you should do if a null value is returned.

Escape Character in Name and Path Properties

The percent sign (%) is used as an escape character to embed special characters in strings. For example, %2f (or %2F) is interpreted as the slash (/) character. To include a percent sign as a literal in a string, use %%.The path to the inventory starts from the root folder (ServiceContent.rootFolder property), denoted by the slash character.

Table 2-4. Special Characters

Character	Description	Representation in URL
%	Percent sign	%25
/	Slash	%2F, %2f
\	Backslash	%5C, %5c
-	Dash	%2D, %2d
.	Dot	%2E, %2e
“	Double quotation mark	%2B, %2b

VMware, Inc.

25

vSphere Web Services SDK Programming Guide

26	VMware, Inc.

Client Applications	3

This chapter includes the following topics:

“vCenter Server Connections” on page 27

“Establishing a Single Sign On Session with a vCenter Server” on page 28

“Establishing a Session with Username and Password Credentials” on page 38

“Web Server Session Token” on page 41

“Multiple Versions of the vSphere API” on page 45

“Identifying the API Version Supported by the Server” on page 46

“Helper Classes for C# Sample Applications” on page 46

vCenter Server Connections

Every vCenter Server client application must connect to the Server and pass user account credentials to authenticate to the Server. After the connection has been established, the client application can use vSphere services to access the virtual environment.

vSphere uses SSL certificates, HTTP tokens, and vCenter Single Sign On tokens to authenticate a client and support a persistent connection between the client and vCenter Server. The following table provides an overview of these elements.

Table 3-1. Security Elements for Client-Server Connections

Security Element	Description
SSL certificates	vSphere Servers use standard X.509 version 3 (X.509v3) certificates to encrypt session
	information sent over Secure Socket Layer (SSL) protocol connections. In a production
	environment, client applications verify the vSphere Server certificate during the connection
	sequence. The examples in this chapter and the examples in the vSphere Web Services SDK
	accept all certificates.
HTTP tokens	A vSphere Server uses an HTTP token to identify a client session. The Server provides the
	HTTP token in its response to a client connection request. Subsequent messages between the
	client and the Server include the HTTP token in the HTTP header.
Client authentication	vSphere supports vCenter Single Sign On. A vCenter client can obtain a vCenter Single Sign
vCenter	On token from a vCenter Single Sign On Server and use that token to login to a vCenter
Single Sign On token	Server.
Client authentication	Username/password authentication for client-server connections has been deprecated as of
username/password	vSphere 5.1.

VMware, Inc.

27

vSphere Web Services SDK Programming Guide

Establishing a Single Sign On Session with a vCenter Server

vSphere uses single sign on to provide a single point of authentication for clients. vSphere includes the vCenter Single Sign On Server. To use vCenter Single Sign On, your client obtains a SAML token (Security Assertion Markup Language) from the vCenter Single Sign On Server and passes the token to the vCenter Server in the login request. The token represents the client and contains claims that support client authentication. Components in the vSphere environment perform operations based on the original authentication. For information about obtaining a vCenter Single Sign On token from the vCenter Single Sign On Server, see vCenter Single Sign On Programming Guide.

To use single sign on, your client calls the LoginByToken method. Your client must send a SAML token to the vCenter Server by embedding the token in the SOAP header for the LoginByToken request. During the login sequence, your client must save and restore the HTTP session cookie. The vCenter Single Sign On SDK contains sample code that demonstrates how to use the LoginByToken method.

The following sections describe examples of using the LoginByToken method to establish a vCenter Single Sign On session with a vCenter Server.

“LoginByToken (C# Example)” on page 28

“LoginByToken (Java Example)” on page 33

LoginByToken (C# Example)

The following sections describe a C# example of using the LoginByToken method.

vCenter Server Single Sign On Session

After you obtain a SAML token from the vCenter Single Sign On Server, you can use the vSphere API method LoginByToken to establish a single sign on session with a vCenter Server. To establish a vCenter Server session that is based on SAML token authentication, the client must embed the SAML token in the SOAP header of the LoginByToken request. The C# LoginByToken example uses the following .NET services to support a single sign on session.

Table 3-2. Microsoft .NET Elements for vCenter Single Sign On Sessions

.NET Element /
Namespace	vCenter Single Sign On Usage
SecurityPolicyAssertion	The sample creates a custom policy assertion derived from the
Microsoft.Web.Services3.Security	SecurityPolicyAssertion class. The custom assertion contains the
	SAML token and X509 certificate.
SendSecurityFilter	The sample defines a custom output filter derived from the
Microsoft.Web.Services3.Security	SendSecurityFilter class. The custom filter adds the token and
	certificate to the outgoing SOAP message.
ServicePointManager	The sample uses the ServicePointManager to specify SSL3 and HTTP
System.net	100-Continue behavior.
ConfigurationManager	The sample uses the ConfigurationManager to specify certificate
System.Configuration	metadata (password and certificate type).
CookieContainer	The sample uses the CookieContainer class to manage vCenter session
System.Net	cookies.

Persistent vCenter Sessions

A persistent vCenter session relies on a session cookie. When the vCenter Server receives a connection request (SessionManager.RetrieveServiceContent), the Server creates a session cookie and returns it in the HTTP header of the response. The client-side .NET framework embeds the cookie in HTTP messages that the client sends to the Server.

28	VMware, Inc.

Chapter 3 Client Applications

The LoginByToken request includes the SAML token and client certificate security assertions for client authentication. After successful login, the authentication overhead is no longer needed. The client resets the VimService context to eliminate the security overhead. Subsequent client requests will contain the session cookie, which is enough to support the persistent, authenticated session.

Sample Code

The code examples in the following sections show how to use the LoginByToken method with a holder-of-key security token. The code examples are based on the LoginByTokenSample project contained in the vCenter Single Sign On SDK. The project is located in the dotnet samples directory (SDK/ssoclient/dotnet/cs/samples/LoginByToken).

Project file – LoginByToken.csproj

Sample code – LoginByTokenSample.cs

SOAP header manipulation code – CustomSecurityAssertionHok.cs

Using LoginByToken

The example program uses the following elements and general steps:

LoginByTokenSample Constructor

Token Acquisition

Security Policies

Connection and Login

LoginByTokenSample Constructor

The LoginByTokenSample class constructor creates the following elements to set up access to the vCenter Server.

VimService object – Provides access to vSphere API methods and support for security policies and session cookie managment. It also stores the vCenter Server URL.

CookieContainer – Provides local storage for the vCenter session cookie.

ManagedObjectReference – Manually created ManagedObjectReference to retrieve a

ServiceInstance at the beginning of the session.

The following code fragment shows the LoginByTokenSample constructor.

Example 3-1. LoginByTokenSample Constructor

// Global variables

private VimService _service;

private ManagedObjectReference _svcRef; private ServiceContent _sic;

private string _serverUrl;

public LoginByTokenSample(string serverUrl)

{

_service = new VimService(); _service.Url = serverUrl; _serverUrl = serverUrl;

_service.CookieContainer = new System.Net.CookieContainer(); _svcRef = new ManagedObjectReference();

_svcRef.type = "ServiceInstance"; _svcRef.Value = "ServiceInstance";

}

VMware, Inc.

29

vSphere Web Services SDK Programming Guide

Token Acquisition

The client must obtain a SAML token from a vCenter Single Sign On Server. See the vCenter Single Sign On Programming Guide.

Security Policies

The LoginByToken sample creates a custom policy assertion that is derived from the .NET class SecurityPolicyAssertion. The assertion class gives the .NET framework access to the SAML token and the X509 certificate.

The sample performs the following operations to set up the security policy and message handling.

Sets the ServicePointManager properties to specify SSL3 and HTTP 100-Continue response handling. 100-Continue response handling supports more efficient communication between the client and vCenter Server. When the client-side .NET framework sends a request to the Server, it sends the request header and waits for a 100-Continue response from the Server. After it receives that response, it sends the request body to the Server.

Creates an X509Certificate2 object, specifies the certificate file, and imports the certificate. The certificate file specification indicates a PKCS #12 format file (Public-Key Cryptography Standards) – PfxCertificateFile. The file contains the client’s private key and public certificate. The PfxCertificateFile setting is defined in the app.config file in the LoginByToken project. The definition specifies the location of the file.

Creates a custom security assertion to store the SAML token and the certificate. The token and certificate will be included in the policy data for the LoginByToken request.

Defines a custom output filter that is derived from the .NET class SendSecurityFilter.

Custom Security Assertion The following code fragment shows the LoginByTokenSample class method

GetSecurityPolicyAssertionForHokToken. The method returns a CustomSecurityAssertionHok instance which overrides the .NET class SecurityPolicyAssertion. The security assertion contains the SAML token and the X509 certificate token. This code is taken from the LoginByToken project file samples/LoginByToken/CustomSecurityAssertionHok.cs.

Example 3-2. Setting Up Security Policies

private SecurityPolicyAssertion GetSecurityPolicyAssertionForHokToken(XmlElement xmlToken)

{

//When this property is set to true, client requests that use the POST method //expect to receive a 100-Continue response from the server to indicate that //the client should send the data to be posted. This mechanism allows clients //to avoid sending large amounts of data over the network when the server, //based on the request headers, intends to reject the request ServicePointManager.Expect100Continue = true; ServicePointManager.SecurityProtocol = SecurityProtocolType.Ssl3;

X509Certificate2 certificateToBeAdded = new X509Certificate2();

string certificateFile = ConfigurationManager.AppSettings["PfxCertificateFile"]; string password = ConfigurationManager.AppSettings["PfxCertificateFilePassword"]; certificateToBeAdded.Import(certificateFile, password ?? string.Empty,

X509KeyStorageFlags.MachineKeySet);

var customSecurityAssertion = new CustomSecurityAssertionHok(); customSecurityAssertion.BinaryToken = xmlToken; customSecurityAssertion.TokenType = strSamlV2TokenType;

customSecurityAssertion.SecurityToken = new X509SecurityToken(certificateToBeAdded);

return customSecurityAssertion;

}

Custom Output Filter The following code fragment shows the custom output filter for the custom security assertion. The custom filter provides three methods:

30	VMware, Inc.