42
vCloud Air Platform Programmer's Guide vCloud Air OnDemand 5.7 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. EN-001712-00

vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

  • Upload
    others

  • View
    22

  • Download
    0

Embed Size (px)

Citation preview

Page 1: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

vCloud Air Platform Programmer'sGuide

vCloud Air OnDemand 5.7

This document supports the version of each product listed andsupports all subsequent versions until the document isreplaced by a new edition. To check for more recent editionsof this document, see http://www.vmware.com/support/pubs.

EN-001712-00

Page 2: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

vCloud Air Platform Programmer's Guide

2 VMware, Inc.

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:

[email protected]

Copyright © 2016 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

Page 3: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Contents

About This Programmer's Guide 5

1 About the vCloud Air Platform APIs 7

The VMware APIs for Virtual Private Cloud OnDemand 8Service-Oriented Architecture Explained 8About Plans, Instances, and the Compute Service 9Media Support - JSON and XML 11API Versioning 12Authentication and Authorization 12Roles for the APIs for Cloud Automation 13Error Codes and Error Handling 13Filter Expressions 15vCloud Air Platform APIs Schema Reference 15About the Examples in This Programmer's Guide 16

2 Hello vCloud Air: A Simplified RESTful Workflow 17

Log In and Receive Access Token 18List Available Plans and Instances 19

3 Managing Users 23

About User Management 23List Users 25Add a User 28Update a User 30Delete a User 33Retrieve Forgotten Password 34

4 Metering and Billing for Resource Usage 37

About Resource Usage Metering and Billing 37Workflow for Using the Metering GET Operations 38Summary of Metering and Billing Requests 39

Index 41

VMware, Inc. 3

Page 4: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

vCloud Air Platform Programmer's Guide

4 VMware, Inc.

Page 5: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

About This Programmer's Guide

The vCloud Air Platform Programmer's Guide provides information about APIs for vCloud AirVirtual Private Cloud OnDemand (formerly known as the vCloud Air API Extensions).

VMware provides many different APIs and SDKs for applications and goals. This guide providesinformation about vCloud Air Platform APIs for developers who create RESTful clients for vCloud AirVirtual Private Cloud OnDemand.

Intended AudienceThis guide is intended for software developers who are building interactive clients of vCloud AirVirtual Private Cloud OnDemand. This guide discusses Representational State Transfer (REST) and RESTfulprogramming conventions, and vCloud Air technology. You must be familiar with these and other widelydeployed technologies such as XML, HTTP, and the Windows or Linux operating system.

Related DocumentationThe vCloud Air – Virtual Private Cloud OnDemand User's Guide and the vCloud Air Compute ServiceProgramming Guide (API Version 9.0) contain detailed information about many of the objects andoperations referred to in this guide.

VMware Technical Publications GlossaryVMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitionsof terms as they are used in VMware technical documentation, go to http://www.vmware.com/support/pubs.

VMware, Inc. 5

Page 6: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

vCloud Air Platform Programmer's Guide

6 VMware, Inc.

Page 7: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

About the vCloud Air Platform APIs 1The vCloud Air Platform APIs provide programmatic access to vCloud AirVirtual Private Cloud OnDemand.

Virtual Private Cloud OnDemand is an infrastructure-as-a-service (IaaS) platform that allows customers toconsume specific compute, storage, and networking resources as incremental pay-as-you-go services.Virtual Private Cloud OnDemand leverages a resource pool-based delivery model. Customers pay for onlythe resources they actually used, on a metered, charge-back basis, under flexible service agreements, asopposed to fixed-term contracts. Customers can increase or decrease capacity based on demands andbudget.

Customers consume Virtual Private Cloud OnDemand like any software-defined data center. BecauseVirtual Private Cloud OnDemand is built on the vSphere and vCloud platforms, customers consume it thesame way that they consume their existing on-premises vSphere environments.

For more information about the features of vCloud Air – Virtual Private Cloud OnDemand, see IntroducingVirtual Private Cloud OnDemand in the vCloud Air – Virtual Private Cloud OnDemand User's Guide.

This chapter includes the following topics:

n “The VMware APIs for Virtual Private Cloud OnDemand,” on page 8

n “Service-Oriented Architecture Explained,” on page 8

n “About Plans, Instances, and the Compute Service,” on page 9

n “Media Support - JSON and XML,” on page 11

n “API Versioning,” on page 12

n “Authentication and Authorization,” on page 12

n “Roles for the APIs for Cloud Automation,” on page 13

n “Error Codes and Error Handling,” on page 13

n “Filter Expressions,” on page 15

n “vCloud Air Platform APIs Schema Reference,” on page 15

n “About the Examples in This Programmer's Guide,” on page 16

VMware, Inc. 7

Page 8: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

The VMware APIs for Virtual Private Cloud OnDemandThe vCloud Air Platform APIs provides support for developers who are building interactive clients ofvCloud Air using a RESTful application development style.

vCloud Air clients and vCloud Air servers communicate over HTTP, exchanging representations ofvCloud Air objects. These representations take the form of XML elements. vCloud Air clients make HTTPrequests to the server and retrieve the information the clients need from the server's responses.

Customers manage and consume Virtual Private Cloud OnDemand resources by using public APIs. Thepublic APIs provide management of cloud resources including virtual data center management,configuration of network services, and virtual machine instance lifecycle management, as well as access toresource usage metrics.

Complete programmatic access to the VMware APIs for Virtual Private Cloud OnDemand is accomplishedby utilizing the following VMware APIs:

n vCloud Air Platform APIs, version 5.7: Build client applications that discover and access vCloud Airservices (such as Virtual Private Cloud OnDemand), manage users forVirtual Private Cloud OnDemand, and automate resource usage metering and billing.

In addition to this guide, see the vCloud Air Platform APIs Schema Reference , 5.7.

n vCloud Air Compute Service APIs: Build client applications that access the API endpoint for thevCloud Compute Service, which exposes compute (vRAM and vCPU resources for virtual machines),storage, and networking functionality in the public cloud on a pay-as-you-go basis.

For information, see the following documentation:

n vCloud Air Compute Service Programming Guide (API Version 9.0)

n vCloud API 9.0 Schema Reference

Service-Oriented Architecture ExplainedThe vCloud Air Platform APIs are designed to work with the service-oriented architecture on whichVirtual Private Cloud OnDemand is built.

Understanding the service-oriented architecture is essential to creating API clients to automate operations.

The extensibility of the service-oriented architecture supports the discovery and consumption of servicesthrough public APIs, allowing for a common framework, and loosely-coupled services based on a commonmessage bus.

Figure 1‑1. Components of the Service-Oriented Architecture

Schema Docs

NetworkComputeMeteringIdentity Management

Service Controller

REST API

vCloud Air

vCloud Air Platform Programmer's Guide

8 VMware, Inc.

Page 9: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Table 1‑1. API Surfaces for Virtual Private Cloud OnDemand

Component Capabilities API URI

IdentifyManagement

n Authentication and single sign on betweenservices

n User identity lifecycle managementn Authorization, such as access controlFor information about the APIs for authentication andauthorization, see Chapter 2, “Hello vCloud Air: ASimplified RESTful Workflow,” on page 17.For information about the APIs for user management,see Chapter 3, “Managing Users,” on page 23.

