VMware vCenter vCenter Lab Manager 2.4 User guide

Brand: VMware vCenter

Model: vCenter Lab Manager 2.4

Type: User guide

VMware® Lab Manager

SOAP API Guide

VMware Lab Manager 2.4

VMware, Inc.

3145 Porter Drive

Palo Alto, CA 94304

www.vmware.com

2 VMware, Inc.

VMware® Lab Manager SOAP API Guide

You can find the most up-to-date technical documentation on our 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:

[email protected]

6,496,847, 6,704,925, 6,711,672, 6,725,289, 6,735,601, 6,785,886, 6,789,156, 6,795,966, 6,880,022,

6,961,941, 6,961,806 and 6,944,699; patents pending.

VMware, the VMware “boxes” logo and design, Virtual SMP and VMotion are registered trademarks or

trademarks 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 Lab Manager SOAP API Guide

Revision: 20061220

Item: VL-ENG-Q406-301

VMware, Inc. 3

Contents

Preface 7

1 IntroducingVMwareLabManagerSOAPAPI 11

IntegratingLabManagerwithAutomatedTestingTools 12

SupportedOperations 12

LabManagerDataObjects 12

StandardsComplianceandCompatibleDevelopmentPlatforms 13

Security 13

UserAuthentication 13

2 GettingStartedwiththeLabManagerSOAPAPI 15

Requirements 16

ObtainingandImportingtheWSDL 16

ImportingtheWSDLFileintoYourDevelopmentPlatform 16

InstructionsforUsingMicrosoftVisualStudiowithLabManagerWSDL 17

SimpleandAdvancedCodeSamples 18

SimpleC#ConsoleApplication 19

AdvancedSample:IntegratingLabManagerandQualityCenter 21

3 LabManagerAPIDataTypes 27

PrimitiveXMLDataTypes 28

LabManagerDataTypes 28

AuthenticationHeader 29

SupportedAPICalls 29

Fields 29

SampleUsage:C# 29

Configuration 30

Machine 30

4 LabManagerAPIMethodReference 33

ConfigurationCapture 35

Syntax 35

VMware® Lab Manager SOAP API Guide

4 VMware, Inc.

Arguments 35

Response 35

SampleCode:C# 35

ConfigurationCheckout 36

Syntax 36

Arguments 36

Response 36

SampleCode:C# 37

ConfigurationClone 38

Syntax 38

Arguments 38

Response 38

SampleCode:C# 38

ConfigurationDelete 39

Syntax 39

Arguments 39

Response 39

SampleCode:C# 39

ConfigurationDeploy 40

Syntax 40

Arguments 40

Response 40

SampleCode:C# 41

ConfigurationPerformAction 41

Syntax 42

Arguments 42

Response 42

SampleCode:C# 42

ConfigurationSetPublicPrivate 43

Syntax 43

Arguments 43

Response 43

SampleCode:C# 43

ConfigurationUndeploy 44

Syntax 44

Arguments 44

Response 44

SampleCode:C# 44

GetConfiguration 45

Syntax 45

VMware, Inc. 5

Contents

Response 45

SampleCode:C# 46

GetConfigurationByName 46

Syntax 46

Arguments 47

Response 47

SampleCode:C# 47

GetMachine 48

Syntax 48

Arguments 48

Response 48

SampleCode:C# 48

GetMachineByName 49

Syntax 49

Arguments 49

Response 49

SampleCode:C# 50

GetSingleConfigurationByName 50

Syntax 50

Arguments 50

Response 51

SampleCode:C# 51

ListConfigurations 52

Syntax 52

Arguments 52

Response 52

SampleCode:C# 52

ListMachines 53

Syntax 53

Arguments 53

Response 54

SampleCode:C# 54

LiveLink 55

Syntax 55

Arguments 55

Response 55

SampleCode:C# 55

MachinePerformAction 56

Syntax 56

Arguments 57

