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:
docfeedback@vmware.com
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.
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
Contents
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.
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
Contents
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.
Index 255
Contents
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
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. Ta bl e 1 summarizes the significant changes in each version of this book.
Tabl e 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.
®
vSphere components available on
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
docfeedback@vmware.com.
12 VMware, Inc.
1
VMware vSphere and vSphere 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.
1
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.
2
vSphere API Programming Model
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.
2
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
vSphere server
VirtualMachine
managed object
vSphere client application
GuestInfo
data object
GuestInfo
data object
managed object
reference to a
VirtualMachine
data objects
network
connection
Figure 2-1. vSphere Server and Client
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
client application
vSphere Server
method
execution
method
invocation
SOAP-encoded WSDL
network
connection
WSDL2Java,
wsdl.exe, or
other tool
WSDL
files
client
proxy
interface
(Java, C#,
or other)
Figure 2-2. Client-Server Communication Through a Client Proxy Interface
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.*;
I
MPORTANT 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
Tab le 2- 1 identifies client proxy definitions for the vSphere Web Services SDK WSDL.
Tabl e 2-1 . Client Proxy Definitions
Element Access Java C#
Access to vSphere
Web service
(HTTPS/HTTP)
Access to vSphere
API methods
Access to vSphere
API properties
vSphere API data
objects
VimServiceLocator class AppUtil class
VimPortType class VimService class
get
PropertyName
methods defined for data objects
Data objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxy
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; }
and set
PropertyName
get and set methods defined for properties
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.
Tab le 2- 2 lists some of the more common XML primitive data type mappings.
Tabl e 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.
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
Chapter 2 vSphere API Programming Model
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.
I
MPORTANT 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).
Tab le 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.
Tabl e 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.
Tabl e 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.
3
Client Applications
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.
Tabl e 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
Client authentication
vCenter
Single Sign On token
Client authentication
username/password
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.
vSphere supports vCenter Single Sign On. A vCenter client can obtain a vCenter Single Sign
On token from a vCenter Single Sign On Server and use that token to login to a vCenter
Server.
Username/password authentication for client-server connections has been deprecated as of
vSphere 5.1.
3
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.
Tabl e 3-2 . Microsoft .NET Elements for vCenter Single Sign On Sessions
.NET Element /
Namespace vCenter Single Sign On Usage
SecurityPolicyAssertion
Microsoft.Web.Services3.Security
SendSecurityFilter
Microsoft.Web.Services3.Security
ServicePointManager
System.net
ConfigurationManager
System.Configuration
CookieContainer
System.Net
The sample creates a custom policy assertion derived from the
SecurityPolicyAssertion class. The custom assertion contains the
SAML token and X509 certificate.
The sample defines a custom output filter derived from the
SendSecurityFilter class. The custom filter adds the token and
certificate to the outgoing SOAP message.
The sample uses the ServicePointManager to specify SSL3 and HTTP
100-Continue behavior.
The sample uses the ConfigurationManager to specify certificate
metadata (password and certificate type).
The sample uses the CookieContainer class to manage vCenter session
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,
var customSecurityAssertion = new CustomSecurityAssertionHok();
customSecurityAssertion.BinaryToken = xmlToken;
customSecurityAssertion.TokenType = strSamlV2TokenType;
customSecurityAssertion.SecurityToken = new X509SecurityToken(certificateToBeAdded);
X509KeyStorageFlags.MachineKeySet);
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.
Loading...