/api/iam/login

/api/iam/Users

Service Controller n vCloud Air plan and instance management,including the instance lifecycle

n Exposure of the service-oriented architecture thatis available for consumption

n Discovery of plans and instances by customersn Registry for information related to plans and

instancesFor information about the APIs for the ServiceController, see Chapter 2, “Hello vCloud Air: ASimplified RESTful Workflow,” on page 17.

/api/sc/plans

/api/sc/instances

Metering Service Metering data collection and aggregation with aninterface to your My VMware account for billing dataFor information about the APIs for the MeteringService, see Chapter 4, “Metering and Billing forResource Usage,” on page 37.

/api/metering

/api/billing

Compute Service Exposure of compute (vRAM and vCPU resources forvirtual machines), storage, and networkingfunctionality in the public cloud on a pay-as-you-gobasisFor information about the APIs for the vCloudCompute Service, see vCloud Air Compute ServiceProgramming Guide (API Version 9.0).

/api/compute

For the list of API surfaces forprovisioning within the vCloudCompute Service, see Summary ofvCloud API Provisioning Requests in thevCloud Air Compute Service ProgrammingGuide (API Version 9.0).

Networking Service The pay-as-you-go network services—gateways,networks, vApp/VM networks, firewall and NATrulesFor information about the APIs for the NetworkingService, see Network Administration in the vCloud AirCompute Service Programming Guide.NOTE External networks and network pools aresystem resources managed by vCloud Airadministrators with VMware or your authorizedservice provider.

/api/admin/edgeGateway

/api/admin/vdc/id/networks

About Plans, Instances, and the Compute ServiceTo work with the service-oriented architecture on which Virtual Private Cloud OnDemand is built, youneed to understand the following resources and how they interact.

n Plans

Chapter 1 About the vCloud Air Platform APIs

VMware, Inc. 9

Page 10: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

A plan abstracts the infrastructure and platform functionality for Virtual Private Cloud OnDemand.You can think of a plan as a template because it defines how you consume resources provided in theVMware public cloud. For example, the plan for Virtual Private Cloud OnDemand allows customers tocreate virtual machines configured with 2.6GHz vCPUs. Other plans for vCloud Air might allowcustomers to create virtual machines configured with a different vCPU speed.

NOTE Each location can have different plans provisioned; if multiple locations are offering the sameplan, the plans in each location have the same plan name.

For information about how Virtual Private Cloud OnDemand is available in different locations, see Geographical Locations in the vCloud Air – Virtual Private Cloud OnDemand User's Guide.

n Instances

An instance is a consumable instance of a given plan. After account creation, you initialize an instancein a chosen location.

n Compute Service

A user in vCloud Air can access the vCloud API through the vCloud Compute Service. The vCloudCompute Service is the service that exposes the compute, networking, and storage functionality that isavailable to customers of Virtual Private Cloud OnDemand.

For information about the APIs to develop client applications that access the API endpoint for thevCloud Compute Service, see the vCloud Air Compute Service Programming Guide (API Version 9.0).

A plan, which is a complex type, has the following structure:

<xs:element name="Plan" type="service:PlanType"/>

<xs:complexType name="PlanType">

<xs:complexContent>

<xs:extension base="common:ResourceType">

<xs:sequence>

<xs:element name="region" type="common:NonEmptyString"/>

<xs:element name="description" type="common:NonEmptyString" minOccurs="0"/>

<xs:element name="planVersion" type="common:NonEmptyString"/>

<xs:element name="planAttributes" type="common:NonEmptyString" minOccurs="0"/>

<xs:element name="instanceSpec" type="common:NonEmptyString" minOccurs="0"/>

<xs:element name="planPolicy" type="service:PlanPolicyType" minOccurs="0"/>

</xs:sequence>

</xs:extension>

</xs:complexContent>

</xs:complexType>

<xs:element name="PlanList" type="service:PlanListType"/>

<xs:complexType name="PlanListType">

<xs:sequence>

<xs:element name="plans" type="service:PlanType" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

An instance has the following (complex type) structure:

<xs:element name="Instance" type="instance:InstanceType"/>

<xs:complexType name="InstanceType">

<xs:complexContent>

<xs:extension base="common:ResourceType">

<xs:sequence>

<xs:element name="description" type="common:NonEmptyString" minOccurs="0"/>

<xs:element name="region" type="common:NonEmptyString"/>

<xs:element name="serviceName" type="common:NonEmptyString"/>

vCloud Air Platform Programmer's Guide

10 VMware, Inc.

Page 11: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

<xs:element name="instanceVersion" type="common:NonEmptyString" minOccurs="0"/>

<xs:element name="planId" type="common:NonEmptyString"/>

<xs:element name="serviceGroupId" type="common:NonEmptyString"/>

<xs:element name="apiUrl" type="xs:anyURI"/>

<xs:element name="dashboardUrl" type="xs:anyURI"/>

<xs:element name="instanceAttributes" type="common:NonEmptyString" minOccurs="0"/>

</xs:sequence>

</xs:extension>

</xs:complexContent>

</xs:complexType>

The instance, as shown in the example, has the following attributes:

n serviceName: The name of the service offering for the plan

The serviceName attribute can be used to distinguish whether a plan or instance belongs to the ComputeService or another vCloud Air service.

n planId: The plan associated with the creation of an instance

n serviceGroupId: Service group ID associated with the creation of the instance

When you sign up for Virtual Private Cloud OnDemand, VMware creates your account and assigns aservice group ID to your account. VMware uses your service group ID as part of its billing system. Theservice group ID indicates which billing account to charge for resource usage.

n The attributes instanceAttributes and apiURL are optional; the client should not assume they arepresent.

Each instance created for Virtual Private Cloud OnDemand contains one vCloud Compute Service. ThevCloud Compute Service exposes compute (vRAM and vCPU resources for virtual machines), storage, andnetworking functionality in the public cloud on a pay-as-you-go basis.

Media Support - JSON and XMLThe vCloud Air Platform APIs support XML and JSON data input and output formats. Whether you specifyJSON or XML in a request, the data structure returned in the response is equivalent for both formats; theonly difference is the data encoding differs by format.

Request HeadersIn HTTP requests, API clients must specify in the Content-Type header the format in which data issubmitted:

Content-Type: application/xml

Content-Type: application/json

For HTTP responses, specifying the media type and subtype is optional.

For HTTP responses, the vCloud Air Platform APIs support specifying in the Accept header the followingmedia types and subtypes:

Accept: application/xml

Accept: application/json

Accept: application/*

Accept: */*

When you do not specify a media type or subtype or you specify wildcards in an Accept header, thevCloud Air Platform APIs provide the HTTP response by using application/xml. To receive a responseusing JSON, you must explicitly specify application/json in the Accept header.

Chapter 1 About the vCloud Air Platform APIs

VMware, Inc. 11

Page 12: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Table 1‑2. Media Type and Subtype Support

Type Media Range

Application media type and JSON subtype Accept:application/json;class=mediatype

Application media type and XML subtype Accept:application/xml;class=mediatype

Wildcard media type and subtype n Accept:application/*;class=mediatypen Accept: */*;class=mediatype

n Media type defaults to “application”n Subtype defaults “xml”

NOTE Specifying the media class for a resource is optionaland does not include versioning information.

