123doku.com

vSphere Web Services SDK Programming GuideCreating and Configuring Resource Pools229Configuring Reservation and Limit for Resource PoolsConfiguring Priority Shares for Resource PoolsDeleting Child Resource Pools230233243Moving Resource Pools or Virtual Machines Into a Resource PoolIntroduction to vSphere ClustersVMware DRSVMware HAVMware HCI243244244244245Creating and Configuring ClustersCreating a Cluster245246Adding a Host to a ClusterReconfiguring a ClusterManaging DRS ClustersManaging HA Clusters247247248248Primary and Secondary Hosts248Failure Detection and Host Network IsolationUsing VMware HA and DRS Together24924916 Tasks and Scheduled Tasks 251Creating Tasks251Session PersistenceCancelling a Task252252Using TaskInfo to Determine Task StatusMonitoring TaskInfo Properties252253Accessing and Manipulating Multiple Tasks254Gathering Data with a ViewManager ObjectGathering Data with a TaskManager Interface255264Understanding the ScheduledTaskManager InterfaceScheduling Tasks266267Cancelling a Scheduled TaskUsing a TaskHistoryCollectorManaging the HistoryCollectorSample Code Reference27127127227217 Events and Alarms 274Event and Alarm Management ObjectsUnderstanding Events275Managing Events with EventManagerEvent Data Objects275276Formatting Event Message ContentVMware, Inc.27427710

vSphere Web Services SDK Programming GuideCreating Custom Events277Using an EventHistoryCollector279Creating an EventHistoryCollector FilterManaging the HistoryCollectorUsing Alarms280280280Obtaining a List of AlarmsCreating an Alarm281281Defining Alarms Using the AlarmSpec Data Object282Specifying Alarm Trigger Conditions with AlarmExpressionSpecifying Alarm Actions284Deleting or Disabling an AlarmSample Code Reference28328528518 vSphere Performance 287vSphere Performance Data Collection287PerformanceManager Objects and MethodsRetrieving vSphere Performance Data290291Performance Counter Example (QueryPerf)Large-Scale Performance Data Retrieval292303Using the QueryPerf Method as a Raw Data FeedComparison of Query Methods304Retrieving Summary Performance DataPerformance Counter MetadataPerfCounterInfo303304305305Performance Intervals306ESXi Server Performance Intervals306vCenter Server Performance IntervalsvSphere Performance and Data StorageModifying Historical Intervals307307308Modifying Performance Counter Collection LevelsSample Code Reference30830919 Diagnostics and Troubleshooting 311Troubleshooting Best Practices311Overview of Configuration Files and Log FilesESXi Log File312313Virtual Machine Log Files313vCenter Server Log Files314Modifying the Log Level to Obtain Detailed InformationSetting the Log Level on ESXi SystemsGenerating LogsVMware, Inc.31531531611

vSphere Web Services SDK Programming GuideSetting the Log Level on vCenter Server SystemsUsing DiagnosticManager316316Using the MOB to Explore the DiagnosticManagerGenerating Diagnostic Bundles318319Export Diagnostic Data By Using the vSphere Client31920 Managed Object Browser 320Using the MOB to Explore the Object ModelAccessing the MOB320320Using the MOB to Navigate the VMware Infrastructure Object ModelUsing the MOB to Invoke Methods321322Passing Primitive Datatypes to Method322Passing Arrays of Primitives to Methods322Passing Complex Structures to Methods323Using the MOB Along With the API Reference32621 HTTP Access to vSphere Server Files 328Introduction to HTTP Access328URL Syntax for HTTP Access329Datastore Access (/folder)329Host File Access (/host)330Update Package Access (/tmp)331Privilege Requirements for HTTP Access33122 Sample Program Overview 332Java Sample Programs (JAXWS Bindings)C# Sample ProgramsVMware, Inc.33233612

