3PAR Web Services PDF
3PAR Web Services PDF
3PAR Web Services PDF
1 Developer's Guide
Abstract
This guide provides instructions and reference information for the HP 3PAR Web Services API.
Copyright 2013 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.21 1 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
Contents
1 Introduction...............................................................................................6
About the WSAPI......................................................................................................................6 Typographic Conventions......................................................................................................6 User Input......................................................................................................................6 System Output................................................................................................................6 Getting Started.........................................................................................................................6 Configuring the Server..............................................................................................................6 About the SDK.........................................................................................................................7 Java SDK............................................................................................................................7 Perl SDK.............................................................................................................................7
2 Overview..................................................................................................8
Protocol and Message Format....................................................................................................9 Client Headers....................................................................................................................9 Examples.....................................................................................................................10 Querying CPGs........................................................................................................10 Creating CPGs.........................................................................................................10 Server Headers.................................................................................................................10 Supported HTTP Methods....................................................................................................10 GET............................................................................................................................10 POST...........................................................................................................................11 DELETE........................................................................................................................11 General URI Format................................................................................................................11
3 System Access..........................................................................................12
Creating Credentials...............................................................................................................12 About Multiple Session Keys................................................................................................12 About Session Key Security.................................................................................................12 Creating a Session Key...........................................................................................................12 Deleting a Session Key............................................................................................................13 Getting Version Information......................................................................................................13 Success............................................................................................................................13
5 6 7 8
Request Input and Optional Members.........................................................20 Enumerations...........................................................................................21 JSON Types and API Types........................................................................22 Working with Common Provisioning Groups................................................23
CPG Enumeration and Configuration Objects.............................................................................23 LDLayout Object................................................................................................................23 RAIDType Enumeration........................................................................................................23 HA Enumeration................................................................................................................24 chunkletPosPref Enumeration................................................................................................24 diskPatterns Object.............................................................................................................24 diskType Enumeration.........................................................................................................25
Contents 3
Space Usage Objects.........................................................................................................25 Growth Objects.................................................................................................................26 state Enumeration..............................................................................................................26 detailed state Enumeration..................................................................................................26 Create a CPG........................................................................................................................26 Message Body Parameters..................................................................................................27 Responses.........................................................................................................................27 Success........................................................................................................................27 Error Codes..................................................................................................................27 Remove a CPG.......................................................................................................................27 Responses.........................................................................................................................28 Success........................................................................................................................28 Errors..........................................................................................................................28 Query CPG Information...........................................................................................................28 Responses.........................................................................................................................29 Success........................................................................................................................29
Success........................................................................................................................43 Error Codes..................................................................................................................43 Example...........................................................................................................................43 HTTP Request................................................................................................................43 HTTP Response.............................................................................................................43 Query VLUN Information.........................................................................................................43 Responses.........................................................................................................................43 Success........................................................................................................................43 JSON Objects in a VLUN Query................................................................................44 Example...........................................................................................................................45 HTTP Request................................................................................................................45 HTTP Response.............................................................................................................45
12 Documentation feedback.........................................................................51
Contents
1 Introduction
This Developer's Guide describes how to write a client that uses the HP 3PAR Web Services API (HP 3PAR WSAPI) to manage HP 3PAR storage systems. HP 3PAR storage systems include both hardware components that store data, and software applications to manage data. The Application Program Interface (API) provides a more flexible and powerful way to perform storage management tasks than Command Line Interface (CLI) scripting or the HP 3PAR OS Management Console software. This API enables you to automate management of volumes, Common Provisioning Groups (CPGs), and Virtual LUNs (VLUNs).
Typographic Conventions
User Input
User-supplied text is marked as boldface and enclosed in angle brackets, as follows: https://<Storage System>:8080/api/v1/credentials/<session key> In this example, the user supplied text is:
Text <Storage System> <session key> Description The name of the server processing requests and sending responses. The session key. For more information on session keys, see Creating Credentials (page 12)
System Output
System-supplied variables are marked in italics and enclosed in angle brackets, as follows: /api/v1/volumes/<volume name> <volume name> in this case is the name of the newly created volume, returned in the HTTP Location header.
Getting Started
This section of the HP 3PAR Web Services API Developer's Guide shows how to configure the server. Included also is an introduction to the WSAPI commands and a summary of the items included in the HP 3PAR Web Services API Server SDK. It contains the following topics: Configuring the server About the SDK
Introduction
NOTE: 2.
Java SDK
The Java SDK includes: Core "storage-entity" classes representing the attributes of HP 3PAR storage system objects (CPGs, volumes, VLUNs) and input parameters for creating objects. An example client interface which demonstrates the use of JavaScript Object Notation (JSON) processors with the base classes. Example programs to illustrate the creation and query of base entities. These examples rely on the accessor and base packages.
Perl SDK
The Perl SDK includes: A module with methods for accessing the HP 3PAR storage system. Modules with mappings of the error codes and enumerated properties used by WSAPI. An example program that demonstrates creation, querying, and deleting of base entities.
2 Overview
The HP 3PAR Web Services API (WSAPI) makes it possible to manage storage volumes, Common Provisioning Groups (CPGs) and Virtual Logical Unit Numbers (VLUNs) through a series of HTTP or HTTPS requests. NOTE: For security reasons, HTTPS is the preferred choice and is used by default. Throughout this document, HTTP is used to refer to both. The behavior is the same using both protocols. Clients make HTTP requests to the server and receive HTTP replies. When input is provided, such as with the HTTP POST method, or when output is returned, the body of the messages are coded using JSON. The message body will be ignored for GET and DELETE operations. The WSAPI enables programmatic management of HP 3PAR storage servers. The clients access Web services at specified HTTPS locations that control the following volume management tasks: Creating and deleting volumes Creating snapshot volumes Querying all volumes Creating and deleting Common Provisioning Groups (CPGs) Querying all CPGs Creating and deleting VLUNs Querying all VLUNs
Tasks can be automated by developing a WSAPI client. Because the API is more formally defined, using it is preferable to scripts that use the HP 3PAR CLI, since those scripts will need to process CLI-generated text.
Overview
Client Headers
Client header information is required only when the client request has a message body. In these instances, the client must provide the HTTP Content-Type specifying application/json and the optional charset parameter. For example: application/json; charset=UTF-8 The HTTP requests that clients make to the API server include HTTP headers. The following table shows the required and optional HTTP headers. Optional headers, when present, must be one of the values listed in the Values column: Table 1 Headers Supported by the HP 3PAR Web Services API for Requests
Header Accept Description The response format the client can accept. Values One of the following: application/* application/json application/json* Accept-Language The response language the client can accept. One of the following: * en en* Content-Length The length of the content in bytes. The format of the body. Number of bytes Yes, for requests with a message body. Yes, for requests with a message body. Yes, except for a request to create credentials. No Required No
Content-Type
application/json
Examples
Querying CPGs When querying the CPGs, the client sends the following: GET /api/v1/cpgs HTTP/1.1 Accept: application/json Accept-Language: en X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50 Creating CPGs When creating a CPG, the client sends the following: POST /api/v1/cpgs HTTP/1.1 X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50 Accept: application/json Content-Type: application/json Content-Length: 27 { "name" : "t887-cpg" }
Server Headers
Table 2 HTTP headers Included by the Web Services API in Responses
HTTP Header Server Cache-Control Value HP3PAR-WSAPI no-cache Description The HP 3PAR Web Services API Server. Disables caching by mechanisms between the Web Services API server software and client (HTTP RFC 2616), for HTTP/1.0 and 1.1. Disables caching by mechanisms between the Web Services API server software and client (HTTP RFC 2616), for HTTP/1.0 and 1.1 Included when the message body, which will be in JSON format, is nonempty. The path portion of the URI of a newly created object, such as: /api/v1/volumes/foo Encoding is UTF-8 and percent encoded per RFC 3986. The date and time at which the message was originated, per RFC 2616.
Pragma
no-cache
Content-Type Location
Date
GET
The GET method retrieves information identified by the Request-URI.
10
Overview
POST
The POST method requests an object described by the body of the request be created in the collection identified by the URI.
DELETE
The DELETE method requests that the server deletes the resource identified by the Request-URI.
1 1
3 System Access
This chapter discusses the use of session keys with the WSAPI. Session keys enable access to the HTTP methods for a single session.
Creating Credentials
In order to use the Web Services, you must create a session key by providing a username and password. The username and password are the same that you would use to access the HP 3PAR storage server through the Command Line Interface (CLI) or the Management Console (MC). The authorization carries the same user permissions for the WSAPI as for the CLI/MC, in that you have permission to perform the same operations through the API (where available) as you would with the CLI or MC. 1. Create a session key using the HTTP POST method with a URL of the following format: https://<Storage System>:8080/api/v1/credentials 2. The message body of the request is a JavaScript Object Notation (JSON) object with the following members:
Member user password JSON type string string Value Username User's password
NOTE:
For error output for this and other conditions, see Status and Error Codes (page 14).
12
System Access
https://storsys1.example.com:8080/api/v1/credentials 2. The system returns the key in the JSON content of the response: {"key":"1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50"}
To delete a session key, send a request with the HTTP DELETE method and the URI: https://<Storage System>:8080/api/v1/credentials/<session key> NOTE: The <session key> is the key that is returned in the process of creating a session key. For more information, see Creating Credentials (page 12).
2.
A successful session key deletion returns status code 200 OK. There is no message body. NOTE: An error condition returns an error object as a message body.
Example
An example of deleting credentials using cURL is: curl -X DELETE -H "Accept: application/json" https://storsys1.example.com:8080 /api/v1/credentials/1-c86aedb2e7e98b41-b06d2d50
Success
On success, a JSON object is returned that describes the interface version provided by the API server, as described in the following table:
member major minor build JSON type number number number description The version major number. The version minor number. A build number not meant to be interpreted by clients, but useful for identifying specific builds of versions for defect reports or support requests.
13
When an operation fails, one of several HTTP status codes is returned. Also, the message body contains a JSON object with information specific to the HP 3PAR WSAPI. The JSON object contains the members code, desc, and, when relevant, ref. The code member is a number and the rest are strings. The JSON object contains the following members:
Codes Listing
For applications that change behavior based on errors, only the code member should be relied on. For ease of reading documentation, a symbol is defined for each numeric code, but the symbol is not part of the API. The numeric value is the contract between client and server. The codes are described in the following table: Table 3 API General Error Codes Provided by the code Member
API error code 1 2 3 4 5 6 7 8 9 API error symbol INT_SERV_ERR Description HTTP code
An internal error has occurred in 500 Internal the server. Server Error An SSL protocol violation has occurred. 400 Bad Request
The client has not sent a complete 400 Bad Request request. The client has sent a request that 413 Request is too long. Entity Too Large The username or password is invalid. The client request has an invalid session key. 403 Forbidden 403 Forbidden
The client did not send or receive 408 Request in time. Timeout The client request has an unsupported HTTP method. 505 HTTP Version Not Supported
UNSUP_HTTP
UNSUP_OP
The resource does not support the 501 Not method. Implemented
14
Table 3 API General Error Codes Provided by the code Member (continued)
API error code 1 1 12 13 14 15 16 17 18 19 21 22 23 24 API error symbol URI_RES_NOT_FOUND INV_INPUT PERM_DENIED EXISTENT_CPG NON_EXISTENT_CPG EXISTENT_HOST NON_EXISTENT_HOST EXISTENT_LUN NON_EXISTENT_VLUN BAD_PORT_TYPE EXISTENT_VOL NON_EXISTENT_VOL NO_SPACE Description The resource of the request does not exist. The client request contains an invalid value. Permission denied, insufficient privileges. The CPG already exists. The CPG does not exist. The host already exists. The host does not exist. The VLUN already exists. The VLUN does not exist. Attempt to create VLUN with invalid port type. The storage volume already exists. The storage volume does not exist. Not enough space is available for the operation. This varies based on the following circumstances: In volume creation, when the CPG contains insufficient space for the specified volume size. In CPG creation, when the storage system's hardware configuration does not support the requested LD layout. In CPG creation, when the chunklets that are required for the requested LD layout are in the process of being cleaned. 25 27 28 29 31 32 33 HAS_RO_CHILD RETAINED TOO_LARGE OTHER SVC_UNAVAIL The volume has a read-only child. 409 Conflict Volume retention time has not expired. The client request contains a value that is too large. A more specific error could not be determined. 409 Conflict 400 Bad Request 400 Bad Request HTTP code 404 Not Found 400 Bad Request 403 Forbidden 409 Conflict 404 Not Found 409 Conflict 404 Not Found 409 Conflict 404 Not Found 400 Bad Request 409 Conflict 404 Not Found 400 Bad Request
The server has reached its 503 Service maximum number of connections. Unavailable The Virtual Volume (VV) has a child VV2. The VV has no snapshot CPG configured. 409 Conflict 409 Conflict
HAS_CHILD NO_SNAP_CPG
15
Table 3 API General Error Codes Provided by the code Member (continued)
API error code 34 35 API error symbol IN_USE UNSUP_REPRESENTATION Description The resource is in use. The representation specified in client's Accept header is not supported. HTTP code 409 Conflict 406 Not Acceptable
36
UNSUP_LANGUAGE
The language specified in client's 406 Not Accept-Language header is not Acceptable supported. Invalid RAID set size. The domain does not exist. 400 Bad Request 404 Not Found
37 38 39
A JSON input object contains a 400 Bad Request name-value pair where the type of the value differs from what is expected (e.g. a number is found where a string is expected). Ref contains the name of the name-value pair. A JSON input object is missing a 400 Bad Request required name-value pair. Ref contains the expected name. A JSON input object contains 400 Bad Request more than one name-value pair with the same name. Ref contains the name. A JSON input object contains a 400 Bad Request name-value pair with a name that is unrecognized. Ref contains the name. A JSON input object contains a name-value pair with a numeric value that exceeds the expected range. Ref contains the name 400 Bad Request
40
INV_INPUT_MISSING_REQUIRED
41
INV_INPUT_DUP_NAME
42
INV_INPUT_UNREC_NAME
43
INV_INPUT_EXCEEDS_RANGE
44
INV_INPUT_PARAM_CONFLICT
A JSON input object contains a 400 Bad Request name-value pair that cannot be present with another name-value parameter that is present. Ref contains the name A JSON input object contains a name-value pair with an empty string (distinct from a null string) where a string of length greater than zero is required. 400 Bad Request
45
INV_INPUT_EMPTY_STR
46
INV_INPUT_BAD_ENUM_VALUE
A JSON input object contains an 400 Bad Request enum property with a value thats not in the valid range. The allocation warning level is higher than the allocation limit. 400 Bad Request
47 48 49
User space allocation alerts only 400 Bad Request valid with TPVV. The VV retain time is greater than 400 Bad Request the expiration time.
16
Table 3 API General Error Codes Provided by the code Member (continued)
API error code 50 51 API error symbol INV_INPUT_VV_POLICY UNSUP_CONTENT Description HTTP code
An invalid policy (e.g., system or 400 Bad Request caching) is specified for VV. Unsupported content (e.g., as specified in Content-Type HTTP header). 415 Unsupported Media Type
52 53 54 55 56 57 58 59 60
A JSON object was expected but 400 Bad Request another JSON type was found. A pattern in a CPG specifies illegal values. 400 Bad Request
Missing both hostname and port 400 Bad Request position. Incorrect port specification. Invalid URL percent encoding. Invalid input: string length exceeds limit. Invalid time specified. An ID exists. 400 Bad Request 400 Bad Request 400 Bad Request 400 Bad Request 409 Conflict
JSON syntax error. When the 400 Bad Request error is associated with an object member, ref contains the name of the member. Too many levels of nesting in JSON; numbers too large to be represented; length restrictions exceeded. When the error is associated with an object member, ref contains the name of the member. Invalid HTTP header syntax. A request body contains a sequence of characters that is invalid for the supported UTF encodings. A POST request is missing a JSON request body. The request line (first line) of an HTTP request does not meet the form specified for Request-Line in RFC 2616. 400 Bad Request
61
JSON_NOT_SUPPORTED
62 63
INV_HTTP_HEADER INV_UTF
64 65
INV_INPUT_NO_REQ INV_HTTP_REQ
66
INV_URI
The URI is not absolute, contains 400 Bad Request characters not allowed in a URI, contains invalid percent encoding, or, after percent decoding, contains an invalid UTF-8 character sequence. A POST request contains an action member with an invalid value. 400 Bad Request
67
INV_POST_ACTION
17
Table 3 API General Error Codes Provided by the code Member (continued)
API error code 68 API error symbol SYS_SVC_NOT_READY Description HTTP code
Services that the system depends 503 Service on in order to process the Unavailable requested operation are not ready. Input contains one or more illegal 400 Bad Request characters. System is not licensed for this feature or functionality. 403 Forbidden
69 70
INV_INPUT_ILLEGAL_CHAR UNLICENSED_FEATURE
Examples
Examples of desc are: {"code":28,"desc":"client request contains values that are too large} {"code":24,"desc":"insufficient space for requested operation"}
Example
curl -k -H "Accept:application/bogus" -H "X-HP3PAR-WSAPI-SessionKey:9-1786eb905dabf39a4d564e799ea4360c-8053d24f" https://storsys1.example.com:8080 '{"code":35,"desc":"unsupported representation scheme","ref":"Accept"}'
Request
POST /api/v1/credentials HTTP/1.1 Content-Type: application/json Host: storsys1:8080 Content-Length: 44
18 Status and Error Codes
Response
HTTP/1.1 403 Forbidden Date: Tue, Wed, 31 Oct 2012 22:15:52 GMT Server: hp3par-wsapi Content-Type: application/json Connection: close {"code":5,"desc":"invalid user or password"}
19
20
6 Enumerations
Some properties have values from a fixed set of limited values. For example, the state property of a Storage Volume can be one of Normal, Degraded or Failed. When properties like these are present in a JSON object, they are represented numerically. In addition to the values shown in the definition of an enumeration, each enumeration can also have the value of -1, meaning that the API server has encountered a value that it does not recognize and therefore cannot assign a value from the valid set. This usually means a defect in the API server. The values defined for an enumeration start with 1; the value 0 is unused. When using tools that deserialize JSON into a class, this allows an omitted property of enumeration type to be detected, since the member will not be assigned a non-zero value of a property and will retain its default or pre-set value of 0. For enumerations, the symbols used in this document are for convenience in referring to values of enumerations, but are not part of the WSAPI. Integer values representing the symbols appear in JSON objects. Clients can use any symbols with the integers.
21
The properties returned in JSON output objects and the parameters provided in JSON input objects use JSON primitive types with additional restrictions on valid values. Restrictions on values or format are given names that appear in the Type column in the table below. These API types are referenced in the sections below describing JSON input and output. Table 4 API Types
Type 8601 Description JSON string with time in ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD , where TZD is Z or +hh:mm or -hh:mm NOTE: igint32 epoch For more information, see http://www.w3.org/TR/NOTE-datetime
JSON number restricted to a 32-bit signed integer where negative values are ignored by the server, and treated as if not present. The number of seconds since 01/01/1970 GMT. Also known as Unix epoch.
int32 name31
JSON number restricted to a 32-bit signed integer JSON string of 31 or fewer characters, in which the following characters are allowed: a-z A-Z 0-9 . (dot) - (dash) NOTE: Dash (-) is disallowed as the first character. A name of 0 characters is represented in JSON as the empty string . An unset name is represented in JSON as null.
JSON string of 51 1 or fewer characters. JSON number restricted to a 32-bit unsigned number. JSON string of 16 or 32 characters. For port and FC Host it is always 16 characters. Possible characters are: 09 af AF
JSON members suffixed with MiB represent size or space in mebibtyes where 1 MiB = 1,048,576 bytes (2^20 bytes). Members suffixed with MB represent size or space in megabytes where 1MB = 1,000,000 bytes (10^6 bytes). JSON members suffixed with Pct mean percent.
22
LDLayout Object
Table 5 LDLayout object
Member RAIDType setSize HA JSON type number number number API type RAIDType enum igint32 HA enum Description Ignored Values
Specifies the RAID type for the Negative values logical disk. Specifies the set size in the number of chunklets. Negative values
Specifies that the layout must Negative values support the failure of one port pair, one cage, or one magazine. Specifies the chunklet location Negative values preference characteristics. Specifies patterns for candidate disks. None
RAIDType Enumeration
Table 6 RAIDType enumeration
Symbol R0 R1 R5 R6 Value 1 2 3 4 Description RAID level 0 RAID level 1 RAID level 5 RAID level 6
23
HA Enumeration
Table 7 HA Enumeration
Symbol Port cage mag Value 1 2 3 Description Support failure of a port. Support failure of a drive cage. Support failure of a drive magazine.
chunkletPosPref Enumeration
Table 8 chunkletPosPref enumeration
Symbol first last Value 1 2 Description Lowest numbered available chunklets, where transfer rate is the fastest. Highest numbered available chunklets, where transfer rate is the slowest.
diskPatterns Object
Table 9 diskPatterns Object
Symbol nodeList Value string Description Specifies one or more nodes. Nodes are identified by one or more integers. Multiple nodes are separated with a single comma (1,2,3). A range of nodes is separated with a hyphen (07). The primary path of the disks must be on the specified node number. Ignored values Null
slotList
string
Specifies one or more PCI slots. Slots are Null identified by one or more integers. Multiple slots are separated with a single comma (1,2,3). A range of slots is separated with a hyphen (07). The primary path of the disks must be on the specified PCI slot number(s). Specifies one or more ports. Ports are identified Null by one or more integers. Multiple ports are separated with a single comma (1,2,3). A range of ports is separated with a hyphen (04). The primary path of the disks must be on the specified port number(s). Specifies one or more drive cages. Drive cages Null are identified by one or more integers. Multiple drive cages are separated with a single comma (1,2,3). A range of drive cages is separated with a hyphen (03). The specified drive cage(s) must contain disks. Specifies one or more drive magazines. Drive Null magazines are identified by one or more integers. Multiple drive magazines are separated with a single comma (1,2,3). A range of drive magazines is separated with a hyphen (07). The specified magazine(s) must contain disks. Specifies one or more disk positions within a Null drive magazine. Disk positions are identified by one or more integers. Multiple disk positions
portList
string
cageList
string
magList
string
diskPosList
string
24
RPM
number
diskType Enumeration
Table 10 diskType Enumeration
Symbol FC NL SSD Value 1 2 3 Description Fibre Channel Near Line SSD
25
Growth Objects
Table 12 SAGrowth and SDGrowth Objects
Member warningMiB limitMiB incrementMiB LDLayout JSON type number number number object API type uint32 uint32 uint32 LDLayout object Description Threshold of used logical disk space, when exceeded, results in a warning alert. The auto-grow operation is limited to the specified storage amount that sets the growth limit. The growth increment, the amount of logical disk storage created on each auto-grow operation. Logical disk types to be used for this CPG. See LDLayout object for member details.
state Enumeration
Table 13 state Enumeration
Symbol normal degraded failed Value 1 2 3 Description The CPG is operating normally. The CPG is in a degraded state. The CPG is operating abnormally.
Create a CPG
This topic describes how to create a CPG. You create a CPG with the HTTP POST method to the following URI: https://<Storage System>:8080/api/v1/cpgs NOTE: Any user with Super or Edit role, or any role granted with the cpg_create right can perform this operation.
26
Specifies the growth Negative values increment, the amount of logical disk storage created on each auto-grow operation. Specifies that the auto-grow Negative values operation is limited to the specified storage amount that sets the growth limit. Specifies that the threshold of used logical disk space, in MiB, when exceeded results in a warning alert. Specifies the name of the domain in which the object will reside. Specifies Logical Disk types to be used for this CPG. Negative values
growthLimitMiB
number
igint32
usedLDWarningAlertMiB number
igint32
domain
string
name31
Null
LDLayout
object
LDLayout object
None
Responses
Success
A successful operation returns status code 201 Created. There is no message body. On successful creation of the CPG, the Location response header contains the URI for the newly created CPG in the following format: /api/v1/cpgs/<cpg name>
Error Codes
If there is an error condition, the system returns one of the following error codes, or a general error code listed in API General Error Codes Provided by the code Member (page 14):
API error NON_EXISTENT_DOMAIN EXISTENT_CPG BAD_CPG_PATTERN INV_SET_SIZE HTTP code 404 Not Found 409 Conflict 400 Bad Request 400 Bad Request Description Domain doesnt exist CPG already exists A pattern in a CPG specifies illegal values Invalid RAID set size
Remove a CPG
A CPG is removed with the HTTP DELETE method to the URI: https://<Storage System>:8080/api/v1/<cpg name>
Remove a CPG
27
Responses
Success
Status code 200 OK is returned with no message body.
Errors
API error NON_EXISTENT_CPG IN_USE HTTP code 404 Not Found 408 Conflict Description CPG not found The CPG cannot be removed because it is in use by a volume
number number object object object object object number array of numbers
uint32 uint32 UsrUsage object SAUsage object SDUsage object SAGrowth object SDGrowth object state enum array of DetailedState enum
28
Responses
Success
On success, status code 200: OK is returned.
29
Queries for storage volume information are created with the HTTP GET method on a URI, with no message body. The syntax is as follows: https://<Storage System>:8080/api/v1/volumes Unless an error occurs, the response includes a message body with JSON objects total and members. The object members will contain an array of zero or more JSON objects, shown below as the Output object. The total is the number of objects in the members array.
tpvv
3 4 5
30
31
space Objects
The volume space is specified by the following three sub-objects, each of which uses the same members: adminSpace snapshotSpace userSpace
The members are listed in the following table: Table 22 Members of the JSON Volume Space Objects adminSpace
Member reservedMiB rawReservedMiB usedMiB freeMiB JSON type number number number number API Type uint32 uint32 uint32 uint32 Description Reserved space in MiB Raw reserved space in MiB Used space in MiB Free space in MiB
32
When creating a snapshot volume, the message body is a JSON object with two members, action and parameters. The action member is a string with the value "createSnapshot". The parameters member is a JSON object with members described in Create Snapshot Volumes (page 35). NOTE: Any user with Super or Edit role, or any role granted with the volumes_create right can perform this operation.
Specifies a VV name up None (Required) to 31 characters in length. Specifies the name of the None (Required) CPG from which the volume user space will be allocated. Specifies the size for the None (Required) volume in MiB. The volume size is rounded up to the next multiple of 256 MiB. Specifies the ID of the volume. If not specified, the next available ID is chosen. Negative values
cpg
string
name31
sizeMiB
number
uint32
id
number
igint32
comment
string
print51 1
Specifies any additional None information up to 51 1 characters for the volume. Specifies virtual volume policies. None except caching and system which are ignored if false.
policies
object
Policies object
snapCPG
string
name31
Specifies the name of the None CPG from which the snapshot space will be allocated.
33
Member ssSpcAllocWarningPct
Description
Ignored values
Enables a snapshot Negative values. space allocation warning. A warning alert is generated when the reserved snapshot space of the virtual volume exceeds the indicated percentage of the virtual volume size. Sets a snapshot space Negative values allocation limit. The snapshot space of the virtual volume is prevented from growing beyond the indicated percentage of the virtual volume size. true: Create TPVV false: (default) Create FPVV None
ssSpcAllocLimitPct
number
igint32
tpvv
Boolean
Boolean
usrSpcAllocWarningPct
number
igint32
This option enables user Negative values space allocation warning. It specifies that a warning alert is generated when the reserved user space of the TPVV exceeds the specified percentage of the virtual volume size. this option sets the user Negative values space allocation limit. The user space of the TPVV is prevented from growing beyond the indicated percentage of the virtual volume size. After this size is reached, any new writes to the virtual volume will fail. Specifies the relative Negative values time from the current time that the value will expire. Value is a positive integer with a range of 1 - 43,800 hours (1825 days). Specifies the amount of Negative values time relative to the current time that the volume will be retained. Value is a positive integer with a range of 1 - 43,800 hours (1825 days).
usrSpcAllocLimitPct
number
igint32
expirationHours
number
igint32
retentionHours
number
igint32
34
Responses
Success A successful operation returns status code 200 OK. There is no message body. On successful creation of the volume, the Location response header, contains the URI for the newly created volume in the following format: /api/v1/volumes/<volume name> Error Codes An error condition returns one of the following:
API error code EXISTENT_SV TOO_LARGE status code 409 Conflict 400 Bad Request Description The volume already exists Volume size above architectural limit
comment readOnly
string Boolean
print51 1 Boolean
None None
retentionHours number
igint32
Negative values
35
Responses
Success Response
A successful removal returns the following code: status code 200: OK
Error Codes
An error returns one of the following:
API error code status code Description The volume does not exist Volume retention time has not expired Volume has read-only child
NON_EXISTENT_VOL 404 Not Found RETAINED HAS_RO_CHILD 403 Forbidden 403 Forbidden
baseId
number
uint32
readOnly
Boolean
Boolean
36
ssSpcAllocLimitPct
number
igint32
usrSpcAllocWarningPct
number
igint32
38
VLUNtype Enumeration
This component enumerates the types of VLUNs assigned in the system. Table 25 Enumeration of VLUN Types.
Value 1 2 3 4 5 Description Empty Port Host. Matched set Host set
39
Create a VLUN
The following section describes the HTTP request and response parameters for creating a VLUN template. No URI parameters are supported for this operation. NOTE: Any user with Super, Edit role or any role granted with the vlun_create right can perform this operation.
URI
A VLUN is created with the HTTP POST method to the URI: https://<Storage System>:8080/api/v1/vluns
Request Body
The following JSON members are sent in the request body, for specifying the parameters for creating a VLUN template.
Member volumeName lun hostname portPos JSON type String Number String Object API Type name31 igint32 name31 portPos Description Name of the volume to be exported LUN id Ignored Values None (required) None (required)
Name of the host which the None* (optional) volume is to be exported. System port of VLUN None* (optional) exported to. It includes node number, slot number, and card port number A VLUN change None* (optional) notification (VCN) not be issued after export (-novcn). Default: False. Existing lower priority VLUNs will be overridden (-ovrd). Use only if hostname member exists. Default: False. None* (optional)
noVcn
Boolean
Boolean
overrideLowerPriority Boolean
Boolean
When creating a VLUN, the volumeName and lun members are required. Either hostname or portPos (or both in the case of matched sets) is also required. The noVcn and overrideLowerPriority members are optional.
40
Return Status
With a successful VLUN creation, status code 201 Created is returned and there is no message body. On successful creation of the VLUN, the Location response header contains the URI for the newly created VLUN in the following format: /api/v1/vluns/<volumeName>,<lun>,<hostname>,[<port>] The volumeName is the volume that the newly created VLUN exports. The hostname or port information or both (depending on the VLUN type) for the newly created VLUN. The port information will not be displayed for host type VLUN.
BAD_PORT_TYPE EXISTENT_LUN
INV_INPUT_PORT_SPECIFICATION 400 Bad Request INV_INPUT_PARAM_CONFLICT 400 Bad Request 400 Bad Request
TOO_LARGE
Response Body
On success, there is no content in the response body for this operation. On failure, the error code and API-specific error information is sent.
Example
The following example creates a matched VLUN type template for test_vv02 volume.
HTTP Request
POST /api/v1/vluns HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50 { "volumeName":"test_vv02", "lun":252, "hostname":"mysystem", "portPos":{
Create a VLUN 41
HTTP Response
HTTP/1.1 201 Created Date: Mon, 16 Apr 2012 06:44:26 GMT Server: hp3par-wsapi Cache-Control: no-cache Pragma: no-cache Location: /api/v1/vluns/test_vv02,252,mysystem,2:2:4
Remove a VLUN
The following section describes the HTTP request and response for removing a virtual volumes SCSI LUN export definition from the system. The VLUN definition is removed with the HTTP Delete method to the URI: https://<Storage System>:8080/api/v1/vluns/<volumeName>,<lun>, <hostname>[,<port>][?<query>] NOTE: Any user with Super, Edit role or any role granted with the vlun_remove right can perform this operation.
URI Parameters
The following parameters are sent in the URI for the delete operation:
URI Parameter* volumeName lun hostname port Description Name of the volume to be exported LUN Ignored values None (required) None (required)
Name of the host which the volume is exported. None (required if volume is exported to host, or For VLUN of port type, the value is empty. both host and port) Specifies the system port of the VLUN export. It None (required if volume is exported to port, or includes the system node number, PCI bus slot both host and port) number, and card port number on the FC card in the format: <node>:<slot>:<port>
42
Responses
Success
A successful removal returns status code 200: OK with no message body.
Error Codes
An error state returns one of the following:
API error Status code Description Incomplete VLUN info. Missing volumeName or lun, or both hostname and port. NON_EXISTENT_HOST NON_EXISTENT_VLUN NON_EXISTENT_VOLUME 404 Not Found 404 Not Found 404 Not Found Specified hostname not found Incorrect LUN or volumeName Specified volume name not found Specified port is invalid. The LUN specified exceeds expected range.
Example
In the following example VLUNs with LUN 252, exported to storsys1 is deleted. The optional port information is also sent because the VLUN is of matched type.
HTTP Request
DELETE /api/v1/vluns/test_vv02,252,mysystem,2:2:4 HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50
HTTP Response
HTTP/1.1 200 OK Date: Mon, 16 Apr 2012 07:16:39 GMT Server: hp3par-wsapi Cache-Control: no-cache Pragma: no-cache Connection: close
Responses
Success
A successful query returns status code 200 OK and a response body with the following members:
Query VLUN Information 43
The members object is a JSON array of zero or more JSON objects one for each VLUN on the system. These objects are described in the following table.
Member lun volumeName hostname remoteName JSON type number string string string API type uint32 name31 name31 name31 Description Exported LUN Value Name of exported Virtual Volume name Hostname the VLUN is exported to host WWN, or iSCSI name, or SAS addr; depends on port type System port of VLUN exported to. It includes node number, slot number, and cardPort number VLUN type
portPos
object
portPos object For more information, see JSON Components of the portPos Object. (page 39) VLUNtype enum For more information, see Enumeration of VLUN Types. (page 39) WWN multipathing enum For more information see Enumeration of multipathing Configurations for VLUNs (page 39) failedPathPol enum For more information, see Enumeration of failedPathPol Configurations for VLUNs (page 40) uint32
type
number
volumeWWN multipathing
string number
failedPathPol
number
failedPathInterval
number
Monitoring interval in seconds after which the host checks for failed paths The device name for this VLUN on the host Specified if the VLUN is an active VLUN or a VLUN template. , . true for active VLUN false for VLUN template
hostDeviceName active
string Boolean
name31 Boolean
44
Example
The example lists all the VLUN templates or active VLUNs, including all active and template VLUNs on the storage system:
HTTP Request
GET /api/v1/vluns HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50
HTTP Response
{"total": 2, "members": [ { "lun": 1, "volumeName": "vol1.0", "hostname": "host", "remoteName": "10000000C978500E", "portPos": { "node": 0, "slot": 4, "cardPort": 1 }, "type": 4, "volumeWWN": "60002AC0000000000000020D0000017D", "multipathing": 1, "failedPathPol": 1, "failedPathInterval": 0, "active": true }, { "lun": 10, "volumeName": "vol1.0", "portPos": { "node": 0, "slot": 4, "cardPort": 1 }, "type": 4, "volumeWWN": "60002AC0000000000000020D0000017D", "multipathing": 1, "failedPathPol": 1,
Query VLUN Information 45
46
HP 3PAR documentation
For information about: Supported hardware and software platforms See: The Single Point of Connectivity Knowledge for HP Storage Products (SPOCK) website: http://www.hp.com/storage/spock Locating HP 3PAR documents The HP 3PAR StoreServ Storage site: http://www.hp.com/go/3par To access HP 3PAR documents, click the Support link for your product. HP 3PAR storage system software Storage concepts and terminology HP 3PAR StoreServ Storage Concepts Guide
Using the HP 3PAR Management Console (GUI) to configure HP 3PAR Management Console User's Guide and administer HP 3PAR storage systems Using the HP 3PAR CLI to configure and administer storage systems CLI commands Analyzing system performance Installing and maintaining the Host Explorer agent in order to manage host configuration and connectivity information HP 3PAR Command Line Interface Administrators Manual HP 3PAR Command Line Interface Reference HP 3PAR System Reporter Software User's Guide HP 3PAR Host Explorer Users Guide
Creating applications compliant with the Common Information HP 3PAR CIM API Programming Reference Model (CIM) to manage HP 3PAR storage systems
Contacting HP
47
See:
Migrating data from one HP 3PAR storage system to another HP 3PAR-to-3PAR Storage Peer Motion Guide Configuring the Secure Service Custodian server in order to monitor and control HP 3PAR storage systems Using the CLI to configure and manage HP 3PAR Remote Copy Updating HP 3PAR operating systems Identifying storage system components, troubleshooting information, and detailed alert information Installing, configuring, and maintaining the HP 3PAR Policy Server HP 3PAR Secure Service Custodian Configuration Utility Reference HP 3PAR Remote Copy Software Users Guide HP 3PAR Upgrade Pre-Planning Guide HP 3PAR F-Class, T-Class, and StoreServ 10000 Storage Troubleshooting Guide HP 3PAR Policy Server Installation and Setup Guide HP 3PAR Policy Server Administration Guide
48
Hardware specifications, installation considerations, power requirements, networking options, and cabling information for HP 3PAR storage systems HP 3PAR 7200 and 7400 storage systems HP 3PAR 10000 storage systems HP 3PAR StoreServ 7000 Storage Site Planning Manual HP 3PAR StoreServ 10000 Storage Physical Planning Manual HP 3PAR StoreServ 10000 Storage Third-Party Rack Physical Planning Manual Installing and maintaining HP 3PAR 7200 and 7400 storage systems Installing 7200 and 7400 storage systems and initializing the Service Processor HP 3PAR StoreServ 7000 Storage Installation Guide HP 3PAR StoreServ 7000 Storage SmartStart Software Users Guide HP 3PAR StoreServ 7000 Storage Service Guide HP 3PAR StoreServ 7000 Storage Troubleshooting Guide HP 3PAR Service Processor Software User Guide HP 3PAR Service Processor Onsite Customer Care (SPOCC) User's Guide HP 3PAR host application solutions Backing up Oracle databases and using backups for disaster HP 3PAR Recovery Manager Software for Oracle User's recovery Guide Backing up Exchange databases and using backups for disaster recovery Backing up SQL databases and using backups for disaster recovery Backing up VMware databases and using backups for disaster recovery HP 3PAR Recovery Manager Software for Microsoft Exchange 2007 and 2010 User's Guide HP 3PAR Recovery Manager Software for Microsoft SQL Server Users Guide HP 3PAR Management Plug-in and Recovery Manager Software for VMware vSphere User's Guide
Maintaining, servicing, and upgrading 7200 and 7400 storage systems Troubleshooting 7200 and 7400 storage systems Maintaining the Service Processor
Installing and using the HP 3PAR VSS (Volume Shadow Copy HP 3PAR VSS Provider Software for Microsoft Windows Service) Provider software for Microsoft Windows User's Guide Best practices for setting up the Storage Replication Adapter HP 3PAR Storage Replication Adapter for VMware for VMware vCenter vCenter Site Recovery Manager Implementation Guide Troubleshooting the Storage Replication Adapter for VMware HP 3PAR Storage Replication Adapter for VMware vCenter Site Recovery Manager vCenter Site Recovery Manager Troubleshooting Guide Installing and using vSphere Storage APIs for Array Integration (VAAI) plug-in software for VMware vSphere HP 3PAR VAAI Plug-in Software for VMware vSphere User's Guide
HP 3PAR documentation
49
Typographic conventions
Table 29 Document conventions
Convention Bold text Element Keys that you press Text you typed into a GUI element, such as a text box GUI elements that you click or select, such as menu items, buttons, and so on Monospace text File and directory names System output Code Commands, their arguments, and argument values <Monospace text in angle brackets> Code variables Command variables Bold monospace text Commands you enter into a command line interface System output emphasized for scannability
WARNING! Indicates that failure to follow directions could result in bodily harm or death, or in irreversible damage to data or to the operating system. CAUTION: NOTE: Indicates that failure to follow directions could result in damage to equipment or data.
Required
Indicates that a procedure must be followed as directed in order to achieve a functional and supported implementation based on testing at HP.
50
12 Documentation feedback
HP is committed to providing documentation that meets your needs. To help us improve the documentation, send any errors, suggestions, or comments to Documentation Feedback (docsfeedback@hp.com). Include the document title and part number, version number, or the URL when submitting your feedback.
51