API VersioningThe vCloud Air Platform APIs follow an API version scheme to ensure standardization throughout the APIsurface and to provide backward compatibility with future releases.

To specify the API version for content negotiation, include the vCloud Air Platform APIs version in theAccept header as an extension parameter (;version=5.7).

The API versions the entire information model except for the media classes. (The media class for a resourceis optional and does not include versioning information.)

NOTE n If you specify version=* in the Accept header, the API uses the latest API version.

n When omitting the version from the Accept header, the API performs the operations by using the mostrecent API version supported for the vCloud Air Platform APIs.

In HTTP responses, the API returns the version in the Content-Type header as an extension parameter.

Authentication and AuthorizationHTTP communications between vCloud Air clients and servers are secured with SSL. In addition to SSLencryption, vCloud Air implements authentication and authorization for secure API access.

Authentication with vCloud AirvCloud Air implements Basic HTTP authentication, as defined by RFC 2617, which enables a client toauthenticate by including an Authorization header in the request. The Authorization header sends a username and password as basic credentials in MIME Base64 encoding:

Authorization: Basic [email protected]:password

The vCloud Air Identity Management Service authenticates the user credentials forVirtual Private Cloud OnDemand and returns an OAuth 2.0 Access token that is signed and formatted usingBase64 encoded JSON.

Response:

201 Created

vchs-authorization:vchs-OAuth-token

NOTE Before you can receive an OAuth token in a response, you must log in toVirtual Private Cloud OnDemand using the Web UI and accept the Terms of Service.

vCloud Air Platform Programmer's Guide

12 VMware, Inc.

Page 13: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Authorization with vCloud Air and vCloudThe returned OAuth token contains the necessary user attributes, such as user name, user ID, companyname, company ID, and user permissions, for API clients to access each functional boundary surfaced by theAPI and to receive an authorization token from vCloud.

All requests from clients must include the OAuth token the Authorization header:

Authorization: Bearer OAuth_token

After the client authenticates, vCloud Air retrieves a SAML session token (x-vcloud-authorization) andauthenticates with the vCloud instance to perform Compute Service operations.

The response codes indicate whether requests succeeded or how they failed. When a request is successful,the server returns HTTP response code 201 Created because logging in to the API requires a POST call. If anAuthentication header is missing, the server returns HTTP response code 403. If the credentials supplied inan Authentication header are invalid, or if the token has expired, the server returns HTTP response code401.

NOTE OAuth tokens expire 15 minutes after their issue times (even when API clients are active). You cannotrevoke OAuth tokens. If an API client's session terminates and the OAuth token has expired, the client mustre-authenticate with a user name and password.

Roles for the APIs for Cloud AutomationvCloud Air includes predefined roles. Each of these roles includes a set of default rights.

For information about the rights available for each predefined role in vCloud Air, see Role-based UserAccount Management in the vCloud Air Virtual Private Cloud OnDemand User's Guide.

The following roles have access to the vCloud Air API:

n Virtual Infrastructure Administrator – allows management of virtual data centers, virtual machines,and backup settings

n Read-only Administrator – read access to all administration objects

n End User role – read and write access to virtual machines

These vCloud Air roles map to the following roles in the vCloud API for the Compute Service as follows:

Table 1‑3. vCloud Air Roles Mapped to vCloud API Roles

vCloud Air vCloud API for the Compute Service

Virtual Infrastructure Administrator VPC Administrator

Read-Only Administrator Read-Only VPC Administrator

End User VPC User

Each of the vCloud API roles—VPC Administrator, Read-Only VPC Administrator, and VPC User—provideaccess to vCloud functionality. For the access list for each of the vCloud API roles, see vCloud Air Roles andvCloud Director Rights in the vCloud Air Compute Service Programming Guide.

Error Codes and Error HandlingThe following API functional boundaries for vCloud Air are designed to use standardized error handling:

n Identity Management Service (IAM)

n Service Controller (SC)

Chapter 1 About the vCloud Air Platform APIs

VMware, Inc. 13

Page 14: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

n Metering Service (M/B)

For information about the errors returned by the Compute Service, see vCloud API REST Responses in thevCloud Air Compute Service Programming Guide.

When an API client receives a response containing HTTP status code 400 and higher for any resource, theresponse body includes the following attributes:

n A standard error message type

n The class of the error, which matches the HTTP status code

n The specific error code from the error code list for the vCloud Air Platform APIs

n A detailed error message

n Additional information (when available), such as a link to details about the error

Table 1‑4. Description of the Error Codes that the API Returns

Code Possible Causes Components

CLIENT ERRORS

400 The request body is malformed, incomplete, or otherwise invalid. IAM, SC, M/B

401 Unable to authenticate: Provided credentials are not valid.n The credentials supplied in an Authentication header are invalid.n The OAuth token has expired.

IAM, SC, M/B

403 n The Authentication header is missing.n The server does not support the requested operation.n One or more objects specified in the request could not be found in

the specified container.n The user is not authenticated or does not have adequate privileges to

access one or more objects specified in the request.n The user's session has expired.

IAM, SC, M/B

404 n The specified resource does not exist.n The request URL or request body is malformed.

IAM, SC, M/B

405 The HTTP method specified in the request is not supported for thisobject. (The links applicable to a resource are returned as a part of theresource.)

SC

409 n The object state is not compatible with the requested operation.n A duplicate exists. All resources are uniquely identified by an ID

field.

IAM, SC

412 A precondition failed:n If received when logging in, the precondition failed because the user

did not accepted the Terms of Service.n A resource could not be updated because the resource changed on

the server since the last time it was retrieved.

IAM

413 The requested entity is too large.{"maxOperations": 1000,"maxPayload": 1048576}

IAM

SERVER ERRORS

500 The request was received but could not be completed because of aninternal server error or a timeout.

IAM, SC, M/B

501 The requested operation is not supported. IAM

503 The server is busy performing a long running operation. SC

vCloud Air Platform Programmer's Guide

14 VMware, Inc.

Page 15: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Filter ExpressionsYou can filter results using string matching or numeric comparison operations. A filter comprises one ormore subexpressions drawn from the following set of operators.

When using filtering with the API, the following conditions apply:

n All collection APIs use standardized filtering.

n Only one query parameter is supported for filtering named as "filter".

n Filter expressions use the following format: filter={expression}

NOTE Only the Service Controller APIs (/api/sc/plans and /api/sc/instances) support filter expressions.

Table 1‑5. Supported Filter Operators

Operator Example Operation

== attribute==value MatchesThe example evaluates to true if attribute has a value thatmatches value in a case-sensitive comparison.NOTE Asterisk (*) characters that appear anywhere in value aretreated as wildcards that match any character string. Whenvalue includes wildcards, the comparison with attributebecomes case insensitive.

!= attribute!=value Does not matchThe example evaluates to true if attribute has a value that doesnot match value in a case-sensitive comparison. Wildcardcharacters are not allowed.

; attribute1==value1;attribute2!=value2

Logical ANDThe example evaluates to true only if attribute1 has a valuethat matches value1 and attribute2 has a value that does notmatch value2 in a case-sensitive comparison.

, attribute1==value1,attribute2==value2

Logical ORThe example evaluates to true if attribute1 has a value thatmatches value1 or attribute2 has a value that matches value2in a case-sensitive comparison.

