API Programming Guide vCenter Chargeback Manager 2.0.0 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.
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-2011 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 Manager APIs 7 What Is vCenter Chargeback Manager? 7 REST Architecture 7 Requests 8 Responses 8 Common Elements in the Request and Response XMLs 9 vCenter Chargeback Manager API Syntax 9 API Versioning 10 2 Understanding the Workflow 13 Requirements for Code Examples 13 JAR Files 13 CommonUtil Class 14 FakeSSLCertificateSocketFactory Class 15 Log In to vCenter Chargeback Manager 16 Add vCenter Server Information 17 Add a Custom Chargeback Hierarchy 18 Add
API Programming Guide 4 VMware, Inc.
About This Book The API Programming Guide provides information on how to use vCenter Chargeback Manager APIs. Intended Audience This book is intended for anyone who develop applications to work with vCenter Chargeback Manager. 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.
API Programming Guide Support Offerings To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services. 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.
1 vCenter Chargeback Manager APIs 1 This chapter includes the following topics: “What Is vCenter Chargeback Manager?” on page 7 “REST Architecture” on page 7 “vCenter Chargeback Manager API Syntax” on page 9 “API Versioning” on page 10 What Is vCenter Chargeback Manager? vCenter Chargeback Manager is a cost reporting solution for environments virtualized using vSphere.
API Programming Guide Figure 1-1.
Chapter 1 vCenter Chargeback Manager APIs If an API task is unsuccessful, the status parameter is set to failure and the Error element captures all the details. PAGE 10API Programming Guide Table 1-4. API Syntax Components Syntax Component Description API_signature The URL path for a vCenter Chargeback Manager API. For example, /hierarchies retrieves the hierarchies added to the vCenter Chargeback Manager running on 123.123.123.123. version (Optional) API version. If you want to use vCenter Chargeback Manager 1.5 API, then specify the version as 1.5.0. If you do not specify the version, the current API version, which is 2.0, is considered.
Chapter 1 vCenter Chargeback Manager APIs If you specify the API version, be sure to specify it with both the request XML (wherever applicable) and the URL. If it is specified only in the request XML or the URL and not both, then the API results in an error. If the API version is absent in both the URL and the request XML (wherever applicable), then the API returns the output corresponding to the latest version. VMware, Inc.
API Programming Guide 12 VMware, Inc.
2 Understanding the Workflow 2 This chapter explains how to perform some of the basic vCenter Chargeback Manager tasks using the APIs. You can create a hierarchy and add entities, add fixed cost and generate a report on resource utilization.
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.
API Programming Guide Log In to vCenter Chargeback Manager To start using vCenter Chargeback Manager APIs, you must log in to vCenter Chargeback Manager. To log in to vCenter Chargeback Manager 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?version=2.0 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?version=2.0"; 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.
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.
API Programming Guide The following is an example request XML. If successful, the API returns an XML file that indicates the status.
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.
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.
API Programming Guide vCenter Chargeback Manager 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. For more information on the Get Queued Task Status API, see the vCenter Chargeback Manager API Reference.
3 Using vCenter Chargeback Manager with a Billing System 3 This chapter explains some of the tasks that you can perform by using vCenter Chargeback Manager APIs in an environment where vCenter Chargeback Manager is integrated with a third party billing system. You can use vCenter Chargeback Manager to perform cost measurement and generate resource utilization reports, which are provided to the billing system to charge customers.
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 Manager 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.
API Programming Guide Add Cost Models You can add multiple cost models in vCenter Chargeback Manager. 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 Manager 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.
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 Manager 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.
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.releaseConnection(); } } } Add Report Schedule for Hierarchy You can schedule reports to be generated at regular intervals.
Chapter 3 Using vCenter Chargeback Manager with a Billing System 13 59 2 1321295400000 -1 <
API Programming Guide To get schedule by hierarchy name 1 Call the Search API by using the following URL in your program. POST /search 2 3 In the request XML, specify the following parameters to search schedules. You can use any of these parameters alone or in combination with the others. name desc hierarchyName costModelName You can use search operators such as EQUAL, NOT_EQUAL, BETWEEN, GT, LT, GT_EQUAL, LT_EQUAL, NULL, NOT_NULL, LIKE, NOT_LIKE to filter your search.
Chapter 3 Using vCenter Chargeback Manager with a Billing System System.out.println(post.getResponseBodyAsString()); } finally { if (post != null) { post.releaseConnection(); } } } Reschedule a Report You can update a report schedule using the Reschedule Report API. The Reschedule Report API updates the schedule information. If you want to update the entity to cost model mapping, you must delete the schedule and create a new schedule.
API Programming Guide public static void sampleRescheduleReport(String requestFilePath, String baseURL, int scheduleId) throws HttpException, IOException, KeyManagementException, NoSuchAlgorithmException, JDOMException { PutMethod put = null; Document requestDocument = CommonUtil.getXMLDocument(requestFilePath); String bodyString = CommonUtil.xmlAsString(requestDocument); HttpClient client = new HttpClient(); Protocol.
Chapter 3 Using vCenter Chargeback Manager with a Billing System } } } Get List of Archived Reports for a Hierarchy For a specific hierarchy, you can get a list of archived reports that were generated after a specific time. To do this, you can use the Search API. To get list of archived reports for a hierarchy 1 Call the Search API by using the following URL in your program.
API Programming Guide HttpClient client = new HttpClient(); Protocol.registerProtocol("https", new Protocol("https", (ProtocolSocketFactory) new FakeSSLCertificateSocketFactory(), 443)); String uri = "https://" + baseURL + "/vCenter-CB/api/search"; try { post = new PostMethod(uri); post.setRequestBody(bodyString); client.executeMethod(post); System.out.println(post.getResponseBodyAsString()); } finally { if (post != null) { post.
Index A about, vCenter Chargeback Manager APIs 7 add billing policy 29 cost model 28 entity 19 fixed cost 21 hierarchy 18 report schedule 32 vCenter Server 17 add vCenter Server example program 18 request XML 17 add vCenter Server API add vCenter Server 17 Apache Tomcat 7 API add billing policy 29 add vCenter Server entity 19 login 16 request 8 response 8 syntax 9 versioning 10 API syntax 17 components 9 API versioning, about 10 example 10 APIs export report 38 get hierarchy 31 Reschedule Report 35 Search
API Programming Guide get details hierarchy 31 H helper class for examples 13, 25 hierarchy add 18 get details 31 J JAR files for examples 13, 25 L list of hierarchies get 30 log in request XML 16 log in API example program 16 login 13 API 16 M modify value of fixed cost 22 R report generate 23 in XML 38 reschedule 35 XML format 38 report schedule add 32 delete 36 example program 33 for hierarchy 33 request XML 32 40 request API 8 request XML add vCenter Server 17 archived reports 37 log in 16 login
