vCenter Chargeback API Programming Guide vCenter Chargeback 1.5 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.
vCenter Chargeback API 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 © 2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents About This Book 5 1 vCenter Chargeback APIs 7 What Is vCenter Chargeback? 7 REST Architecture 7 Requests 8 Responses 8 Common Elements in the Request and Response XMLs 9 Chargeback API Syntax 9 API Versioning 10 2 Understanding the Workflow 11 Requirements for Code Examples 11 JAR Files 11 CommonUtil Class 12 FakeSSLCertificateSocketFactory Class 13 Log In to vCenter Chargeback Server 14 Add vCenter Server Information 15 Add a Custom Chargeback Hierarchy 16 Add a vCenter Server Entity to the C
vCenter Chargeback API Programming Guide 4 VMware, Inc.
About This Book The vCenter Chargeback API Programming Guide provides information on how to use vCenter Chargeback APIs. Intended Audience This book is intended for anyone who develop applications to work with vCenter Chargeback. 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.
vCenter Chargeback API Programming Guide VMware Professional Services VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides offerings to help you assess, plan, build, and manage your virtual environment.
1 vCenter Chargeback APIs 1 This chapter includes the following topics: “What Is vCenter Chargeback?” on page 7 “REST Architecture” on page 7 “Chargeback API Syntax” on page 9 “API Versioning” on page 10 What Is vCenter Chargeback? vCenter Chargeback is a cost reporting solution for environments virtualized using vSphere.
vCenter Chargeback API Programming Guide Figure 1-1. REST Architecture in vCenter Chargeback Requests An HTTP request sent by a Chargeback API can be of the following type: PUT, POST, GET, or DELETE. Table 1‐1 shows how each of these request types maps to a standard CRUD operation. Table 1-1. Request Type Mapping Request Type CRUD Operation POST CREATE GET READ PUT UPDATE/CREATE DELETE DELETE Along with the HTTP requests, you can pass request parameters by using XMLs.
Chapter 1 vCenter Chargeback APIs If an API task is unsuccessful, the status parameter is set to failure and the Error element captures all the details. PAGE 10vCenter Chargeback API Programming Guide If you want to use vCenter Chargeback 1.0.1 APIs, you need to do the following tasks: In the API URL, specify version=1.0.1. For example, /?version=1.0.1 In the request XML, update the request element with the following tag: API Versioning Every vCenter Chargeback 1.5.0 API request and response includes target namespace to denote the API version.
2 Understanding the Workflow 2 This chapter explains how to perform some of the basic vCenter Chargeback tasks using the APIs. You can create a hierarchy and add entities, add fixed cost and generate a report on resource utilization.
vCenter Chargeback API Programming Guide CommonUtil Class The code examples use the following CommonUtil class. public final class CommonUtil { /** * This method writes out a formatted XML document to the Writer out. * * @param doc * @param out * @throws IOException */ public static void printXML(Document doc, Writer out) throws IOException { XMLOutputter o = new XMLOutputter(); Format newFormat = o.getFormat(); newFormat.setIndent(" "); o.setFormat(newFormat); o.
Chapter 2 Understanding the Workflow FakeSSLCertificateSocketFactory Class The code examples use the following class to access resources over the HTTPS protocol. /** * Helper class to accept self-signed certificate. */ public class FakeSSLCertificateSocketFactory implements SecureProtocolSocketFactory { private SSLContext sslContext; public FakeSSLCertificateSocketFactory() throws NoSuchAlgorithmException, KeyManagementException { sslContext = SSLContext.getInstance("SSL"); sslContext.
vCenter Chargeback API Programming Guide Log In to vCenter Chargeback Server To start using vCenter Chargeback APIs, you must log in to vCenter Chargeback server. To log in to vCenter Chargeback 1 Call the Login API by using the following syntax. /login For example, you can define a call as follows: POST https://123.123.123.123/vCenter-CB/api/login 2 (Optional) Use the URL parameter version to specify the API version that you want to call.
Chapter 2 Understanding the Workflow Protocol.registerProtocol("https", new Protocol("https", (ProtocolSocketFactory) new FakeSSLCertificateSocketFactory(), 443)); String uri = "https://" + baseURL + "/vCenter-CB/api/login"; System.out.println(uri); try { post = new PostMethod(uri); post.setQueryString(parameters); post.setRequestBody(bodyString); client.executeMethod(post); System.out.println(post.getResponseBodyAsString()); } finally { if (post != null) { post.
vCenter Chargeback API Programming Guide vim_vcdb sa xxxx false If the vCenter Server is successfully added, the API returns an XML response that provides the vCenter Server ID. The following is an example program that calls the API.
Chapter 2 Understanding the Workflow The following is an example request XML. Test_Hierarchy Test Hierarchy If successful, the API returns details of the new hierarchy. The following is an example program that calls the API.
vCenter Chargeback API Programming Guide The following is an example request XML. If successful, the API returns an XML file that indicates the status. The following is an example program that calls the API.
Chapter 2 Understanding the Workflow Add a Fixed Cost A fixed cost is a definite cost that can be charged on an entity. Using the Add Fixed Cost API, you can create fixed costs for entities. To add a fixed cost 1 Call the API using the following syntax. /fixedCost For example, you can define a call like this: POST https://123.123.123.123/vCenter-CB/api/fixedCost 2 In the request XML, specify a name and a description for the fixed cost.
vCenter Chargeback API Programming Guide Modify a Fixed Cost Value Using the Modify Fixed Cost API, you can update the ID, value, and duration for a fixed cost. To modify a fixed cost value 1 Call the API by using the following syntax. /fixedCost/{fixedCostId}/values For example, you can define a call like this: PUT https://123.123.123.123/vCenter-CB/api/fixedCost/{fixedCostId}/values 2 In the request XML, specify a name and a description for the fixed cost.
Chapter 2 Understanding the Workflow } finally { if (put != null) { put.releaseConnection(); } } } Generate a Report Use the Generate Report API to send a request to create a report. To generate a report 1 Call the API by using the following syntax. /report For example, you can define a call like this: POST https://123.123.123.123/vCenter-CB/api/report 2 In the request XML, specify the following details about the hierarchy, entity, resource counters, and the cost model.
vCenter Chargeback API Programming Guide vCenter Chargeback queues this report request as a task and returns an XML that indicates the status of the task. You can use the Get Queued Task Status API to track the progress of the task.
3 Using vCenter Chargeback with a Billing System 3 This chapter explains some of the tasks that you can perform by using vCenter Chargeback APIs in an environment where vCenter Chargeback is integrated with a third party billing system. You can use vCenter Chargeback to perform cost measurement and generate resource utilization reports, which are provided to the billing system to charge customers.
vCenter Chargeback API Programming Guide CommonUtil Class The code examples use the following CommonUtil class. public final class CommonUtil { /** * This method writes out a formatted XML document to the Writer out. * * @param doc * @param out * @throws IOException */ public static void printXML(Document doc, Writer out) throws IOException { XMLOutputter o = new XMLOutputter(); Format newFormat = o.getFormat(); newFormat.setIndent(" "); o.setFormat(newFormat); o.
Chapter 3 Using vCenter Chargeback with a Billing System FakeSSLCertificateSocketFactory Class The code examples use the following class to access resources over the HTTPS protocol. /** * Helper class to accept self-signed certificate. */ public class FakeSSLCertificateSocketFactory implements SecureProtocolSocketFactory { private SSLContext sslContext; public FakeSSLCertificateSocketFactory() throws NoSuchAlgorithmException, KeyManagementException { sslContext = SSLContext.getInstance("SSL"); sslContext.
vCenter Chargeback API Programming Guide Add Cost Models You can add multiple cost models in vCenter Chargeback. Defining multiple cost models enables you to charge different sets of entities or hierarchies differently. It also enables you to compare the costs calculated using different cost models for a hierarchy or a set of entities. To add a cost model 1 Call the Add Cost Model API by specifying the following URL in your program.
Chapter 3 Using vCenter Chargeback with a Billing System try { post = new PostMethod(uri); post.setRequestBody(bodyString); client.executeMethod(post); System.out.println(post.getResponseBodyAsString()); } finally { if (post != null) { post.releaseConnection(); } } } Add a Billing Policy You can define custom billing policies as per your requirements. A billing policy defines an expression that is used for identifying the computing resources units to be considered for calculating the costs.
vCenter Chargeback API Programming Guide Protocol.registerProtocol("https", new Protocol("https", (ProtocolSocketFactory) new FakeSSLCertificateSocketFactory(), 443)); String uri = "https://" + baseURL + "/vCenter-CB/api/billingPolicy"; try { post = new PostMethod(uri); post.setRequestBody(bodyString); client.executeMethod(post); System.out.println(post.getResponseBodyAsString()); } finally { if (post != null) { post.
Chapter 3 Using vCenter Chargeback with a Billing System The following is an example program that calls the API. This program assumes that the request XML is populated with the required information.
vCenter Chargeback API Programming Guide Protocol.registerProtocol("https", new Protocol("https", (ProtocolSocketFactory) new FakeSSLCertificateSocketFactory(), 443)); String uri = "https://" + baseURL + "/vCenter-CB/api/hierarchy/" + hierarchyId; try { get = new GetMethod(uri); client.executeMethod(get); System.out.println(get.getResponseBodyAsString()); } finally { if (get != null) { get.
Chapter 3 Using vCenter Chargeback with a Billing System