VMware® Lab Manager SOAP API Guide

6 VMware, Inc.

Response 57

SampleCode:C# 57

Index 59

VMware, Inc. 7

ThisprefaceprovidesinformationabouttheVMwareLabManagerSOAPAPIGuideand

linkstoVMware

®

technicalsupportandeducationalresources.

Thisprefacecontainsthefollowingtopics:

 “A b o u t ThisBook”

 “TechnicalSupportandEducationResources”

About This Book

UsetheVMwareLabManagerSOAPAPIGuidetodevelopapplicationsthatleverageLab

ManagerWebservicedata,automatetasks,orintegrateLabManagerwithother

softwaretestingtools.

Intended Audience

ThisguideisintendedfordeveloperswhowanttoleverageLabManagerdatafor

customizedtestingsolutions,orintegrateLabManagerandothersoftwaretestingtools

intheirenvironment.Forexample,usingtheLabManagerSOAPAPIletsyouintegrate

LabManagerwithautomatedsoftwaretestingtools,suchasMercuryQuality

Center.

Thisguideassumesyouhavesomefamiliaritywith:

 Virtualmachinetechnology

 Distributed,multitieredsystemsconcepts

 Developmentandtestingpractices

Preface

VMware® Lab Manager SOAP API Guide

8 VMware, Inc.

 WindowsorLinuxoperatingsystems

 WebServices,SOAP,andXML

Document Feedback

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

[email protected]

Conventions

Table P‐1illustratesthetypographicconventionsusedinthismanual.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.

Self-Service Support

UsetheVMwareTechnologyNetwork(VMTN)forself‐helptoolsandtechnical

information:

 Productinformation–http://www.vmware.com/products/

 Technologyinformation–http://www.vmware.com/vcommunity/technology

 Documentation–http://www.vmware.com/support/pubs

 VMTNKnowledgeBase–http://www.vmware.com/support/kb

 Discussionforums–http://www.vmware.com/community

 Usergroups–http://www.vmware.com/vcommunity/usergroups.html

Table P-1. Conventions in this Manual

Style Elements

Blue(onlineonly) Cross‐referencesandemailaddresses

Blueboldface(onlineonly) Links

Blackboldface Userinterfaceelementssuchasbuttonnamesandmenuitems

Monospace Commands,filenames,directories,andpaths

Monospace bold Userinput

Italic Documenttitles,glossary terms,andoccasionalemphasis

<Name> Variableandparameternames

VMware, Inc. 9

Preface

FormoreinformationabouttheVMwareTechnologyNetwork,goto:

http://www.vmtn.net

Online and Telephone Support

Useonlinesupporttosubmittechnicalsupportrequests,viewyourproductand

contractinformation,andregisteryourproducts.Goto:

http://www.vmware.com/support

Customerswithappropriatesupportcontractsshouldusetelephonesupportforthe

fastestresponseonpriority1issues.Goto:

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

Support Offerings

FindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds.Goto:

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

VMware Education Services

VMwarecoursesofferextensivehands‐onlabs,casestudyexamples,andcourse

materialsdesignedtobeusedason‐the‐jobreferencetools.Formoreinformationabout

VMwareEducationServices,goto:

http://mylearn1.vmware.com/mgrreg/index.cfm

VMware® Lab Manager SOAP API Guide

10 VMware, Inc.

VMware, Inc. 11

TheLabManagerWebserviceSOAPAPIprovidesprogrammaticaccesstotheLab

Managersystem.Byusingthesecureapplicationprogramminginterface(API),youcan

connecttoLabManagerServertoautomateorperformvariousoperations.

TheLabManagerWebserviceSOAPAPIusesXML‐basedtechnologies,including

SimpleObjectAccess

Protocol(SOAP)asthecommunicationprotocolandWeb

ServicesDescriptionLanguage(WSDL)astheinterfacedescriptionlanguage.TheLab