About This BookThe vSphere Web Services SDK Programming Guide provides information about developing applicationsusing the VMware vSphere Web Services SDK 6.7.VMware provides different APIs and SDKs for various applications and goals. The vSphere Web ServicesSDK targets developers who create client applications for managing VMware vSphere componentsavailable on VMware 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 HistoryThis book is revised with each release of the product or when necessary. A revised version can containminor or major changes. The following table summarizes the significant changes in each version of thisbook.Table 1-1. Revision HistoryRevision DateDescription02APR2020vSphere 7.0Added scalable shares feature. Reworked and expanded fixed shares and other resource anagement material.Added Virtual Machine Guest Operations chapter, including guest customization for instant clone virtualmachines.20AUG2019vSphere 6.7 Update 3Bug fixes. Added section on crypto key query for VM encryption.16OCT2018vSphere 6.7 Update 1Added section on Hyperconverged Infrastructure (HCI) clusters.17APR2018vSphere 6.7 - GAAdded Instant Clone material to VM Management chapter.Minor updates elsewhere.12APR2017Removed appendix with list of permissions. Was not maintained.15NOV2016vSphere 6.5 - GAAdded chapter about vSphere virtual machine encryption.Removed description of deprecated CIM Storage Management API.Updated information about session cookie management.04SEP2015Updated information about migrating VMs with vMotion across data centers.12MAR2015vSphere 6.0 - Rewrote “Exporting a Virtual Application” section in Virtual Applications chapter.VMware, Inc.13

vSphere Web Services SDK Programming GuideTable 1-1. Revision History (continued)Revision DateDescription19SEP2013vSphere 5.5 – Added a C# example of using LoginByToken; clarified limitation for HA clusters.10SEP2012vSphere 5.1 – Added information about using the SessionManager.LoginByToken method; added informationabout distributed virtual switches.24AUG2011vSphere 5.0 - Revised performance manager chapter. Added information about: unset properties, using vCenterto access host data, and using the QueryConfigOption to add devices; emphasized ListView instead ofTaskManager; 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 withSDK.13JUL2010Restructured manual and added chapters about host, storage, and networking. Revised property collectorchapter and added appendix about HTTP access.07MAY2009vSphere Web Services SDK 4.0 Programming Guide.Intended AudienceThis book is intended for anyone who needs to develop applications using the vSphere Web ServicesSDK. 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 programmingbackground in one of the stub languages (C# or Java) is required.VMware Technical Publications GlossaryVMware Technical Publications provides a glossary of terms that might be unfamiliar to you. Fordefinitions of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.Document FeedbackVMware welcomes your suggestions for improving our documentation. Send your feedback [email protected], Inc.14

About the vSphere Web ServicesSDK1VMware vSphere supports robust, fault-tolerant virtualized applications, networking, and storage.vSphere offers many optional components and modules such as VMware High Availability and VMwareVMotion. The VMware vSphere Web Services SDK gives Web services developers programmatic accessto vSphere components.This chapter includes the following topics:nvSphere Web Services SDKnSDK Developer Setup for the Web Services SDKnSDK Samples for the Web Services SDKnUML Diagrams Used in the Web Services SDK Programming GuidevSphere Web Services SDKThe vSphere Web Services SDK is the most comprehensive of the available management APIs. The SDKworks against both ESXi and vCenter Server systems.As a Web Services SDK, the SDK is language neutral. The SDK includes stubs and examples for Javaand C# and a comprehensive documentation set including an API Reference generated from the source.VMware, Inc.15

vSphere Web Services SDK Programming GuideFigure 1-1. vSphere APIs and CLIsSDK Developer Setup for the Web Services SDKBefore you can start developing applications with the vSphere Web Services SDK, you must downloadthe software and set up your system. The vSphere Web Services SDK Developers Setup Guide hascomplete instructions for Java and C# development and discusses a simplified security configuration fordevelopment environments.SDK Samples for the Web Services SDKThe SDK includes a set of samples that illustrate much of the SDK features. Two sample sets areavailable:nJava samples use the generated Java stubs that are shipped with the SDK.nC# 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 thatdoes not require utility applications to run.See #unique 6 for lists of samples for the two languages and a brief explanation of what each sampledoes.UML Diagrams Used in the Web Services SDKProgramming GuideThis guide uses UML (unified modeling language) diagrams to illustrate the API objects and theirrelationships.VMware, Inc.16

