N VSphere 6 - Vdc- .vmware

vSphere Web Services SDK Programming GuidePerformance Intervals279ESXi Server Performance Intervals280vCenter Server Performance IntervalsvSphere Performance and Data StorageModifying Historical Intervals280281281Modifying Performance Counter Collection LevelsSample Code Reference28228318 Diagnostics and Troubleshooting 285Troubleshooting Best Practices285Overview of Configuration Files and Log FilesESXi Log File286287Virtual Machine Log Files287vCenter Server Log Files288Modifying the Log Level to Obtain Detailed InformationSetting the Log Level on ESXi SystemsGenerating Logs288289289Setting the Log Level on vCenter Server SystemsUsing DiagnosticManager290290Using the MOB to Explore the DiagnosticManagerGenerating Diagnostic Bundles292293Export Diagnostic Data By Using the vSphere Client29319 Managed Object Browser 294Using the MOB to Explore the Object ModelAccessing the MOB294294Using the MOB to Navigate the VMware Infrastructure Object ModelUsing the MOB to Invoke Methods295296Passing Primitive Datatypes to Method296Passing Arrays of Primitives to Methods296Passing Complex Structures to Methods297Using the MOB Along With the API Reference30020 HTTP Access to vSphere Server Files 302Introduction to HTTP Access302URL Syntax for HTTP Access303Datastore Access (/folder)303Host File Access (/host)304Update Package Access (/tmp)305Privilege Requirements for HTTP AccessVMware, Inc.30511

vSphere Web Services SDK Programming Guide21 Sample Program Overview 306Java Sample Programs (JAXWS Bindings)C# Sample ProgramsVMware, Inc.30631012

About This BookThe vSphere Web Services SDK Programming Guide provides information about developing applications using the VMware vSphere Web Services SDK 6.7.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 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 tohttp://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. Revision HistoryRevision DateDescription16OCT2018vSphere 6.7 Update1Added 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.19SEP2013vSphere 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.VMware, Inc.13

vSphere Web Services SDK Programming GuideTable 1. Revision History (Continued)Revision DateDescription24AUG2011vSphere 5.0 - Revised performance manager chapter. Added information about: unset properties, usingvCenter to 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 tohttp://www.vmware.com/support/pubs.Document FeedbackVMware welcomes your suggestions for improving our documentation. Send your feedback todocfeedback@vmware.com.VMware, Inc.14

VMware vSphere and thevSphere Web Services SDK1VMware 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.Figure 1‑1. vSphere APIs and CLIsVMware, Inc.15

vSphere Web Services SDK Programming GuideSDK 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 7 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.The guide includes class diagrams and instance diagrams. Figure 1‑2 shows the UML notation used formanaged objects and data objects. The diagrams use a tilde ( ) if an object has no properties ormethods. Ellipses (.) means some properties or methods are omitted.Figure 1‑2. Legend for UML Class DiagramsVMware, Inc.16

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.17

vSphere Web Services SDK Programming GuideFigure 2‑1 shows a vSphere server and client application. The client has a managed object reference to avirtual machine on the server, and a copy of the GuestInfo data object for the virtual machine. A clientmust maintain its copy of a data object because, depending on the type of client request, a vSphereserver might send property data for a data object as a set of name-value pairs associated with amanaged object reference. See the description of the ObjectContent data object in the vSphere APIReference.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.18

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 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.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.19

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 (VimServiceLocator, AppUtil) and declare the methods defined fornthe vSphere 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 vSphereWeb service(HTTPS/HTTP)VimServiceLocator classAppUtil classAccess to vSphere APImethodsVimPortType classVimService classgetPropertyName and setPropertyName methodsget and set methods defined for propertiesAccess to vSphere APIpropertiesdefined for data objectsvSphere API dataobjectsData objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxyinterfaceThe 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 18.VMware, Inc.20

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.RetrieveServiceContent method to aServiceContent data object. ServiceContent provides access to the vSphere managed objectservices. See Overview of a Java Sample Application for the Web Services SDK for an example ofconnecting to a server and using the ServiceInstance reference to retrieve the ServiceContentobject.Figure 2‑3 shows the object model for the ServiceInstance and ServiceContent objects. The figureshows 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 avalue. (The value property is an opaque string.)VMware, Inc.21

vSphere Web Services SDK Programming GuideFigure 2‑3. ManagedObjectReference Data ObjectAccess to vSphere Server DataTo obtain information about the virtual infrastructure, you retrieve managed object properties. Managedobject properties can be simple data types, such as integer or string data, or they can be complex typessuch as data objects that contain sets of properties.Obtaining Information from a ServerWith a reference to a managed object, you can obtain information about the state of the server-sideinventory objects and populate client-side data objects based on the values. You can use one of thefollowing approaches:nUse an accessor (getter) method. The client proxy interface provides accessor metho

1 VMware vSphere and the vSphere Web Services SDK 15 . Introduction to vSphere Clusters 219 VMware DRS 219 VMware HA 220 VMware HCI 220 Creating and Configuring Clusters 221 . 17 vSphere Performance 263 vSphere Performance Data Collection 263 PerformanceManager Objects and Methods 265