ManagerWSDLfiledetailstheavailablemethodsofthe service(called“operations”in

WebServicesvernacular)andparametertypes,aswellastheSOAPendpointforthe

service.

Thischaptercoversthese

topics:

 “IntegratingLabManagerwithAutomatedTestingTools”onpage 12

 “SupportedOperations”onpage 12

 “LabManagerDataObjects”onpage 12

 “StandardsComplianceandCompatibleDevelopmentPlatforms”onpage 13

 “Security”onpage 13

Introducing VMware Lab

Manager SOAP API

VMware® Lab Manager SOAP API Guide

12 VMware, Inc.

Integrating Lab Manager with Automated Testing Tools

TheLabManagerWebserviceSOAPAPIallowsyoutoleverageLabManagerdata

usingthelanguageandplatformofyourchoice.TheexamplesinthisguideusetheC#

programminglanguageandtheMicrosoft.NETframework,butotherprogramming

languagesanddevelopmentenvironmentsarealsosupported.Ifyouareusing

a

languageotherthanC#,seethedocumentationonyourdevelopmentenvironmentfor

comparableinformationaboutdevelopingWebserviceapplications.

InadditiontoextendingorcustomizingLabManagerbyusingtheSOAPAPI,youcan

alsointegrateLabManagerwithautomatedtestingsystems.Youcanseeanexampleof

thisintegration

in“AdvancedSample:IntegratingLabManagerandQualityCenter”

onpage 21.

FormoreinformationaboutLabManagersolutions,developerresources,and

communityresources,gotohttp://www.vmware.com.

Supported Operations

UsingyourpreferredWeb‐enableddevelopmentenvironment,youcanconstructWeb

serviceclientapplicationsusingstandardWebserviceprotocolstoprogrammatically:

 Queryforvirtualmachineandconfigurationinformation.

 Performactionsonmachinesandconfigurations.

 Capture,checkout,clone,delete,anddeployconfigurations.

 CreateaLiveLinkconfigurationURLyoucanemailtootherteammembers.

FordetailedinformationaboutsupportedWebserviceoperations,see“LabManager

APIMethodReference”onpage 33.

Lab Manager Data Objects

TheLabManagerWebserviceSOAPAPIinteractswiththedatainyourorganization

usingobjects,whichareprogrammaticrepresentationsoftheLabManagerdata.Object

propertiesrepresentfieldsinthosedataentities.Forexample,aLabManager

configurationisrepresentedbyaConfigurationobject,whichhasfieldsthatrepresent

the

configurationname,configurationnumericidentifier,deploymentstatus,shared

state,andmore.

Thisdocumentdescribeshowtoperformoperationssuchasquery,clone,capture,and

deployonLabManagerdatausingtheLabManagerdataobjects.Fordetailed

information,see“LabManagerAPIDataTypes”onpage 27.

VMware, Inc. 13

Chapter 1 Introducing VMware Lab Manager SOAP API

Standards Compliance and Compatible Development

Platforms

TheLabManagerWebServiceSOAPAPIcomplieswithSOAP1.1,WSDL1.1,and

otherstandardsidentifiedintheWS‐IBasicProfileVersion1.1.TheLabManagerWeb

ServiceSOAPAPIworkswithcurrentSOAPdevelopmentenvironmentsthatadhere

totheBasicProfileVersion1.1standards.Theexamplesinthis

documentusethe

MicrosoftVisualStudio.NET2003developmentenvironmentandtheC#

programminglanguage.

IfyouareusingVisualStudiofor.NETdevelopment,VMwarerecommendsthatyou

useVisualStudio2003orhigher.

Security

ClientapplicationsthataccesstheLabManagerdatainyourorganizationaresubjectto

thesamesecurityprotectionsthatareusedintheLabManagerWebconsole.Lab

ManagerexposesallSOAPAPImethodsusingSSL.