vSphere Web Services SDK Programming GuideThe guide includes class diagrams and instance diagrams. Figure 1-2. Legend for UML Class Diagramsshows the UML notation used for managed objects and data objects. The diagrams use a tilde ( ) if anobject has no properties or methods. Ellipses (.) means some properties or methods are omitted.Figure 1-2. Legend for UML Class DiagramsVMware, Inc.17

vSphere Web Services APIProgramming Model2The vSphere Web Services API is implemented as a language-neutral Web service. The API is based ona remote procedure call mechanism that client applications use to access services and components onESXi and vCenter Server systems.This chapter includes the following topics:nvSphere Client-Server ArchitecturenWeb Services API as a Web ServicenAccess to Managed ObjectsnAccess to vSphere Server DatavSphere Client-Server ArchitectureVMware vSphere client applications participate in a distributed architecture that uses an asynchronouscommunications model. This architecture is based on server-side managed objects, client-side managedobject references, and data objects.nManaged objects exist on a vSphere server (ESX/ESXi or vCenter Server system). They representvSphere services and components. Services include PropertyCollector, SearchIndex,PerformanceManager, and ViewManager. Components include inventory objects such asVirtualMachine, Datastore, and Folder.nManaged object references are client application references to server-side managed objects. Yourclient application uses ManagedObjectReference objects when it invokes operations on a server. AManagedObjectReference is guaranteed to be unique and persistent during an object's lifetime. Thereference persists after an object has moved within the inventory, across sessions, and across serverrestarts. If you remove an object, for example, a virtual machine, from the inventory, and then put itback, the reference changes.nData objects contain information about managed objects. Your client application sends data objects toand receives data objects from a vSphere server. Examples are the different specification andcapability objects such as VirtualMachineConfigSpec and HostCapability.VMware, Inc.18

vSphere Web Services SDK Programming GuideFigure 2-1. vSphere Server and Client shows a vSphere server and client application. The client has amanaged object reference to a virtual machine on the server, and a copy of the GuestInfo data object forthe virtual machine. A client must maintain its copy of a data object because, depending on the type ofclient request, a vSphere server might send property data for a data object as a set of name-value pairsassociated with a managed object reference. See the description of the ObjectContent data object inthe vSphere API Reference.Figure 2-1. vSphere Server and ClientThe VMware vSphere application model uses an asynchronous client-server communication model inmost cases. Methods are nonblocking and return a reference to a Task managed object. For moreinformation about the Task managed object, see Tasks and Scheduled Tasks.Web Services API as a Web ServiceThe vSphere Web Services API is a language-neutral Web service that runs on ESXi and vCenter Serversystems.The API complies with the Web Services Interoperability Organization (WS-I) Basic Profile 1.0. The WS-IBasic Profile 1.0 includes support for the following standards:nXML Schema 1.0nSOAP 1.1nWSDL 1.1For 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. ThevSphere API Web service provides access to all operations necessary for monitoring and managingvSphere components, such as compute resources, virtual machines, networks, storage, and so on.WSDL Files and the Client-Side Proxy InterfaceThe vSphere Web Services SDK provides a set of WSDL (Web Services Description Language) files thatdefine the vSphere Web Services API. Web-services development tools such as JAX-WS wsimport, orMicrosoft .NET wsdl.exe use these WSDL files to generate client-side proxy code (stubs).VMware, Inc.19

