Operations performed on QoS groups by using REST API requests that include simple in the request line
Overview of REST API requests that include simple in the request line
Specifying resources to manage (URL)
To specify resources to manage, specify the URL in the following format:
protocol://host:port/application/version/domain
- protocol
Specify https or http.
Specify a valid protocol in the storage system settings.
We recommend using https for security.
- host
Specify the IP address of the SVP or a host name that can be resolved.
- port
Specify the port number to use for communication.
The default port number is 443 (for SSL communication) and 80 (for non-SSL communication). The port number can be omitted if the default port number is used for communications.
- application
Specify ConfigurationManager/simple.
In this document, protocol://host:port/ConfigurationManager is indicated as a base URL.
- version
Specify the version of the REST API request that includes simple in the request line. Currently, only v1 can be specified.
- domain
Specify the domain. Currently only objects can be specified.
The URL formats are as follows.
Under objects, specify the type of object on which operations will be performed:
- performances
- qos-groups
The following tables describe the URL formats supported for object type.
URL formats (excluding the base URL) |
HTTP method |
Processing method |
Operations |
/simple/v1/objects/performances/qos-groups/object-ID |
GET |
Synchronous |
Getting performance information for a specific QoS group |
URL formats (excluding the base URL) |
HTTP method |
Processing method |
Operations |
/simple/v1/objects/qos-groups |
GET |
Synchronous |
Getting a list of QoS groups |
/simple/v1/objects/qos-groups/object-ID |
GET |
Synchronous |
Getting information for a specific QoS group |
REST API requests that include simple in the request line have the following processing methods:
- Synchronous processing
The processing results are returned as the response.
A maximum of 16 requests can be executed at the same time.
Specifying an object ID
An object ID is used when specifying a specific resource in a URL. To specify an object ID, execute the GET operation and then obtain the object ID from the execution results.
Example: If the object ID of a QoS group is 10
qos-groups/10
When the GET operation is performed to obtain an object ID, the REST API server sometimes returns a value encoded according to RFC 3986, as the value of the attribute obtained by the GET operation. To use the object ID obtained by performing the GET operation in a request of another operation, use the object ID without decoding it.
Supported HTTP methods
REST API requests that include simple in the request line support the following HTTP methods.
HTTP method |
Description |
GET |
This method gets object information. Alternatively, this method gets a list of objects. When information about multiple objects is obtained, the information is not sorted by object ID . For this reason, filter the information to obtain by specifying query parameters. Alternatively, if you know the object IDs of the objects for which you want to get information, run the API request for obtaining information about specific objects. |
Request headers
The following table lists the request headers supported by REST API requests that include simple in the request line.
Header |
Category |
Description |
Accept |
Optional |
Specifies the media type of the response. Specifiable value: */* (json) Default value: */* (json) |
Accept-Language |
Optional |
Specifies the language of the messages received by the client. Specify ja to set the language to Japanese. If any language other than Japanese is specified, or if this header is omitted, the language will be set to English (en). |
Content-Type |
Optional |
Specifies the media type of the request body. Specifiable value: application/json Default value: application/json |
Content-Length |
Optional |
Specifies the size of the request body. You can specify the Content-Length header when specifying a request body. This header is automatically assigned depending on the specifications of the client software. Specifiable value: Specify the header, in bytes. Default value: None. |
Authorization |
Required |
Specifies the authorization method and authorization credentials. Session token Specify a token that was obtained when the session was generated. For details about how to use the API request for generating sessions, see the description of the following API request.
POST base-URL/v1/objects/sessions |
If a header other than the above is specified, the specified header is ignored.
Response headers
The following table describes the response headers returned by the REST API server.
Header |
Description |
Content-Type |
Indicates the media type of the response data. Default: application/json;charset=UTF-8 |
Content-Length |
Indicates the size of the response data. If the size of the response data is large, instead of this header, Transfer-Encoding: chunked is returned, indicating that the response data has been divided and then transferred. |
Transfer-Encoding |
Indicates the encoding format used when the response data was transferred. When a large amount of response data is divided and then transferred, chunked is returned. |
Retry-After |
Indicates the recommended wait time (in seconds) before the request can be retried. When the HTTP status code 503 is returned, this header is sometimes set. |
WWW-Authenticate |
Indicates that authentication is required when the HTTP status code 401 is returned.
|
HTTP status codes
HTTP status codes |
Description |
200 |
OK The request was processed correctly. |
400 |
Bad Request The request header, the query parameter, the object ID, or the request body is invalid. |
401 |
Unauthorized The Authorization header is not specified in the request header. Alternatively, authentication by using the information specified in the Authorization header fails. |
403 |
Forbidden You do not have the permission required to perform the operation. |
404 |
Not Found The resource specified by the URL could not be found. Alternatively, there are no resources for the specified URL. |
406 |
Not acceptable The media type specified in the Accept header is not supported. |
415 |
Unsupported Media Type The specified media type is not supported. |
500 |
Internal Server Error An internal error occurred on the server. Only the most critical error is returned. |
503 |
Service Unavailable Indicates that the service is temporarily unavailable because it is busy or under maintenance. Only the most critical error is returned. If the response header includes Retry-After, wait for the period of time indicated by the return value (the recommended wait time, given in seconds), and then run the request again. |
504 |
Gateway Timeout No response was received from the device in the allotted time. Only the most critical error is returned. |
Request and response formats
The supported character encoding is UTF-8.
- If you specified a null character for a string-type attribute, the value of the attribute is assumed to be null.
- If you specified a null character for an attribute whose type is not string, the attribute is assumed to be unspecified.
- If the API processing succeeds, a response is returned in JSON format.
- If the processing fails, depending on the contents of the error, a response
in HTML format, instead of JSON format, might be returned.
To resolve the error based on the HTTP status code in the program, check the value of Content-Type in the response header.
Query parameters
Query parameters can be specified at the end of the URL in the following format:
?parameter=value
To specify multiple parameters, concatenate them by using ampersands (&). Multiple parameters are specified in the following example:
?parameter=value¶meter=value...
For details on parameters that can be specified for queries, see the section explaining the specific API request.
Parameters are case-sensitive. If you specify a parameter other than those that can be specified for each API, the invalid parameter is ignored, and only the valid parameters are used to filter the execution results.
Data type
The following table shows the data types supported by REST API requests that include simple in the request line and the corresponding JSON data types.
Data type |
JSON type |
Description |
boolean |
boolean |
A type that represents true or false. Example: true |
int |
number |
A type that represents a 32-bit signed integer. Example: 100 |
long |
number |
A type that represents a 64-bit signed integer. Example: 1048576 |
string |
string |
A type that represents a character string. Example: "DKR5D-J900SS" |
ISO8601string |
string |
A type that represents time in the ISO 8601 extended format (YYYY-MM-DDThh:mm:ssZ). The only time zone that you can specify is UTC. Example: "2017-09-30T09:27:35Z" |
In addition to the preceding data types, the following JSON data types are also used:
Object type
The character string, in which the attribute and value are connected with a colon (:), is enclosed in { and }. If more than one attribute-value pair exists, the pairs are separated by commas.
Array type
The character string, in which multiple values are separated by commas, is enclosed in [ and ].
Output format
The following table shows the response output formats when the processing of the request is successful.
API processing method |
API processing type |
Status code of the execution result |
Output format |
Synchronous processing |
GET (getting a single object) |
200 |
See the description in the response message for each API function. |
GET (getting multiple objects) |
200 |
Data object |
If the processing of the request fails, an error object is returned as a response.
Data object
The following table shows the data object schema.
Attribute |
Data type |
Description |
data |
array |
Object list |
The following attributes are displayed along with the data object.
Attribute |
Data type |
Description |
count |
int |
Number of objects |
Error object
The following table explains the schema of an error object.
Attribute |
Data type |
Description |
errorSource |
string |
URL where the error occurs |
messageId |
string |
Message ID |
message |
string |
Content of the error message |
cause |
string |
Cause of the error |
solution |
string |
Solution to the error |
errorCode |
string |
Error code from the storage system A value is returned only if an error occurs in the storage system. The error codes are as follows:
Storage system error codes are required for maintenance of the storage system. |
The following is an example of an error object when an error occurs:
{ "errorSource": "/ConfigurationManager/simple/v1/objects/qos-groups/10", "messageId": "KART70006-E", "message": "The specified resource does not exist or is an unmanaged resource. If you are accessing an unmanaged resource, use other management interfaces." }
Operations on QoS groups
Getting a list of QoS groups
This API request can be used when the storage system is VSP 5000 series.
Storage Administrator (View Only)
GET base-URL/simple/v1/objects/qos-groups
Object ID
None.
Query parameters
None.
Body
None.
Body
{ "data": [ { "id": 10, "threshold": { "isUpperIopsEnabled": false, "isUpperTransferRateEnabled": false }, "alertSetting": { "isUpperAlertEnabled": false }, "alertTime": {} }, { "id": 200, "threshold": { "isUpperIopsEnabled": true, "upperIops": 2000, "isUpperTransferRateEnabled": true, "upperTransferRate": 20000 }, "alertSetting": { "isUpperAlertEnabled": true, "upperAlertAllowableTime": 10 }, "alertTime": { "upperAlertTime": "2020-10-21T07:10:17Z" } } ], "count": 2 }
Attribute
Type
Description
id
int
ID of the QoS group
threshold
object
Information about the QoS settings of the QoS group
isUpperIopsEnabled
(boolean)Whether the upper limit on the IOPS is enabled
- true: Enabled
- false: Disabled
upperIops
(int)Upper limit on the IOPS
This information is not output if
isUpperIopsEnabled
is false.isUpperTransferRateEnabled
(boolean)Whether the upper limit on the amount of data that can be transferred is enabled
- true: Enabled
- false: Disabled
upperTransferRate
(int)Upper limit on the amount of data that can be transferred per second (MBps)
This information is not output if
isUpperTransferRateEnabled
is false.
alertSetting
object
Information about the alert settings of the QoS group
isUpperAlertEnabled
(boolean)Whether alerts are output if the IOPS or the amount of data transferred not achieve the upper limit for a continuous period of time
- true: Output
- false: Not output
upperAlertAllowableTime
(int)Amount of time to wait before issuing an alert when an upper limit is exceeded for a continuous period of time (in seconds)
This information is not output if
isUpperAlertEnabled
is false.
alertTime
object
The time# when an alert was issued for the QoS group
upperAlertTime
(ISO8601string)Time when the last alert was issued because the IOPS or the amount of data transferred per second had exceeded the upper limit for a continuous period of time (UTC)
#: If you change the time zone of the storage system, the times displayed for alerts that were issued before the change will be invalid.
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3f9f04ea8bd8f09847fac48d3" -X GET https://192.0.2.100/ConfigurationManager/simple/v1/objects/qos-groups
Getting information for a specific QoS group
This API request can be used when the storage system is VSP 5000 series.
Storage Administrator (View Only)
GET base-URL/simple/v1/objects/qos-groups/object-ID
Object ID
Specify the value of
id
that is obtained when you get information about the QoS group.Attribute
Type
Description
id
int
(Required) ID of the QoS group
Query parameters
Parameter
Type
Description
withVolumeIds
boolean
(Optional) Specify whether to get information about the LDEV numbers that belong to the QoS group.
- true: Obtain the LDEV numbers.
- false: Do not obtain the LDEV numbers.
If this value is omitted, false is assumed.
Body
None.
Body
{ "id": 200, "threshold": { "isUpperIopsEnabled": true, "upperIops": 2000, "isUpperTransferRateEnabled": true, "upperTransferRate": 20000 }, "alertSetting": { "isUpperAlertEnabled": true, "upperAlertAllowableTime": 10 }, "alertTime": { "upperAlertTime": "2020-10-21T07:10:17Z" }, "volumeIds": [ 10000, 10001 ] }
Attribute
Type
Description
id
int
ID of the QoS group
threshold
object
Information about the QoS settings of the QoS group
isUpperIopsEnabled
(boolean)Whether the upper limit on the IOPS is enabled:
- true: Enabled
- false: Disabled
upperIops
(int)Upper limit on the IOPS
This information is not output if
isUpperIopsEnabled
is false.isUpperTransferRateEnabled
(boolean)Whether the upper limit on the amount of data that can be transferred is enabled:
- true: Enabled
- false: Disabled
upperTransferRate
(int)Upper limit on the amount of data that can be transferred per second (MBps)
This information is not output if
isUpperTransferRateEnabled
is false.
alertSetting
object
Information about the alert settings of the QoS group
isUpperAlertEnabled
(boolean)Whether alerts are output if the IOPS or the amount of data transferred not achieve the upper limit for a continuous period of time:
- true: Output
- false: Not output
upperAlertAllowableTime
(int)Amount of time to wait before issuing an alert when an upper limit is exceeded for a continuous period of time (in seconds)
This information is not output if
isUpperAlertEnabled
is false.
alertTime
object
The time# when an alert was issued for the QoS group
upperAlertTime
(ISO8601string)Time when the last alert was issued because the IOPS or the amount of data transferred per second had exceeded the upper limit for a continuous period of time (UTC)
volumeIds
int[]
The LDEV numbers that belong to the QoS group
This attribute is displayed only if you specified true for
withVolumeIds
in the query parameters.#: If you change the time zone of the storage system, the times displayed for alerts that were issued before the change will be invalid.
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/simple/v1/objects/qos-groups/200?withVolumeIds=true
Getting performance information for a specific QoS group
This API request can be used when the storage system is VSP 5000 series.
Storage Administrator (View Only)
GET base-URL/simple/v1/objects/performances/qos-groups/object-ID
Object ID
Specify the value of
id
that is obtained when you get information about the QoS group.Attribute
Type
Description
id
int
(Required) ID of the QoS group
Query parameters
None.
Body
None.
Body
{ "id": 10, "receivedCommands": 0, "transferRateOfReceivedCommands": 0, "iops": 0, "transferRate": 0, "responseTime": 0, "monitorTime": "2020-10-08T05:54:07Z" }
Attribute
Type
Description
id
int
ID of the QoS group
receivedCommands
int
Number of commands received from hosts (IOPS)
transferRateOfReceivedCommands
int
Amount of data transferred by commands received from hosts (KBps)
iops
int
Number of commands processed by the storage system (IOPS)
transferRate
int
Amount of transferred data processed by the storage system (KBps)
responseTime
long
Response time (microseconds)
monitorTime
ISO8601string
Time at which the performance information was obtained (UTC)
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/simple/v1/objects/performances/qos-groups/10