WhenaccessingtheSOAPAPIwiththeWebserviceURL,youmightseeanSSL

certificatewarning.Acceptthecertificate tousetheAPIorreplacethecertificatewitha

validsignedcertificate.

User Authentication

Clientapplicationsmustprovidevalidcredentials—aLabManageruseraccountand

password—witheachLabManagerWebservicemethodcall.Theuseraccountmust

haveAdministratorprivilegesontheLabManagerServ er.TheLabManagerServer

authenticatesthesecredentials.

OTE Implementationdifferencesincertaindevelopmentplatformsmightprevent

accesstosomeorallofthefeaturesintheLabManagerWebserviceSOAPAPI.

VMware® Lab Manager SOAP API Guide

14 VMware, Inc.

VMware, Inc. 15

YoucanreviewintroductoryinformationaboutusingtheLabManagerWebservice

SOAPAPItodevelopanXMLWebserviceclient.AnXMLWebserviceclientisany

componentorapplicationthatreferencesandusesanXMLWebservice.Thisdoesnot

needtoinvolveaclient‐basedapplication.Inmany

cases,XMLWebserviceclients

mightbeotherWebapplications,suchasWebFormsorevenotherXMLWebservices.

Thischaptercoversthesetopics:

 “Requirements”onpage 16

 “ObtainingandImportingtheWSDL”onpage 16

 “SimpleandAdvancedCodeSamples”onpage 18

Getting Started with the Lab

Manager SOAP API

VMware® Lab Manager SOAP API Guide

16 VMware, Inc.

Requirements

TheinstructionsinthischapterassumethataninstanceofLabManagerisinstalled,

configured,andrunningonyournetwork.Beforeyoucanstartdevelopingan

application,reviewtheserequirements:

 YoumustknowtheaddressoftheLabManagerserverinstance,startingwithits

fully‐qualifiedhostnameorIPaddress.

Forexample,https://hostname.company.com/LabManager.

 YoumusthaveanaccountwithLabManagerAdministratorprivilegesonthe

targetLabManagerserver.

IfyouarenotanAdministrator,haveyourLabManagerAdministratorsetyouup

withaLabManageraccount.

AssumingyouhaveanappropriateaccountontheLabManagerServer,youcan

continuewith“Obtaining

andImportingtheWSDL.”

Obtaining and Importing the WSDL

Aswithanystandards‐basedSOAPAPIimplementation,theLabManagerAPI

definitionisavailableontheWebserviceasanXML‐formattedWSDLfile.

ToobtaintheWSDL,launchInternetExplorer5.5orhigherandnavigatetothisURL

foryourLabManagerServer:

https://<hostname>/LabManager/SOAP/LabManager.asmx?WSDL

TheWSDLdefinesalltheLabManagerAPIcallsandobjects.

FormoreinformationonWSDL,see:

http://www.w3.org/TR/wsdl

Importing the WSDL File into Your Development Platform

AfteryouobtaintheWSDL,importitintoyourdevelopmentenvironmentand

generatethenecessaryobjectsforuseinbuildingclientWebserviceapplications.The

processdependsonyourdevelopmentenvironment,programminglanguage,and

associatedtools.Forexample,theMicrosoftVisualStudiodevelopmentenvironment

handlesthetasksautomatically.

Thenextsection

providesanexampleofobtainingtheWSDLandimportingitinthe

MicrosoftVisualStudio2003.Forinstructionsaboutotherdevelopmentplatforms,see

theproductdocumentationforyourplatform.

VMware, Inc. 17

Chapter 2 Getting Started with the Lab Manager SOAP API

Instructions for Using Microsoft Visual Studio with Lab Manager

WSDL

MicrosoftVisualStudioprogramminglanguagesaccesstheLabManagerWebservice

APIthroughobjectsthatserveasproxiesfortheirserver‐sidecounterparts.

WhenaccessingXMLWebservicesinmanagedcode,aproxyclassandthe.NET