vSphere Web Services SDK Programming GuideThe client proxy provides a language-specific interface proxy, for example, using Java or C#. The proxyfacilitates remote method invocation, organization of object data, and other aspects of distributed, objectoriented, applications programming. Your client application calls proxy interface methods. The client proxyuses SOAP (Simple Object Access Protocol) to exchange WSDL messages with a vSphere server.Figure 2-2. Client-Server Communication Through a Client Proxy Interface is a representation of a clientapplication that uses the client proxy interface to call a method. The client proxy interface is based on theWSDL definitions.Figure 2-2. Client-Server Communication Through a Client Proxy InterfaceTo use the VMware client proxy interface, you must import the vSphere Web Services API client librariesin to your client application using the following Java and C# statements.C#using VimApi;Javaimport com.vmware.vim25.*;Important The vSphere Web Services SDK includes Java client-side proxy code that was generatedusing the JAX-WS toolkit. If the versions of Java and JAX-WS on your development platform are thesame as those used to generate the proxy interface shipped in the SDK, you do not have to generateclient-side proxy code from the WSDL. See the Developer’s Setup Guide for information about how toconfigure a development environment for the vSphere Web Services SDK.Network Access to the vSphere Web ServiceYour client application can use the vSphere Web Services API to communicate with vSphere servers overHTTPS (HTTP over an encrypted Secure Sockets Layer connection) at port 443. HTTPS is the defaultprotocol.You can configure the server to support HTTP. Use HTTP access only for test or developmentenvironments, not for production. For information about how to configure the server to support HTTPaccess, see the vSphere Web Services SDK Developer’s Setup Guide.VMware, Inc.20

vSphere Web Services SDK Programming GuideLanguage-Specific Classes and MethodsThe SOAP tools generate language-specific classes and methods that match the WSDL definitions. Thetools 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 establishthe client-server connection (VimService, AppUtil) and declare the methods defined for thenvSphere API (VimPortType, VimService).Generated methods. The additional methods are accessor (getter) and mutator (setter) methods forproperties. For Java, the method names are constructed by adding get and set prefixes to anproperty name, and changing the first character of the property name to upper case.The following table identifies client proxy definitions for the vSphere Web Services SDK WSDL.Element AccessJavaC#Access to vSphere Webservice (HTTPS/HTTP)VimService classAppUtil classAccess to vSphere APImethodsVimPortType classVimPortType classAccess to vSphere APIpropertiesgetPropertyName and setPropertyNamevSphere API data objectsData objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxyinterface(Vim25Api.VimService in vSphere 6.0 and before)get and set methods defined for propertiesmethods defined for data objectsThe following code fragments show getter and setter method definitions for theAfterStartupTaskScheduler.minute property.Javapublic 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 thevSphere API Reference. For example, the ScsiLun data object has a displayName property. For theJava API, you can use a setDisplayName method to assign a string value to the property, and obtain thestring value by using the getDisplayName method. The vSphere Web Services SDK includes Java andC# sample code that illustrates how to use the proxy interfaces. See #unique 15.VMware, Inc.21

vSphere Web Services SDK Programming GuideMapping XML Data Types to Java and C# Data TypesIn this guide, the UML class and object diagrams use the primitive data type names such as string andinteger, without the XML Schema definition namespace prefix (xsd:). The vSphere API Referencecontains the complete data type name, such as xsd:string. The data types map to the primitive datatypes of the programming language used for the client application.The following table lists some of the more common XML primitive data type mappings.XML SchemaJava.NET Data ntInt32xsd:stringjava.lang.StringStringAccess to Managed ObjectsYour client application obtains access to managed objects through the ServiceInstance managedobject and its associated ServiceContent data object. The ServiceContent data object containsmanaged 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 vCenterServer systems. The server creates the ServiceInstance, and creates the manager entities that provideservices 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 startsby connecting to a server and creating a reference to the ServiceInstance. After you have connected tothe server, you can call the ServiceInstance.RetrieveServiceC

Closing the Connection from a Web Services Client 51 Using the Java Samples as Reference 52 Multiple Versions of the vSphere API 53 Java and C# Sample Applications in the Web Services SDK 54 Java Samples in the Web Services SDK 54 C# Samples in the Web Services SDK 54 4 Datacenter Inventory 56 Invent