vCloud Air Platform APIs Schema ReferenceThe schema reference includes detailed information about the XML representations of all vCloud Air APIobjects and HTTP requests that operate on those objects.

The API represents objects in a cloud as XML documents in which object properties are contained inelements and attributes that have typed values, and an explicit object hierarchy defined by an XML schema.The schema reference includes reference material for all elements, types, and operations in vCloud Air.

Clients of RESTful Web services must be able to request object representations from the server, parse theserver's responses to extract the information contained in the responses, and compose requests that arebased on the information extracted from the responses.

vCloud Air uses a validating XML parser that requires elements in XML documents to agree in order andnumber with the schema. Required elements must appear in requests. All elements that appear in requestsmust appear in the order established by the schema, and with content that conforms to the type constraintspecified in the schema.

The schema reference is available in HTML format in the vCloud Air Documentation Center. See vCloudAir Platform REST APIs Schema Reference.

Chapter 1 About the vCloud Air Platform APIs

VMware, Inc. 15

Page 16: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

The schema reference includes the schema definition files. To download the complete set of schemas for thevCloud Air Platform APIs, see Download an Archive in the vCloud Air Documentation Center.

About the Examples in This Programmer's GuideThe examples in this guide of HTTP requests and responses illustrate the workflow and content that isassociated with automating login to vCloud Air, user management, and obtaining metering data forresource usage.

NOTE The vCloud Air Platform APIs support XML and JSON data input and output formats. Thisprogrammer's guide provides examples for requests and responses by using JSON and XML formatinterchangeably.

Example request headers follow these conventions:

n Header names and values are case-insensitive, and can be submitted or returned in any character case.

n HTTP headers (such as Date, Content-Length, and Server) are omitted when they are not relevant to thespecifics of the example.

Example responses follow these conventions:

n Responses show only those elements and attributes that are relevant to the operation being explained.Ellipses (…) indicate omitted content within responses.

n Object IDs shown in href attribute values appear as small integers, for example vca-2 for compute-uuidor vdc-7 for vdc-uuid. In the API, object IDs are universal unique identifiers (UUIDs) as defined by RFC4122, for example f5e185a4-7c00-41f1-8b91-0e552d538101.

vCloud Air Platform Programmer's Guide

16 VMware, Inc.

Page 17: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Hello vCloud Air: A SimplifiedRESTful Workflow 2

vCloud Air clients and servers communicate over HTTPS, exchanging XML or JSON representations ofvCloud API objects for the Compute Service. This simplified example of a RESTful workflow includeslogging in to Virtual Private Cloud OnDemand and requesting service details from the Service Controller.

Using the plan and instance data returned from the Service Controller, you can create a vCloud session toobtain the list of virtual data centers for a Compute Service. For the steps to create a vCloud session to accessthe vCloud Compute Service, see the Access the vCloud API Through the vCloud Compute Service invCloud Air in vCloud Air Compute Service Programming Guide.

These tasks assume that you have registered for Virtual Private Cloud OnDemand and have received youruser account information.

For information about signing up for Virtual Private Cloud OnDemand, see Create Your Account invCloud Air – Virtual Private Cloud OnDemand Getting Started.

This guide documents how to use the vCloud Air Platform APIs to retrieve information about theVirtual Private Cloud OnDemand plans and for customers to retrieve information about their instances.

A user in vCloud Air can access the vCloud API through the vCloud Compute Service. The vCloudCompute Service is the service that exposes the compute, networking, and storage functionality that isavailable to customers of Virtual Private Cloud OnDemand.

1 Log In and Receive Access Token on page 18vCloud Air requires login requests to be authenticated. Begin the workflow with a login request thatsupplies user credentials in the MIME Base64 encoding format as specified in RFC 1421.

2 List Available Plans and Instances on page 19To programmatically access the vCloud Compute Service, you must discover the plans and instancesavailable in Virtual Private Cloud OnDemand.

VMware, Inc. 17

Page 18: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Log In and Receive Access TokenvCloud Air requires login requests to be authenticated. Begin the workflow with a login request thatsupplies user credentials in the MIME Base64 encoding format as specified in RFC 1421.

Figure 2‑1. Log in and Accept Terms of Service Sequence Diagram

Client

Client

IAM

IAM

alt

POST api/iam/login

Authentication failedResponse 401 unauthorized

Response 412 TOS not accepted

Success & TOS acceptedStore SAML token in database

Generate OAuth 2.0 access token

Response 201 Created (token in Response header)

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

See Create Your Account in vCloud Air – Virtual Private Cloud OnDemand Getting Started for information.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

Procedure

u POST a request that includes your user name and password in a MIME Base64 encoding:

POST https://vca.vmware.com/api/iam/login

The initial POST requires that you enter the Authorization header with an encoded Base64username:password value as shown:

Authorization: Basic [email protected]:password

Wherein [email protected]:password is encoded.

If the request is successful, the server returns HTTP response code 201 Created and a response thatcontains the vchs-authorization.

TIP Alternatively, you can submit the following POST request if the request in this step is unsuccessful:

POST https://iam.vchs.vmware.com/api/iam/login

Example: Request and Response to Log InRequest Header

POST https://vca.vmware.com/api/iam/login

Accept: application/json;version=5.7

Authorization Basic cHhzdXNlcjFAdm13YXJlLmNvbTpQYXNzQDEyMw==…

vCloud Air Platform Programmer's Guide

18 VMware, Inc.

Page 19: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Request body not required.

Response

HTTP/1.1 201 Created

Header:

Content-Type: application/json;version=5.7

vchs-authorization: eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF…

Body:

{"serviceGroupIds":["89a6da00-0d15-48e9-8fed-6c87dfca5c0e"]}

List Available Plans and InstancesTo programmatically access the vCloud Compute Service, you must discover the plans and instancesavailable in Virtual Private Cloud OnDemand.

Figure 2‑2. Log in and List Available Plans and Instance Sequence Diagram

alt

Client

Client

IAM

IAM SC

SC

POST api/iam/login

Response 201 Created

GET api/sc/plans

Response 200 OK (list of plans)

GET api/sc/instances

[Response OK]

Response with 404 - Not Found[No instances]

Response 200 OK (list of instances)

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

Procedure

1 POST a request that includes your user name and password in a MIME Base64 encoding:

POST https://vca.vmware.com/api/iam/login

The initial POST requires that you enter the Authorization header with an encoded Base64username:password value as shown:

Authorization: Basic [email protected]:password

Wherein [email protected]:password is encoded.

If the request is successful, the server returns HTTP response code 201 Created and a response thatcontains the vchs-authorization.

2 Issue a request to get the list of service plans for your account:

GET https://vca.vmware.com/api/sc/plans

Chapter 2 Hello vCloud Air: A Simplified RESTful Workflow

VMware, Inc. 19

Page 20: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

In the request, include the OAuth token:

Authorization: Bearer OAuth_token

Include the OAuth token in all subsequent API requests as a request header.

The returned response includes the list of plans for your account. Each plan consists of the followingelements:

Element Description

id The ID of the plan

name The name of the plan

region The geographical location where the plan is offered

description Description about the plan

planVersion The version of the plan

serviceUri The API endpoint of the service offering for the plan