Frameworkhandlealloftheinfrastructurecoding.

BeforeyoucanusetheLabManager

WebserviceAPIwithVisualStudio,youmustfirst

generatetheproxyclassobjectfromtheWSDLfile.

VisualStudioprovidesawizard(“AddaWebReference”)toconnecttoaWebservice

andgeneratethenecessaryartifacts.YoucanaddaWebreferencetoanexisting

applicationorcreatea

newapplicationinVisualStudio.

TheinstructionsbelowarespecifictoMicrosoftVisualStudio2003.

To add a Web reference

1FromtheWindowsStartmenu,launchMicrosoftVisualStudio.NET2003.

TheVisualStudioenvironmentopens.

2 SelectNewProjecttocreateanewproject,orselectOpentoopenanexisting

project.

3InVisualStudio,choose

AddWebReferencefromtheProjectmenu.

4IntheURLtextbox,typetheURLtoobtaintheservicedescriptionoftheLab

ManagerWebservice:

https://<hostname>/LabManager/SOAP/LabManager.asmx

5ClickGo.

ThecertificateexchangebetweentheLabManagerserverandthedevelopment

environmentclientbegins.Asecurityalertdisplaysthedetailsofthecertificate

sentfromtheserver.

6ClickYestoproceed.

OTE ThesecurityalertmessagesaregeneratedwhentheLabManagerserveruses

thedefault,self‐signedcertificates.Youcanreplacethesecertificatesonthe

LabManagerserverwithcertificatespurchasedfromVerisign,Thawte,and

othercertificateauthorities.

VMware® Lab Manager SOAP API Guide

18 VMware, Inc.

AnalertfromtheVisualStudioenvironmentmightappear.ClickYestoproceed.

TheMicrosoftVisualStudioenvironmentconnectstotheWebserviceendpoint

anddisplaystheoperationsdescribedintheLabManagerWebserviceWSDL.

7 SelectthetextintheWebreferencenametextboxandrenametheWebreference

toLabManagerSoap,thenamespaceusedforthisWebreference.

“LabManagerSoap”isoneword,withoutspaces.

8ClickAddReferencetocompletetheprocess.

Acertificatewarningmessagemightappear.ClickYes.

9ClickYesagaintoproceed.

Formoreinformation,seethe“A d d i n g andRemovingWebReferences”topicin

theVisualStudiodocumentation.

VisualStudio

retrievestheservicedescriptionandgeneratesaproxyclass

(LabManagerSoap)thatservesasaninterfacetotheLabManagerWebservicefrom

yourapplication.Attheendoftheprocess,theclassgetsaddedtotheWebReferences

folderoftheproject.(ClickSolutionExplorertoseeLabManagerSoaplistedinthe

Web

Referencesfolder .)

Withthisbasicsetuptaskcompleted,youcanbuildclientapplicationsthatusetheLab

ManagerWebServiceSOAPAPI.ThefastestwaytobecomefamiliarwiththeAPIisby

walkingthroughthecodesamplelistedinthenextsection.

Simple and Advanced Code Samples

Thissectioncontainstwocodesamples—onesimpleandonemorecomplex—written

inC#usingtheMicrosoftVisualStudio2003IDE.

AssumingthatyouhaveaLabManagerinstancerunning,yourprogramming

environmentissetup,andyouhavetheappropriatepermissionsontheLabManager

server(see“Requirements”onpage 16),you

cantestbasicAPIprogramming

connectivitybetweenyourdevelopmentworkstationandyourLabManagerWeb

servicebyusingthe“SimpleC#ConsoleApplication.”Copythecodelistingdisplayed

inthenextsection,andpasteitintoyourMicrosoftVisualStudio2003environment.

OTE VMwareassumesyouarefamiliarwithbasicprogrammingconceptsand

alreadyhaveaprogrammingdev elopmentenvironmentsetuponyour

