Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Operations performed on QoS groups by using REST API requests that include simple in the request line

The following is an overview of REST API requests that include simple in the request line, and describes operations performed on QoS groups by using REST API requests that include simple in the request line. These operations can be performed for VSP 5000 series storage systems.

Overview of REST API requests that include simple in the request line

Review general information about API requests, how to specify managed resources to use REST API requests that include simple in the request line, the information needed to execute an API request, and the information that is output when an API request is executed.

Specifying resources to manage (URL)

For REST API requests that include simple in the request line, the resources to manage must be specified in URL format.

To specify resources to manage, specify the URL in the following format:

protocol://host:port/application/version/domain
  • protocol

    Specify https or http.

    We recommend specifying 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.

Note

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.

Resources for the object type performances:

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

Resources for the object type qos-groups:

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.

Note

A maximum of 16 requests can be executed at the same time.

Specifying an object ID

An object ID is used to uniquely identify a resource.

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
Note

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

Specify operations to perform on resources in the HTTP method.

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

Request headers are request messages sent from REST API clients to the REST API server.

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 response headers are response messages from the REST API server to REST API clients.

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.

  • Default:

    • Authentication by using a session

      Session realm="Block storage"

HTTP status codes

REST API requests that include simple in the request line use the following standard HTTP status codes to indicate the processing results.

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

JSON format is used for getting the results of resource information (GET).

The supported character encoding is UTF-8.

Request format
  • 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.
Response format
  • 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

If the GET method is used to obtain an object, query parameters can be specified to filter the execution results based on specific conditions.

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&parameter=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

This section describes the data types that can be specified by using REST API requests that include simple in the request line.

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

After an API request is issued, a response is returned based on the API processing method, the API processing type, and the execution result.

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

Data object is an object for returning the object list.

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 describes the error object that is returned together with an HTTP status code if an error occurs during the processing of a request.

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:

  • SSB1 code
  • SSB2 code

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

Gain an understanding about operations on QoS groups performed by using REST API requests that include simple in the request line.
ImportantFor details on common specifications (how to specify resources, the information required to run an API request, and information that can be checked by running the API request) for running REST API requests that include simple in the request line, see the overview of REST API requests in the appendix.

Getting a list of QoS groups

This request gets a list of QoS group information.
Note

This API request can be used when the storage system is VSP 5000 series.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/simple/v1/objects/qos-groups
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • 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.

Status codes

For details on the status codes of the API, see the description on HTTP status codes.

Coding example
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 request gets information about QoS group.
Note

This API request can be used when the storage system is VSP 5000 series.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/simple/v1/objects/qos-groups/object-ID
Request message
  • 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.

Response message
  • 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.

Status codes

For details on the status codes of the API, see the description on HTTP status codes.

Coding example
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

The following request gets performance information about a QoS group for the specified QoS group ID.
Note

This API request can be used when the storage system is VSP 5000 series.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/simple/v1/objects/performances/qos-groups/object-ID
Request message
  • 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.

Response message
  • 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)

Status codes

For details on the status codes of the API, see the description on HTTP status codes.

Coding example
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