instanceSpec Custom values to create an instanceWhen instanceSpec is specified, default values are not used when theinstance is created.

planAttributes The attributes associated with a given plan

planPolicy Policy information for the planThe planPolicy element enables functionality for future releases.

3 Issue a request to get a list of all the instances:

GET https://vca.vmware.com/api/sc/instances

The response includes your list of all instances. Each instance has the following elements:

Element Description

description Description of the instance

region The geographical location where the instance was created

instanceVersion The version of the instance

planId The plan associated with the creation of the instance

serviceGroupId The service group ID associated with the creation of the instance

apiUrl The API endpoint to access the instanceYou use the value in the apiUrl to log in to the Compute Service forVirtual Private Cloud OnDemand.

dashboardUrl The URL to access the Compute Service by using the Web UI

instanceAttributes The attributes associated with a given instance

id The ID of the instance

name The name of the instance

Example: Request and Response to List Plans and InstancesRequest Header – Log in

POST https://vca.vmware.com/api/iam/login

Accept: application/json;version=5.7

Authorization: Basic cHhzdXNlcjFAdm13YXJlLmNvbTpQYXNzQDEyMw==…

Request body not required.

vCloud Air Platform Programmer's Guide

20 VMware, Inc.

Page 21: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Response – Log in

HTTP/1.1 201 Created

Header:

vchs-authorization: eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF…

Body:

{"serviceGroupIds":["37"]}

Request Header – Get plans

GET https://vca.vmware.com/api/sc/plans

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF…

Response body not required.

Response Body – Get plans

