vCloud SDK for PHP Developer's Guide vCloud Director 5.1 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.
vCloud SDK for PHP Developer's 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 © 2010–2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents vCloud SDK for PHP Developer's Guide 5 1 About the VMware vCloud API 7 Object Taxonomy 8 Objects, References, and Representations 10 Links and Link Relations 10 Client Workflow Overview 14 About the Schema Reference 17 2 Setting Up for PHP Development 19 Download the vCloud SDK for PHP Package 19 Using the HTML Reference Material 20 3 Working with the vCloud SDK for PHP 21 Summary of SDK Objects, Containers, and Methods 22 Create an SDK Object 24 Create a Data Object 25 Create a Root Object
vCloud SDK for PHP Developer's Guide 4 VMware, Inc.
vCloud SDK for PHP Developer's Guide The vCloud SDK for PHP Developer's Guide provides information about the PHP SDK for version 5.1 of the vCloud API. VMware provides APIs and SDKs for various applications and goals. This guide provides information about the vCloud API for developers who are interested in creating RESTful clients of VMware vCloud Director. Revision History The vCloud SDK for PHP Developer's Guide is revised with each release of the product or when necessary.
vCloud SDK for PHP Developer's Guide 6 VMware, Inc.
About the VMware vCloud API 1 The VMware vCloud API provides support for developers who are building interactive clients of VMware vCloud Director using a RESTful application development style. vCloud API clients and vCloud Director servers communicate over HTTP, exchanging representations of vCloud objects. These representations take the form of XML elements.
vCloud SDK for PHP Developer's Guide Object Taxonomy The vCloud API defines a set of objects common to cloud computing environments. An understanding of these objects, their properties, and their relationships is essential to using the vCloud API. Figure 1-1.
Chapter 1 About the VMware vCloud API Organization vDCs An organization virtual datacenter (organization vDC) is a deployment environment for virtual systems owned by the containing organization, and an allocation mechanism for resources such as networks, storage, CPU, and memory. In an organization vDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two.
vCloud SDK for PHP Developer's Guide Objects, References, and Representations The vCloud API represents objects as XML documents in which object properties are encoded as elements and attributes with typed values and an explicit object hierarchy defined by an XML schema. XML representations of first-class vCloud API objects, such as the objects in Figure 1-1, include these attributes. id The object identifier, expressed in URN format.
Chapter 1 About the VMware vCloud API Attribute values in a Link element supply the following information: rel Defines the relationship of the link to the object that contains it. A relationship can be the name of an operation on the object, a reference to a contained or containing object, or a reference to an alternate representation of the object. The relationship value implies the HTTP verb to use when you use the link's href value as a request URL.
vCloud SDK for PHP Developer's Guide Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb down:aclRules Retrieve the ACL rules for this resource class action. GET down:apidefinitions Retrieve the API definitions for this extension service. GET down:apiDefinitions Retrieve the API definitions for this extension service. GET down:apiFilters Retrieve the API filters for this extension service.
Chapter 1 About the VMware vCloud API Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb installVmwareTools Install VMware Tools on this virtual machine. POST keystore:reset Removes the keystore used by this service. POST keystore:update Updates the keystore used by this service. POST keytab:reset Removes the keytab used by this service. POST keytab:update Updates the keytab used by this service.
vCloud SDK for PHP Developer's Guide Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb rights:cleanup Remove service-specific rights no longer used by any extension service. POST screen:acquireTicket Retrieve a screen ticket for this virtual machine. GET screen:thumbnail Retrieve a thumbnail view of the screen of this virtual machine.
Chapter 1 About the VMware vCloud API If a URL of such an object is known to a client, the client can use an HTTP GET request to retrieve the representation of the object. In the vCloud API, this representation is an XML document. In a RESTful workflow, representations of object state are passed back and forth between a client and a service with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response.
vCloud SDK for PHP Developer's Guide vCloud API REST Requests To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests. Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the of vCloud API that the server supports.
Chapter 1 About the VMware vCloud API Table 1-3. HTTP Status Codes that the vCloud API Returns (Continued) Status Code Status Description 400 Bad Request The request body is malformed, incomplete, or otherwise invalid. 401 Unauthorized An authorization header was expected but not found. 403 Forbidden The requesting user does not have adequate privileges to access one or more objects specified in the request.
vCloud SDK for PHP Developer's Guide 18 VMware, Inc.
Setting Up for PHP Development 2 To use the vCloud SDK for PHP, you need PHP 5.3.2 or later and the PEAR HTTP_Request2 package or a similar HTTP client for PHP. Prerequisites for Using the vCloud SDK for PHP To use the vCloud SDK for PHP, you should be familiar with the PHP programming language and have access to an installation of VMware vCloud Director.
vCloud SDK for PHP Developer's Guide 5 6 On the Download page, choose a download option and click the file format to download. Option Description vcloudPHP_5.1.0.build.tar.gz A compressed archive in tar format, where build is a build number. vcloudPHP_5.1.0.build.zip A compressed archive in zip format. When the download is complete, uncompress the download package into any convenient folder on your computer. The package includes the following folders: docs Reference documentation in HTML format.
Working with the vCloud SDK for PHP 3 The vCloud SDK for PHP provides a PHP class library and a set of example applications. The classes and functions in the library encapsulate the interfaces, objects, and operations that the vCloud API supports, while preserving its RESTful approach and compatibility with the HTTP protocol family.
vCloud SDK for PHP Developer's Guide Table 3-2. VMware_VCloud_SDK Packages Package Name Package Contents VMware_VCloud_SDK Classes that implement operations defined in the vCloud user API and administrative API VMware_VCloud_SDK_Extension Classes that implement operations defined in the vCloud API vSphere Platform Extensions VMware_VCloud_SDK_HTTP Classes that support HTTP client operations.
Chapter 3 Working with the vCloud SDK for PHP Table 3-3.
vCloud SDK for PHP Developer's Guide Table 3-3.
Chapter 3 Working with the vCloud SDK for PHP Create a Data Object To create a data object, you can either invoke an empty constructor and then call the setters for the object or invoke the constructor with parameters. Each data object class includes a constructor method whose parameters represent attributes of the class and all of its ancestors. Attributes are marked as protected to restrict their visibility. All classes contain setter and getter methods for XML elements and attributes.
vCloud SDK for PHP Developer's Guide 2 Call the VMware_VCloud_SDK_Service::getService() method that specifies the client that you created. For example, $service = VMware_VCloud_SDK_Service::getService($myHTTPClient); . 26 VMware, Inc.
4 About the Example Programs The vCloud SDK for PHP includes example programs that demonstrate how to use the SDK to develop client applications. The examples are in the samples folder of the SDK downloadable files. Comments in the examples provide detailed information about how they use the features of the vCloud SDK for PHP. Required Permissions Some of the example programs require system administrator privileges to run. Others can be run by any user who can create and operate a vApp. Table 4-1.
vCloud SDK for PHP Developer's Guide Table 4-1. Summary of Example Programs and Required Permissions (Continued) Example Name Description Required Permissions createprovidervdc.php Creates a provider vDC from vSphere resources. System Administrator. importvm.php Imports a virtual machine from vCenter to create a vApp in the specified vDC. System Administrator. host.php Prepares an ESX/ESXi host for use with vCloud Director. System Administrator. vimserver.
Chapter 4 About the Example Programs 2 Run php hellovcloud.php, as show in “Example: Running HellovCloud,” on page 29. Example: Running HellovCloud You must supply runtime options on the command line. To see a summary of hellovcloud.php options, use the following command: php hellovcloud.php --help To run the hellovcloud.php example, use the following command: php hellovcloud.
vCloud SDK for PHP Developer's Guide Logging In and Getting an Organization List Most vCloud API requests must be authenticated by a login request that supplies user credentials in the form that Basic HTTP authentication requires. This form is MIME Base64 encoding of a string having the form user@vcloud-organization:password. The VMware_VCloud_SDK_Service class implements a login method that takes the following parameters: userName Supplied in the form user@vcloud-organization.
Chapter 4 About the Example Programs Procedure 1 (Optional) Edit the config.php file to provide common parameter values. When you run any example program, you can override its use of these values by supplying them on the command line. 2 Run the example in a shell window using a command of the following form, where example is the name of the example program: php example.php When you run an example program with no parameters, it displays a usage message and exits. VMware, Inc.
vCloud SDK for PHP Developer's Guide 32 VMware, Inc.
Index C containers, SDK 22 SDK, to download 19 SDK object, to create 24 D V data object, to create 25 vCloud API, and RESTful programming style 7 E W Entity, object representation in 10 example programs Hello vCloud 28 to run 30 using 27 workflow 14 X XML compressed responses 16 validation of 16 H HellovCloud, about 29 HTTP library 25 I id attribute 10 L Link element, rel attribute 10 M methods, SDK 22 O object hierarchy, diagram of 8 object identifiers 10 object references, about 10 objects
vCloud SDK for PHP Developer's Guide 34 VMware, Inc.