computer.IfyouareusingaprogramminglanguageotherthanC#andaWeb

servicesdevelopmentenvironmentotherthanMicrosoftVisualStudio2003,

seetheappropriatedocumentationformoreinformation.

VMware, Inc. 19

Chapter 2 Getting Started with the Lab Manager SOAP API

Thecodeperformsseveralsimpletasks.Thefirsttwotasks(bindingtotheWebservice

andprovidingcredentials)aretypicallyrequiredofanyapplicationthatmakescallsto

aLabManagerWebservice:

 BindstotheLabManagerWebServiceSOAPAPI.

 SetsuptheusernameandpasswordformakingaSOAPcall.

 SetsuptheServicePointManagercertificatepolicytoaccepttheSSLcertificate.You

mustsetupthecertificatepolicytoacceptallcertificatestoconnecttotheAPI.

 Makesacalltogetaconfigurationobjectbasedonname.

 Displaysallconfigurationfieldsintheconsole.

Simple C# Console Application

using System;

using System.Net;

namespace LMConsoleApplication1

{

class Class1

{

/// <summary>

/// The main entry point for the application.

/// </summary>

[STAThread]

static void Main(string[] args)

{

try

{

//** Bind to the Lab Manager SOAP API Web Service

LabManagerSoap.VMwareLabManagerSOAPinterface binding =

new LabManagerSoap.VMwareLabManagerSOAPinterface();

//** Enter the URL for your system here

binding.Url ="https://10.6.1.248/LabManager/SOAP/LabManager.asmx;

binding.Timeout = 10 * 60 * 1000; // 10 minutes

ServicePointManager.CertificatePolicy = new CertificateAccepter();

//**

//** Allocate AuthenticationHeader object to hold caller’s

//** username and password

//**

binding.AuthenticationHeaderValue = new

LabManagerSoap.AuthenticationHeader();

VMware® Lab Manager SOAP API Guide

20 VMware, Inc.

//** Substitute a real user’s username and password here

binding.AuthenticationHeaderValue.username = "jaya";

binding.AuthenticationHeaderValue.password = "Lab Manager";

//**

//** Call GetSingleConfigurationByName()

//** Get default configuration that comes with Lab Manager

//** installation and write all property values to console

//**

LabManagerSoap.Configuration defCfg=

binding.GetSingleConfigurationByName("Sample 1");

//** Print out all configuration properties to the Console

Console.WriteLine("Name = " + defCfg.name);

Console.WriteLine("ID = " + defCfg.id.ToString());

Console.WriteLine("Description = "+ defCfg.description);

Console.WriteLine("isPublic = "+ defCfg.isPublic.ToString());

Console.WriteLine("isDeployed = "+ defCfg.isDeployed.ToString());

Console.WriteLine("fenceMode = "+ defCfg.fenceMode.ToString());

Console.WriteLine("type = " + defCfg.type.ToString());

Console.WriteLine("owner = " + defCfg.owner);

Console.WriteLine("dateCreated = " +

defCfg.dateCreated.ToString());

Console.ReadLine();

}

catch (Exception e)

{

Console.WriteLine("Error: " + e.Message);

Console.ReadLine();

}

} //** end Main

} //** end Class1

/// <summary>

/// This class is needed to automatically accept the SSL certificate

/// the Lab Manager sends on each API call.

/// </summary>

public class CertificateAccepter : System.Net.ICertificatePolicy

{

public CertificateAccepter() {}

public bool CheckValidationResult(

System.Net.ServicePoint servicePoint,

System.Security.Cryptography.X509Certificates.X509Certificate cert,

System.Net.WebRequest webRequest, int iProblem)

Page is loading ...

VMware vCenter vCenter Lab Manager 2.4 User guide

VMware vCenter vCenter Lab Manager 2.4 User guide

VMware vCenter vCenter Lab Manager 2.4 User guide

Related papers

Other documents