{

{

"plans": [{

"link": [],

"region": "LVG",

"serviceName": "com.vmware.vchs.compute",

"description": "Create virtual machines, and scale as your needs change.",

"planVersion": "1.0",

"instanceSpec": "",

"planAttributes": "attributes",

"planPolicy": {

"canCreateInstance": true,

"canCreateBinding": true,

"maxInstanceCount": 1

},

"id": "6",

"name": "Virtual Private Cloud OnDemand"

}]

}

Request Header – Get instances

GET https://vca.vmware.com/api/sc/instances

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJmOTF…

Response Body – Get instances

{

"instances": [{

"link": [],

"description": "Create virtual machines, and scale as your needs change.",

"region": "LVG",

"instanceVersion": "1.0",

"planId": "24",

"serviceGroupId": "37",

"apiUrl": "https://example_host.vmware.com/api/compute/api/org/17",

"dashboardUrl": "https://example_host.vmware.com/api/compute/compute/ui?

orgName=42&serviceInstanceId=17",

"instanceAttributes":

"{\"orgName\":\"42\",\"sessionUri\":\"https://example_host.vmware.com/api/compute/api/sessions\"}

",

Chapter 2 Hello vCloud Air: A Simplified RESTful Workflow

VMware, Inc. 21

Page 22: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

"id": "71",

"name": "Virtual Private Cloud OnDemand"

}]

}

vCloud Air Platform Programmer's Guide

22 VMware, Inc.

Page 23: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Managing Users 3Administrators add users for Virtual Private Cloud OnDemand and assign one or more roles to them. Userroles have a default group of privileges. Administrators can manage users and their details.

This chapter includes the following topics:

n “About User Management,” on page 23

n “List Users,” on page 25

n “Add a User,” on page 28

n “Update a User,” on page 30

n “Delete a User,” on page 33

n “Retrieve Forgotten Password,” on page 34

About User ManagementvCloud Air includes APIs for full, user lifecycle management.

Schema for User Management ResourcesvCloud Air implements user management by using attributes from the common System for Cross-DomainIdentity Management (SCIM) specification, which is designed for managing user identity in cloud-basedapplications, and adds schema extensions for functions unique to vCloud Air.

Table 3‑1. Common Elements from the SCIM Schema

Element Description

email Email address for the userNOTE The userName and email attributes must contain the same values.

familyName Family name or last name for the user

givenName First name of the user

VMware, Inc. 23

Page 24: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Table 3‑1. Common Elements from the SCIM Schema (Continued)

Element Description

roles The roles to which the user is assigned

name Name of the roles assigned to the userYou can assign a user to the following roles:n Account Administratorn Virtual Infrastructure Administratorn Network Administratorn Read-Only Administratorn End UserThe roles are mutually exclusive with the exception of the Network Administratorand Virtual Infrastructure Administrator roles; meaning, you can assign a user to theNetwork Administrator and Virtual Infrastructure Administrator roles, or theAccount Administrator, Read-Only Administrator, or End User role.For information about the rights available for each predefined role in vCloud Air, see Role-based User Account Management in the vCloud AirVirtual Private Cloud OnDemand User's Guide.

Table 3‑2. Schema Extensions for User Management

Extension Description

state State of the user—active or inactive

id Unique ID of the userCreated automatically when you create the user.

companyId ID of the company to which the user belongsCreated automatically when VMware creates your Virtual Private Cloud OnDemandaccount.

customerNumber Not used by the API

serviceGroupIds The service group ID associated with the userWhen you sign up for Virtual Private Cloud OnDemand, VMware creates youraccount and assigns a service group ID to your account. VMware uses your servicegroup ID as part of its billing system. The service group ID indicates which billingaccount to charge for resource usage.

tosAccepted Whether the Terms of Service has been accepted by the userNOTE You cannot update the tosAccepted element for a user.

tosAcceptDate When the user accepted the Terms of ServiceNOTE You cannot update the tosAcceptDate element for a user.

userName Name of the user in email formatNOTE The userName and email attributes must contain the same values.

Summary of User Management OperationsAs shown in the following sequence diagram, the APIs for Virtual Private Cloud OnDemand include thecommon CRUD (create, read, update, and delete) methods for the user management operations.

vCloud Air Platform Programmer's Guide

24 VMware, Inc.

Page 25: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Figure 3‑1. User Management API Sequence Diagram

PUT api/iam/Users/{user-id} (update user name)

GET api/iam/Users

POST api/iam/loginResponse 201 Created

Response 200 OK (list of all users)

GET api/iam/Users?self=1

Response 200 OK (user “self” details)

Response 204 No Content

Response 200 OK

Response 204 No Content

Response 201 Created

POST api/iam/Users (create user with Response body)

GET api/iam/Users/{user-id}

DELETE api/iam/Users/{user-id} (delete user)

Client

Client IAM

IAM

Additionally, the APIs include an operation to handle a forgotten password. See “Retrieve ForgottenPassword,” on page 34 for information.

List UsersUse these operations to retrieve a list of all users created to access Virtual Private Cloud OnDemand or toretrieve the details for a specified user.

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

n You have logged in as an administrator using the /api/IAM/login API and received an OATH token.See “Log In and Receive Access Token,” on page 18 for information.

Procedure

1 Issue a request to get the list of users for your account:

GET https://vca.vmware.com/api/IAM/Users

In the request, include the OATH token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

Include the OATH token in all subsequent API requests as a request header.

The returned response includes the list of users added for your account.

2 To get the details for a specific user, issue the following request:

GET https://vca.vmware.com/api/IAM/Users/userId

Where userId is the ID you received in step 1.

Chapter 3 Managing Users

VMware, Inc. 25

Page 26: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Example: Requests and Responses to List UsersThis example shows how to request a list of all users for your account and then request details for a specificuser.

Request Header – List all users

GET https://vca.vmware.com/api/IAM/Users

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request body not required.

Response Body – List all users

{"users":[

"meta": {

"created":1402527010108,

"modified":1402527010108

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"id": "790ee208-6c7d-4177-b6c6-212bdbe1a66b",

"companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2",

"customerNumber": null,

"email": "[email protected]",

"familyName": "samplefamily1",

"givenName": "Jane",

"roles": {

"roles": [

{

"description": "Allows creation and management of VMs.",

"name": "End User",

"id": "6"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

},

{

"meta": {

"created":1402527205542

"modified":1402527205542

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"id": "021cd2ab-c727-45f0-bbaf-1bb2f4af4b72",

"companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2",

vCloud Air Platform Programmer's Guide

26 VMware, Inc.

Page 27: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

"customerNumber": null,

"email": "[email protected]",

"familyName": "FamilyName",

"givenName": "John",

"roles": {

"roles": [

{

"description": "Allows user management and account settings.",

"name": "Account Administrator",

"id": "1"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

}

]

}

Request Header – Get user

GET https://vca.vmware.com/api/iam/Users/790ee208-6c7d-4177-b6c6-212bdbe1a66b

Request body not required.

Response Body – Get user

{"users":[

"meta": {

"created":1402527010108,

"modified":1402527010108

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"id": "790ee208-6c7d-4177-b6c6-212bdbe1a66b",

"companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2",

"customerNumber": null,

"email": "[email protected]",

"familyName": "samplefamily1",

"givenName": "Jane",

"roles": {

"roles": [

{

"description": "Allows creation and management of VMs.",

"name": "End User",

"id": "6"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

Chapter 3 Managing Users

VMware, Inc. 27

Page 28: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

}

Add a UserYou can add users and assign privileges to them in Virtual Private Cloud OnDemand.

The company attribute is present in the OAuth token vCloud Air that sends as a part of the Authorizationheader. The new user is created using the company value of the administrator who logged in to create theuser.

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

n You have logged in as an administrator using the /api/iam/login API and received an OAuth token.See “Log In and Receive Access Token,” on page 18 for information.

Procedure

u Issue a request to create a user for your account:

POST https://vca.vmware.com/api/iam/Users

In the request, include the OAuth token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

Include the following elements in the request body:

Table 3‑3. Required Elements to Create a User

Element Description

state State of the user—active or inactive

email Email address for the userNOTE The userName and email attributes must contain the same values.

familyName Family name or last name for the user

givenName First name of the user

roles The roles to which the user is assigned

vCloud Air Platform Programmer's Guide

28 VMware, Inc.

Page 29: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Table 3‑3. Required Elements to Create a User (Continued)

Element Description

name Name of the roles assigned to the userYou can assign a user to the following roles:n Account Administratorn Virtual Infrastructure Administratorn Network Administratorn Read-Only Administratorn End UserThe roles are mutually exclusive with the exception of the Network Administrator andVirtual Infrastructure Administrator roles; meaning, you can assign a user to the NetworkAdministrator and Virtual Infrastructure Administrator roles, or the AccountAdministrator, Read-Only Administrator, or End User role.For information about the rights available for each predefined role in vCloud Air, see Role-based User Account Management in the vCloud Air Virtual Private Cloud OnDemandUser's Guide.

userName Name of the user in email formatNOTE The userName and email attributes must contain the same values.

Example: Request and Response to Add a UserRequest Header – Add user

POST https://vca.vmware.com/api/iam/Users

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request Body – Add user

{

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"email": "[email protected]",

"familyName": "test12345",

"givenName": "Jill",

"roles": {

"roles": [

{

"name": "End User"

}

]

},

"userName": "[email protected]"

}

Response – Add user

Header:

Status: 201 CREATED

Body:

{

"meta": {

"created": 1400665149048,

"modified": 1400665149048

},

Chapter 3 Managing Users

VMware, Inc. 29

Page 30: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"id": "7179ba2e-6d49-485f-b54e-16e3b8ea3058",

"companyId": "422ca48d-a8e6-4b71-9f8f-5aa78362f98e",

"customerNumber": null,

"email": "[email protected]",

"familyName": "test12345",

"givenName": "Jill",

"roles": {

"roles": [

{

"description": "Allows creation and management of VMs.",

"name": "End User",

"id": "6"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

}

Update a UserTo update a user's profile in Virtual Private Cloud OnDemand, issue a PUT request for a specific user's ID.

All elements are required and omitting elements will cause an error. VMware recommends you issue a GETrequest to retrieve the user's profile, modify the profile, then submit the changes by sending a PUT request.

You can update the following elements for a user:

n givenName

n familyName

n state

n name within the roles element

You can update the name to one of the following values: Account Administrator, Read-OnlyAdministrator, End User, Virtual Infrastructure Administrator, Network Administrator .

NOTE Role updates do not rely on IDs. Change the role name field. The API ignores any changes youmake to the id or description attributes.

n email

The API partially supports updating this element. Update the email element to change the address thatVMware uses when sending Virtual Private Cloud OnDemand messages to the user.

NOTE Updating the email element does not change the value for the userName element.

You cannot update the following attributes for a user:

n userName

vCloud Air Platform Programmer's Guide

30 VMware, Inc.

Page 31: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

n companyId

n userId

n tosAccepted

n tosAcceptDate

n Meta fields

n Schema field

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

n You have logged in as an administrator and received an OAuth token. See “Log In and Receive AccessToken,” on page 18 for information.

Procedure

1 (Optional) Issue a request to get the ID and elements for the user that you want to update:

GET https://vca.vmware.com/api/iam/Users

In the request, include the OAuth token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

Include the OAuth token in all subsequent API requests as a request header.

The returned response includes the list of users added for your account.

2 Issue the following request to update the user's profile:

PUT https://vca.vmware.com/api/iam/Users/userId

In the request, include the OAuth token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

In the request body, include the required elements for the user.

NOTE All elements are required and omitting elements will cause an error. VMware recommends youissue a GET request to retrieve the user's profile, modify the profile, then submit the changes bysending a PUT request.

See “About User Management,” on page 23 for a description of each element.

Example: Requests and Responses to Update a UserThis example shows how to request the profile of a specific user and update the values for familyName androles. The elements and values returned in the GET userId response are provided and updated in theupdate user request body as follows:

n familyName updated from “samplefamily1” to “newName”

n roles updated from End User to Account Administrator.

Chapter 3 Managing Users

VMware, Inc. 31

Page 32: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Request Header – Get userId 790ee208-6c7d-4177-b6c6-212bdbe1a66b

GET https://vca.vmware.com/api/iam/Users/790ee208-6c7d-4177-b6c6-212bdbe1a66b

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request body not required.

Response Body – Get userId 790ee208-6c7d-4177-b6c6-212bdbe1a66b

{"users":[

"meta": {

"created":1402527010108,

"modified":1402527010108

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

"id": "790ee208-6c7d-4177-b6c6-212bdbe1a66b",

"companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2",

"customerNumber": null,

"email": "[email protected]",

"familyName": "samplefamily1",

"givenName": "Jane",

"roles": {

"roles": [

{

"description": "Allows creation and management of VMs.",

"name": "End User",

"id": "6"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

}

Request Header – Update user

PUT https://vca.vmware.com/api/iam/Users/790ee208-6c7d-4177-b6c6-212bdbe1a66b

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request Body – Update user

{"users":[

"meta": {

"created":1402527010108,

"modified":1402527010108

},

"schemas": [

"urn:scim:schemas:core:1.0"

],

"state": "Active",

vCloud Air Platform Programmer's Guide

32 VMware, Inc.

Page 33: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

"id": "790ee208-6c7d-4177-b6c6-212bdbe1a66b",

"companyId": "e9b1f777-ab16-493d-a0af-ad3474e13cd2",

"customerNumber": null,

"email": "[email protected]",

"familyName": "newName",

"givenName": "Jane",

"roles": {

"roles": [

{

"description": "Allows creation and management of VMs.",

"name": "Account Administrator",

"id": "6"

}

]

},

"serviceGroupIds": {

"serviceGroupIds": []

},

"tosAcceptDate": null,

"tosAccepted": false,

"userName": "[email protected]"

}

Response Header – Update user

Status: 204 NO CONTENT

Connection: close

Content-Length: 0

Content-Type: text/plain; charset=UTF-8

Date: Fri, 06 Jun 2014 06:53:40 GMT

Server: Apache-Coyote/1.1

Response body not returned.

Delete a UserWhen users leave your company, you might want to delete their user profile fromVirtual Private Cloud OnDemand.

You can delete users from Virtual Private Cloud OnDemand to revoke their access to the service. In thisway, you can recover any resources that were assigned to the user. If you delete users who are signed in atthe time, their sessions will be forcibly terminated and they will be signed out. The user is deleted and doesnot appear in the user list. The end user's resources (such as any virtual machines that they own) are movedto the administrator who deleted the user.

To temporarily suspend a user's account, you can change the user's state from active to inactive. See “Update a User,” on page 30 for information.

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

n You have logged in as an administrator using the /api/iam/login API and received an OATH token.See “Log In and Receive Access Token,” on page 18 for information.

Chapter 3 Managing Users

VMware, Inc. 33

Page 34: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Procedure

1 If necessary, issue a request to get the ID for the user who you want to delete:

GET https://vca.vmware.com/api/iam/Users

In the request, include the OAuth token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

Include the OAuth token in all subsequent API requests as a request header.

The returned response includes the list of users for your account.

2 Issue the request to delete the user:

DELETE https://vca.vmware.com/api/iam/Users/user_id

Example: Request and Response to Delete a UserRequest Header – Delete user

DELETE https://vca.vmware.com/api/iam/Users/aef1ee7e-c645-49db-83ae-ce9ad164df53

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request body not required.

Response Header – Delete user

Status: 204 NO CONTENT

Connection: close

Content-Length: 0

Content-Type: text/plain; charset=UTF-8

Date: Thu, 26 Jun 2014 05:30:20 GMT

Server: Apache-Coyote/1.1

Response body not returned.

Retrieve Forgotten PasswordWhen a user forgets a password, you can use the API to send the user an email with links to change thepassword. The email is sent to the email address in the element userName.

Prerequisites

n You have signed up and registered for Virtual Private Cloud OnDemand and received an email with auser name and password for an Account Administrator.

n Using the URL in the confirmation email, you have logged in to Virtual Private Cloud OnDemandusing the Web UI, set your password, and accepted the Terms of Service.

n You have logged in as an administrator using the /api/iam/login API and received an OAuth token.See “Log In and Receive Access Token,” on page 18 for information.

Procedure

1 If necessary, issue a request to get the user name for the user who has forgotten a password:

GET https://vca.vmware.com/api/iam/Users/userId

In the request, include the OAuth token and the Accept header:

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

vCloud Air Platform Programmer's Guide

34 VMware, Inc.

Page 35: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Include the OAuth token in all subsequent API requests as a request header.

The returned response includes elements for the specified users.

2 Issue a request to send a link to reset the user password:

PUT https://vca.vmware.com/api/iam/Users/userName/password/forgot

Accept: application/json;version=5.7

Authorization: Bearer OAuth_token

Example: Request and Response to Retrieve Forgotten PasswordRequest Header – Retrieve password

PUT https://vca.vmware.com/iam/Users/[email protected]/password/forgot

Accept: application/json;version=5.7

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJiN2VjNjUyZi1mZmUzLTRh…

Request body not required.

Response Header

Status: 202 ACCEPTED

Content-Length: 0

Date: Mon, 19 May 2014 09:38:30 GMT

Server: Apache-Coyote/1.1

Response body not returned.

Chapter 3 Managing Users

VMware, Inc. 35

Page 36: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

vCloud Air Platform Programmer's Guide

36 VMware, Inc.

Page 37: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Metering and Billing for ResourceUsage 4

With Virtual Private Cloud OnDemand, customers pay nothing up front. They pay for only the services theyactually used, on a metered, charge-back basis, under flexible service agreements, as opposed to fixed-termcontracts.

You can use the vCloud Air Platform APIs to retrieve read-only information about current unbilled resourceusage and billed usage for Virtual Private Cloud OnDemand.

For information about how VMware meters and bills resource usage for Virtual Private Cloud OnDemand,see Metering Resource Usage in the vCloud Air – Virtual Private Cloud OnDemand User's Guide.

This chapter includes the following topics:

n “About Resource Usage Metering and Billing,” on page 37

n “Workflow for Using the Metering GET Operations,” on page 38

n “Summary of Metering and Billing Requests,” on page 39

About Resource Usage Metering and BillingTo utilize the metering API to obtain metering and billing data for Virtual Private Cloud OnDemand, theMetering Service requires the context for metering data collection.

The Metering Service must map resource usage for a specific instance to a service group. The ServiceController requires a mapping between serviceGroupId and instance id. The Metering Service passes theinstance id to the Service Controller and the Service Controller responds with the serviceGroupId for thatinstance id. The Compute Service maintains the metering events for the instance id.

See “About Plans, Instances, and the Compute Service,” on page 9 for information about how an instancecontains the serviceGoupId element.

Metering Object HierarchyThe Metering Service operates using the following object hierarchy (with an ID for each object) to map acustomer's company to their billed usage.

– Company Entity that VMware bills for resource usage; for vCloud Air, a customer is equivalent to a company

– ServiceGroup

Part of the VMware billing system—indicates which billing account to charge for resource usage

– Service A consumable instance of a given plan; initialized in a chosen location

– L2 Container for L1 entities; a virtual data center in the Compute Service

VMware, Inc. 37

Page 38: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

– L1 Primary container for a metered entity; a virtual machine or a gateway in the ComputeService

– Billable Usage Metered resource usage

Metered Entities > L2 and L1Metered entities provide a container for measurements and are directly managed by the Metering Service.The Metering Service defines two abstract containers for metering—L2 and L1. These containers correspondto entities in the Compute Service. An L1 entity is a primary container that the Metering Service monitors;an L2 entity is a container of L1 entities.

In the Compute Service, a virtual machine and a gateway are L1 entities and the virtual data center (VDC)that contains them is the corresponding L2 entity.

Current Versus Billed Usage in the APICurrent usage includes mid-cycle usage when an account is in between billing statements; you query forcurrent usage by using date ranges. The Metering Service returns data for bill-to-date usage.

Billed usage includes usage, rates, and cost as invoiced by VMware. You query for billed usage by using theanniversary (month and year) date.

Getting current and billed usage across the same date range involves issuing separate calls to the currentand billed usage endpoints with appropriate input dates.

Workflow for Using the Metering GET OperationsRetrieving read-only metering and billing information for your Virtual Private Cloud OnDemand accountby using the APIs for the vCloud Air Compute Service and vCloud Air Platform APIs uses the followingworkflow:

1 Issue a login request that supplies user credentials in the MIME Base64 encoding format as specified inRFC 1421.

See “Log In and Receive Access Token,” on page 18 for information.

2 To access the vCloud Compute Service, discover the instance accessible to you inVirtual Private Cloud OnDemand.

See “List Available Plans and Instances,” on page 19 for information.

3 Access the Compute Service through the vCloud API.

See Access the vCloud API Through the vCloud Compute Service in vCloud Air in the vCloud AirCompute Service Programming Guide for information.

4 Issue a request to get the virtual data center attributes for the Org you have logged into.

See Find a Catalog and a VDC in the vCloud Air Compute Service Programming Guide for information.

The response contains the virtual data center ID you need for the metering API GET operations. Theresponse also contains the vApp Container href to navigate to specific virtual machines for which to getmetering data.

5 Retrieve a virtual machine ID by using the discovered virtual machine href.

See Deploying and Operating vApps and Virtual Machines in the vCloud Air Compute ServiceProgramming Guide.

6 Issue a metering GET operation to retrieve resource usage data for the virtual data center or virtualmachine you have navigated to.

vCloud Air Platform Programmer's Guide

38 VMware, Inc.

Page 39: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

See “Summary of Metering and Billing Requests,” on page 39 for information.

Summary of Metering and Billing RequestsThe vCloud Air Platform APIs include the following GET operations that you can use to retrieve meteringand billing information for your Virtual Private Cloud OnDemand account.

Table 4‑1. Resource Usage API Operations for Virtual Private Cloud OnDemand

Request Response Parameters Description

GET /api/metering/service-group/{service-group-id}/billable-costs

BilledCosts n month=..n year=....

Returns the billable value of cost itemsassociated with a service group:n Support Costn Service Credit

GET /api/metering/service-instance/{service-instance-id}/billable-usage

BilledUsage n month=..n year=....n level=....

Returns all billable usage for aninstance. The response includes rolled-up usage for all L2 entities associatedwith the instance. Usage can be rolledup over a period of hours, days, ormonths, or for a specified time.

GET /api/metering/service-instance/{service-instance-id}/l1/{l1-id}/billable-usage

BilledUsage n month=..n year=....

Returns all billable usage for an L1entity. This request returns aggregatedusage data. Usage can be aggregatedover a period of hours, days, ormonths, or for a specified time.

GET /api/metering/service-instance/{service-instance-id}/l2/{l2-id}/billable-usage

BilledUsage n month=..n year=....

Returns all billable usage for an L2entity. This request returns rolled-upusage for all L1 entities associated withthe L2 entity. Usage can be rolled upover a period of hours, days, ormonths, or for a specified time.

GET /api/billing/service-groups ServiceGroups — Returns all service groups for acompany:n Company detailsn Service group

n Billing currencyn Spend threshold and other

billing attributesn Anniversary dates

The OAuth token determines thecompany for which service groupdetails are returned.

GET /api/billing/service-group/{service-group-id}

ServiceGroup — Returns service group details:n Billing currencyn Spend threshold and other billing

attributesn Anniversary dates

GET /api/billing/service-group/{service-group-id}/billed-costs

BillableCosts — Returns the costs associated with aservice group for a billing cycle:n Support Costn Service Credit

GET /api/billing/service-group/{service-group-id}/billed-usage

BillableUsage n start=n end= or

duration=...

Returns all billed usage for a servicegroup post invoicing. This requestreturns all rolled-up usage for all L1entities and L2 entities associated withthe service group ID.

Chapter 4 Metering and Billing for Resource Usage

VMware, Inc. 39

Page 40: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Table 4‑1. Resource Usage API Operations for Virtual Private Cloud OnDemand (Continued)

Request Response Parameters Description

GET /api/billing/service-instance/{service-instance-id}/l1/{l1-id}/billed-usage

BillableUsage n start=n end= or

duration=...

Returns all billed usage for an L1 entitypost invoicing. Usage can beaggregated over a billing month or fora specified time.

GET /api/billing/service-instance/{service-instance-id}/l2/{l2-id}/billed-usage

BillableUsage n start=n end= or

duration=...

Returns all billed usage for an L2 entitypost invoicing. This request returnsrolled-up usage for all L1 entitiesassociated with the L2 entity. Usagecan be rolled up over a billing month orfor a specified time.

vCloud Air Platform Programmer's Guide

40 VMware, Inc.

Page 41: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Index

AAccept header 11, 12API

components 8Compute Service 8Compute Service endpoint 9Networking Service 8sign-up requirement 17user roles 13version 11

audiences, defined 8authentication, requirements 18Authentication header, error 13Authorization header 12, 18

Bbasic auth 18

Ccompany attribute, from Oauth token 28Compute Service

authorization 12documentation 8errors 13metering entities 37Web URL 19

Content-Type header 11

Ddata format, shown in examples 16documentation set

complete 8Compute Service 8vCloud API 8

Gglossary 5

Hheaders

Accept 11, 12Authorization 12, 18Content-Type 11shown in examples 16

HTTP, status codes 13

IIDs

company 23deleting users 33instances 19metering object hierarchy 37objects 16plans 19roles 23service groups 19updating users 30users 23UUIDs 16virtual data center 38virtual machines 38

infrastructure-as-a-service, defined 7initialize, vCloud Air service 9instances, elements of 19intended audience 5

LL1 entities, defined 37L2 entities, defined 37locations, vCloud Air 9

Mmedia classes 12media type, support 11metering data, read-only 37Metering Service, GET operations 39MIME Base64 encoding 18

NNetworking Service, API 8numeric comparison operations 15

OOauth token

company attribute in 28errors 13expiration 12

operators 15

PplanId, defined 9plans, elements of 19

VMware, Inc. 41

Page 42: vCloud Air Platform Programmer's Guide - vCloud Air OnDemand 5 · services (such as Virtual Private Cloud OnDemand), manage users for Virtual Private Cloud OnDemand, and automate

Rrequest, errors 13resources

recover from users 33usage calculation 37usage metering 37

SSAML session token 12, 18schema

downloading 15reference documentation 8

Service ControllerAPI 17filtering 15

service-oriented architecture, defined 8serviceGroupIds

defined 9metering requirement 37

serviceName, defined 9sessions, users terminated 33SSL encryption 12string matching 15

Tterms of service

accepting 18users accepting 23, 30

tokensOauth 12SAML session 12

type constraints 15

Uusers

deactivating 30discovering ID 25elements of 23, 25email 34updating email 30

UUIDs 16

VvCloud Air

API access 13billing system 37locations 9resources 9service-oriented architecture 8terms of service 18user roles 23

vCloud APIroles mapping 13session 17

Virtual Private Cloud OnDemand, features of 7

virtual data center ID, discovery 38

XXMLschema

definition files 15parser 15

vCloud Air Platform Programmer's Guide

42 VMware, Inc.