Skip to main content
Hitachi Vantara Knowledge

Common operations in the REST API

You can perform common REST API operations such as change, delete, generate, and get information about jobs and sessions, and register and manage storage system information. You can also manage resource locks.

Getting the version information

The following request gets information about the version of the REST API.
Execution permission

No role is required to run this API request.

Request headers

This API request does not require authorization. Therefore, the Authorization header does not need to be specified.

Request line
GET base-URL/configuration/version
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "productName": "Configuration Manager REST API",
      "apiVersion": "1.31.0"
    }

    Attribute

    Type

    Description

    productName

    string

    Name of the REST API

    apiVersion

    string

    Version of the REST API

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" -X GET https://192.0.2.100:23451/ConfigurationManager/configuration/version

Getting a list of storage systems

The following request gets a list of the storage systems that can be operated from the REST API. You can check information about storage systems, such as the storage device ID and the serial number of the storage system.
Execution permission

No role is required to run this API request.

Request headers

This API request does not require authorization. Therefore, the Authorization header does not need to be specified.

Request line

GET base-URL/v1/objects/storages
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "data": [
        {
          "storageDeviceId": "834000123456",
          "model": "VSP G400",
          "serialNumber": 123456,
          "svpIp": "192.0.2.100"
        },
        {
          "storageDeviceId": "834000123457",
          "model": "VSP G600",
          "serialNumber": 123457,
          "svpIp": "192.0.2.103"
        },
        {
          "storageDeviceId" : "886000123458",
          "model" : "VSP G900",
          "serialNumber" : 123458,
          "ctl1Ip" : "192.0.2.104",
          "ctl2Ip" : "192.0.2.105",
          "targetCtl" : "CTL1"
        }
      ]
    }
    

    For VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900:

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID

    model

    string

    Model name of the storage system

    serialNumber

    int

    Serial number of the storage system

    ctl1Ip

    string

    IP address of controller 1 of the storage system

    ctl2Ip

    string

    IP address of controller 2 of the storage system

    targetCtl

    string

    Controller operated by the REST API

    • CTL1: Controller 1
    • CTL2: Controller 2

    For VSP 5000 series, VSP G200, G400, G600, G800, VSP G1000, VSP G1500, VSP F400, F600, F800, VSP F1500, Virtual Storage Platform, or Unified Storage VM:

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID

    model

    string

    Model name of the storage system

    serialNumber

    int

    Serial number of the storage system

    svpIp

    string

    IP address of the SVP that manages the storage system

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages

Getting information about a specific storage system

The following request gets information about a storage system by specifying the storage device ID.
Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/storages/storage-device-ID
Request message
  • Object ID

    Specify the storageDeviceId value obtained by getting information about the storage systems.

    Attribute

    Type

    Description

    storageDeviceId

    string

    (Required) Storage device ID

  • Query parameters

    Attribute

    Type

    Filter Condition

    detailInfoType

    string

    (Optional) Type of detailed information to be obtained

    The following values can be specified. To specify multiple values, separate the values by using commas.

    • version

      Additional detailed information about the microcode of the storage system, controller 1, and controller 2 is obtained.

      You cannot specify this attribute if the storage system is Virtual Storage Platform or HUS VM.

    • compressionAcceleration

      Additional information indicating whether the compression accelerator of the capacity saving function (dedupe and compression) can be used is obtained.

  • Body

    None.

Response message
  • Body

    For VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900:

    The following is an example of output for VSP G900.

    {
      "storageDeviceId" : "886000123456",
      "model" : "VSP G900",
      "serialNumber" : 123456,
      "svpIp" : "192.0.2.100",
      "mappWebServerHttpsPort" : 443,
      "rmiPort" : 1099,
      "ctl1Ip" : "192.0.10.10",
      "ctl2Ip" : "192.0.10.11",
      "dkcMicroVersion" : "88-02-00/20",
      "communicationModes" : [ {
        "communicationMode" : "lanConnectionMode"
      } ],
      "isSecure" : true,
      "lanConnectionProtocol" : "DTLS SVP",
      "targetCtl" : "CTL1",
      "usesSvp" : true
    }

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID

    model

    string

    Model name of the storage system

    serialNumber

    int

    Serial number of the storage system

    usesSvp

    boolean

    Whether to link with an SVP

    • true: Link with an SVP
    • false: Do not link with an SVP

    svpIp

    string

    IP address of the SVP

    This attribute is displayed if true is displayed for the usesSvp attribute.

    rmiPort

    int

    The port number to be used for RMI communication between the Configuration Manager REST API server and the storage system

    This attribute is displayed if true is displayed for the usesSvp attribute.

    mappWebServerHttpsPort

    int

    Port number used by the SVP for HTTPS communication

    This attribute is displayed if true is displayed for the usesSvp attribute.

    ctl1Ip

    string

    IP address of controller 1 of the storage system

    ctl2Ip

    string

    IP address of controller 2 of the storage system

    targetCtl

    string

    Controller operated by the REST API

    • CTL1: Controller 1
    • CTL2: Controller 2

    dkcMicroVersion

    string

    Microcode version of the storage system

    communicationModes

    object[]

    Array of communication modes

    For the communication mode between the REST API server and the storage system, the following attributes are output:

    • communicationMode (string)

      Communication mode

      • fcConnectionMode
      • lanConnectionMode

    isSecure

    boolean

    Settings for SSL communication between the REST API server and the storage system

    • true: SSL communication is enabled.

    lanConnectionProtocol

    string

    Encrypted communication mode used for SSL communication between the REST API server and the storage system

    • DTLS SVP
    • SSL TLS

    This attribute is displayed if true is displayed for the usesSvp attribute.

    For VSP 5000 series, VSP G200, G400, G600, G800, VSP G1000, VSP G1500, VSP F400, F600, F800, VSP F1500, Virtual Storage Platform, or Unified Storage VM:

    The following is an example of output for VSP G400.

    {
      "storageDeviceId" : "834000123456",
      "model" : "VSP G400",
      "serialNumber" : 123456,
      "svpIp" : "192.0.2.100",
      "mappWebServerHttpsPort":443,
      "rmiPort" : 1099,
      "ctl1Ip": "192.0.10.10",
      "ctl2Ip": "192.0.10.11",
      "dkcMicroVersion" : "83-02-01/96",
      "communicationModes": [
        {
          "communicationMode": "proxyMode",
          "proxies": [
            {
              "proxyIp": "192.0.2.101",
              "proxyPort": 2010
            },
            {
              "proxyIp": "192.0.2.102",
              "proxyPort": 2011
            }
          ]
        },
        {
          "communicationMode": "lanConnectionMode"
        }
      ],
      "isSecure": false
    }

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID

    model

    string

    Model name of the storage system

    serialNumber

    int

    Serial number of the storage system

    svpIp

    string

    IP address of the SVP

    rmiPort

    int

    The port number to be used for RMI communication between the Configuration Manager REST API server and the storage system

    This port is used by the API function to generate sessions and manage users.

    mappWebServerHttpsPort

    int

    Port number used by the SVP for HTTPS communication

    This port is used when SSL communication is used between the REST API server and the storage system.

    This attribute is displayed for storage systems VSP G200, G400, G600, G800, VSP F400, F600, F800.

    ctl1Ip

    string

    IP address of controller 1 of the storage system

    This attribute is displayed for storage systems VSP G200, G400, G600, G800, VSP F400, F600, F800.

    ctl2Ip

    string

    IP address of controller 2 of the storage system

    This attribute is displayed for storage systems VSP G200, G400, G600, G800, VSP F400, F600, F800.

    dkcMicroVersion

    string

    Microcode version of the storage system

    communicationModes

    object[]

    Array of communication modes

    If this array contains multiple elements, the top element is used first for communications.

    For the communication mode between the REST API server and the storage system, the following attributes are output:

    • communicationMode (string)

      Communication mode

      • proxyMode
      • fcConnectionMode
      • lanConnectionMode
    • proxies (object[])

      Array of relay servers

      The following attributes are output when the communicationMode attribute is proxyMode:

      • proxyIp (string)

        IP address of the relay server

      • proxyPort (int)

        Port number of the relay server

    isSecure

    boolean

    Settings for SSL communication between the REST API server and the storage system:

    • true: SSL communication is enabled.
    • false: SSL communication is disabled.

    lanConnectionProtocol

    string

    Encrypted communication mode used for SSL communication between the REST API server and the storage system

    This attribute is displayed with any of the following values when the value of the isSecure attribute is true:

    • DTLS
    • DTLS SVP
    • SSL TLS

    This attribute is displayed for storage systems VSP G200, G400, G600, G800, VSP F400, F600, F800.

    You can obtain detailed information about the microcode of the storage system by executing the request with version specified for the detailInfoType query parameter.

    {
      "storageDeviceId": "886000123456",
      "model": "VSP G900",
      "serialNumber": 123456,
      "ctl1Ip" : "192.0.10.10",
      "ctl2Ip" : "192.0.10.11",
      "dkcMicroVersion": "88-01-01/82",
      "detailDkcMicroVersion": "88-01-01-60/82",
      "ctl1MicroVersion" : "88-01-01/81",
      "ctl2MicroVersion" : "88-01-01/81",
      "communicationModes": [
        {
          "communicationMode": "lanConnectionMode"
        }
      ],
      "isSecure": true
    }
    

    Attribute

    Type

    Description

    detailDkcMicroVersion

    string

    Microcode version of the storage system

    Model identification information is included.

    ctl1MicroVersion

    string

    GUM version of the controller 1

    This attribute is displayed for storage systems VSP E series, VSP Gx00 models , VSP Fx00 models.

    If a failure has occurred in the GUM of controller 1, this information is not obtained.

    ctl2MicroVersion

    string

    GUM version of the controller 2

    This attribute is displayed for storage systems VSP E series, VSP Gx00 models , VSP Fx00 models.

    If a failure has occurred in the GUM of controller 2, this information is not obtained.

    When you specify compressionAcceleration for the detailInfoType parameter, information indicating whether the compression accelerator can be used is obtained.

    {
      "storageDeviceId": "900000012345",
      "model": "VSP 5600H",
      "serialNumber": 12345,
      "svpIp": "192.0.2.100",
      "rmiPort" : 1099,
      "dkcMicroVersion": "90-08-01/00",
      "isCompressionAccelerationAvailable": true,
      "communicationModes": [
         {
           "communicationMode": "lanConnectionMode"
         }
      ],
        "isSecure": true
    }
    

    Attribute

    Type

    Description

    isCompressionAccelerationAvailable

    boolean

    Whether the capacity saving function (dedupe and compression) that uses a compression accelerator can be used

    • true: Can be used
    • false: Cannot be used

    If both of the following conditions are met, the value of the attribute will be true:

    • The microcode version is a version for which the compression accelerator can be used or a later version.
    • ACLF (hardware that executes the compression accelerator function) is installed in the storage system.

    For details on the capacity saving function that uses a compression accelerator, see the Provisioning Guide for Open Systems, or the Provisioning Guide.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/834000123456

Registering a storage system

To start the storage operation from the REST API, register information about the storage system to the REST API server. If information (such as the IP address and port number) about the target storage system is changed, delete the information about the storage system, and then register the storage system again with the new information. For this API request, specify the user ID and password for accessing the storage system in the Authorization header. The specified user information is registered to the REST API server as information about the storage system.
Important
  • The user information registered on the REST API server is used by the REST API server when the storage system configuration information is refreshed or when information is obtained to update the information stored on the REST API server.
  • After a storage system is registered on the REST API server, if the password of a registered user is changed by using the REST API or Storage Navigator, the change is not applied to the storage system information registered on the REST API server. To register the new password on the REST API server, use the API function for changing information about storage systems.

Execution permission

Security Administrator (View Only) or Security Administrator (View & Modify)

Request line

POST base-URL/v1/objects/storages
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    • For VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900:

      The following shows an example of coding when VSP G900 is registered.

      {
        "ctl1Ip" : "192.0.10.10",
        "ctl2Ip" : "192.0.10.11",
        "model" : "VSP G900", 
        "serialNumber" : 123456,
        "changeNotificationSetting" : {
          "isNotifiable" : true
        },
        "usesSvp" : true,
        "svpIp" : "192.0.2.100"
      }

      Attribute

      Type

      Description

      serialNumber

      int

      (Required) Serial number of the storage system to be registered

      model

      string

      (Required) Model name of the storage system to be registered

      Specify one of the following values:

      • VSP E590
      • VSP E790
      • VSP E990
      • VSP E1090
      • VSP E590H
      • VSP E790H
      • VSP E1090H
      • VSP G350
      • VSP G370
      • VSP G700
      • VSP G900
      • VSP F350
      • VSP F370
      • VSP F700
      • VSP F900

      targetCtl

      string

      (Optional) Controller operated by the REST API

      Specify one of the following values:

      • CTL1: Controller 1
      • CTL2: Controller 2

      If this attribute is omitted, CTL1 is set.

      ctl1Ip

      string

      (Optional) IP address of controller 1 of the storage system

      You can specify an IPv4 or IPv6 IP address. If both an IPv4 and IPv6 IP addresses are specified on the storage system side as the IP address of the controller 1, specify an IPv4 address.

      If this attribute is omitted, the value is automatically set.

      If you specified CTL1 for the targetCtl attribute or omitted the targetCtl attribute, be sure to specify this attribute.

      ctl2Ip

      string

      (Optional) IP address of controller 2 of the storage system

      You can specify an IPv4 or IPv6 IP address. If both an IPv4 and IPv6 IP addresses are specified on the storage system side as the IP address of the controller 2, specify an IPv4 address.

      If this attribute is omitted, the value is automatically set.

      This attribute must be specified if CTL2 is specified for targetCtl.

      usesSvp

      boolean

      (Optional) Whether to link with an SVP

      • true: Link with an SVP
      • false: Do not link with an SVP

      If this attribute is omitted, false is set.

      If you use an SVP to manage the storage system, we recommend linking the storage system with the SVP.

      svpIp

      string

      (Optional) IP address of the SVP that will manage the storage system to be registered

      You can specify an IPv4 or IPv6 IP address. If both an IPv4 and IPv6 IP addresses are specified on the storage system side as the IP address of the SVP, specify an IPv4 address.

      This attribute must be specified if true is specified for usesSvp.

      If you specified false for the usesSvp attribute or omitted the usesSvp attribute, this attribute will be ignored even if it is specified. Even if the attribute is specified, it will not be registered. In addition, the value is not output by API requests to get storage system information.

      mappWebServerHttpsPort

      int

      (Optional) Port number used by the SVP for HTTPS communication

      If you specify true for the usesSvp attribute, and if the port number has been changed to anything other than the default value (443), be sure to specify this attribute.

      If this attribute is omitted, 443 is set.

      If you specified false for the usesSvp attribute or omitted the usesSvp attribute, this attribute will be ignored even if it is specified. Even if the attribute is specified, it will not be registered. In addition, the value is not output by API requests to get storage system information.

      rmiPort

      int

      (Optional) The port number to be used for RMI communication between the Configuration Manager REST API server and the storage system

      If you specify true for the usesSvp attribute, and if the port number has been changed to anything other than the default value (1099), be sure to specify this attribute.

      If this attribute is omitted, 1099 is set.

      If you specified false for the usesSvp attribute or omitted the usesSvp attribute, this attribute will be ignored even if it is specified. Even if the attribute is specified, it will not be registered. In addition, the value is not output by API requests to get storage system information.

      isSecure

      boolean

      (Optional) Settings for SSL communication between the REST API server and the storage system

      • true: SSL communication is enabled.

      If this attribute is omitted, true is set.

      If you want to ensure communication security, you can enable SSL communication only.

      lanConnectionProtocol

      string

      (Optional) Specifies the encrypted communication mode used for SSL communication between the REST API server and the storage system

      • DTLS SVP
      • SSL TLS

      If this attribute is omitted, DTLS SVP is set.

      If false is specified for the usesSvp attribute, this attribute cannot be specified.

      changeNotificationSetting

      object

      (Optional) Settings for receiving configuration-change notifications from the storage system

      If the changeNotificationSetting attribute is omitted, the system operates in the same way as when the isNotifiable attribute is omitted.

      • (Optional) isNotifiable (boolean)

        Specify whether to receive configuration-change notifications from the storage system.

        We strongly recommend that you specify true for this attribute.

        • true: Receive notifications
        • false: Do not receive notifications

        If true is specified for the isNotifiable attribute, an error occurs if the internal configuration-change notification test cannot be performed. If the attribute is omitted, the system assumes that true is specified for the isNotifiable attribute, and the internal processing continues even if the test cannot be performed. If the configuration-change notification test cannot be performed, change the value of the isNotifiable attribute to false. This will allow processing of the API request to end normally.

        To verify that the settings to receive configuration-change notifications are configured as intended, run the API request that gets a list of the destinations of configuration-change notifications from the storage system. If the Configuration Manager REST API server is registered as a destination for configuration-change notifications, this indicates that settings have been configured with true specified for the attribute.

    • For storage systems VSP 5000 series, VSP G200, G400, G600, G800, VSP G1000, VSP G1500, VSP F400, F600, F800, VSP F1500, Virtual Storage Platform, or Unified Storage VM:

      The following shows an example of coding when VSP G400 is registered.

      {
        "svpIp": "192.0.2.100",
        "serialNumber": 123456,
        "model": "VSP G400",
        "changeNotificationSetting": {
          "isNotifiable": true,
          "mappWebServerHttpsPort": 443
        }
      }

      Attribute

      Type

      Description

      svpIp

      string

      (Required) IP address of the SVP that will manage the storage system to be registered

      You can specify an IPv4 or IPv6 IP address. If both an IPv4 and IPv6 IP addresses are specified on the storage system side as the IP address of the SVP, specify an IPv4 address.

      rmiPort

      int

      (Optional) The port number to be used for RMI communication between the Configuration Manager REST API server and the storage system

      For VSP 5000 series, only 11099 can be specified. If this attribute is omitted, 11099 is set.

      For other series, if this attribute is omitted, 1099 is set.

      mappWebServerHttpsPort

      int

      (Optional) Port number used by the SVP for HTTPS communication

      Use this attribute when SSL communication is used between the REST API server and the storage system.

      You can use this attribute for VSP G200, G400, G600, G800, VSP F400, F600, F800 for which the microcode version is 83-04-44-XX/XX or later.

      If the port number is changed from the default value 443, specify the new value.

      If this attribute is omitted, 443 will be set.

      If this value has been changed, be sure to specify the same value as the mappWebServerHttpsPort attribute that is set when a notification about changes made to the storage system is received.

      serialNumber

      int

      (Required) Serial number of the storage system to be registered

      model

      string

      (Required) Model name of the storage system to be registered

      Specify one of the following values:

      • VSP 5100
      • VSP 5200
      • VSP 5500
      • VSP 5600
      • VSP 5100H
      • VSP 5200H
      • VSP 5500H
      • VSP 5600H
      • VSP G200
      • VSP G400
      • VSP G600
      • VSP G800
      • VSP G1000
      • VSP G1500
      • VSP F400
      • VSP F600
      • VSP F800
      • VSP F1500
      • VSP N400
      • VSP N600
      • VSP N800
      • HUS VM
      • VSP

      isSecure#

      boolean

      (Optional) Settings for SSL communication between the REST API server and the storage system

      • true: SSL communication is enabled.
      • false: SSL communication is disabled.

      For VSP 5000 series, only true can be specified. If this attribute is omitted, true is set.

      For other series, if this attribute is omitted, false is set.

      For VSP G1000, VSP G1500, and VSP F1500 storage systems, we recommend using microcode version 80-05-2X-XX/XX or later.

      lanConnectionProtocol#

      string

      (Optional) Specifies the encrypted communication mode used for SSL communication between the REST API server and the storage system

      You can use this attribute for VSP G200, G400, G600, G800, VSP F400, F600, F800 for which the microcode version is 83-04-44-XX/XX or later.

      You can set any of these values when true is set for the isSecure attribute.

      • DTLS
      • DTLS SVP
      • SSL TLS

      If this attribute is omitted, DTLS is set.

      changeNotificationSetting

      object

      (Optional) Settings for receiving configuration-change notifications from the storage system

      You can specify this attribute for VSP G200, G400, G600, G800, VSP F400, F600, F800 for which the microcode version is 83-04-XX-XX/XX or later, VSP G1000 storage systems for which the microcode version is 80-05-XX-XX/XX or later, VSP 5000 series, VSP G1500, or VSP F1500.

      If the changeNotificationSetting attribute is omitted, the system operates in the same way as when the isNotifiable attribute is omitted.

      • (Optional) isNotifiable (boolean)

        Specify whether to receive configuration-change notifications from the storage system.

        We strongly recommend that you specify true for this attribute.

        • true: Receive notifications
        • false: Do not receive notifications

        If true is specified for the isNotifiable attribute, an error occurs if the internal configuration-change notification test cannot be performed. If the attribute is omitted, the system assumes that true is specified for the isNotifiable attribute, and the internal processing continues even if the test cannot be performed. If the configuration-change notification test cannot be performed, change the value of the isNotifiable attribute to false. This will allow processing of the API request to end normally.

        To verify that the settings to receive configuration-change notifications are configured as intended, run the API request that gets a list of the destinations for configuration-change notifications from the storage system. If the Configuration Manager REST API server is registered as a destination for configuration-change notifications, this indicates that settings have been configured with true specified for the attribute.

      • (Optional) mappWebServerHttpsPort (int)

        Port number used by the SVP for HTTPS communication

        For VSP G200, G400, G600, G800, VSP F400, F600, F800, if the port number has been changed from the default value 443, specify the new value.

        You can set this value when true is set for the isNotifiable attribute.

        If this attribute is omitted, 443 will be set.

        If the microcode version of VSP G200, G400, G600, G800, VSP F400, F600, F800 is 83-04-44-XX/XX or later, and this value is changed, make sure that you specify the same value for the mappWebServerHttpsPort attribute that is set when SSL communication is used between the REST API server and the storage system.

      #: If the management server is running a Linux OS and the REST API is installed by a non-root user, the values that can be specified will be restricted. For details, see the description of operation in an environment where the REST API is installed by a non-root user.

Response message
  • Body

    {
      "storageDeviceId": "834000123456",
      "model": "VSP G400",
      "serialNumber": 123456
    }

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID of the registered storage system

    model

    string

    Model name of the registered storage system

    serialNumber

    int

    Serial number of the registered storage system

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the section explaining HTTP status codes.

Status codes

Message

Description

409

Conflict

The storage system is already registered with the specified storage device ID.

412

Precondition Failed

The specified action cannot be executed because the number of storage systems that can be registered exceeded the maximum.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -u rest-test:rest-api -X POST --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages

Changing information about a storage system

The following requests change information about the users of the storage systems registered in the REST API server, and information not about those users.

Run the API request according to your purpose as follows.

  • To change user information:

    Specify the new user ID and password for the Authorization header, and then run an API request without specifying the request body. The user information specified for the Authorization header is applied to the user information of the storage system. Run this request separately from requests for which attributes are specified in the request body.

  • To change other information:

    Run the request with attributes specified in the request body. Only the information that is specified will be changed. The user information of the storage system will not be updated.

    To specify the targetCtl attribute in the request body (to change the controller on which the REST API operation is performed), run the API request with your user ID and password specified in the Authorization header.

Important
  • To change the following information, first delete the information about the storage system from the REST API server, and then change the settings for the target storage system. Then register the information about the storage system again.

    • Settings such as the IP address and port number of the storage system

    • If the storage system is a VSP E series, VSP G350, G370, G700, G900 or VSP F350, F370, F700, F900 model storage system, settings related to SVP linkage

  • After a storage system is registered on the REST API server, if the password of a registered user is changed by using the REST API or Storage Navigator, the change is not applied to the storage system information registered on the REST API server. Use this API request to register the new password on the REST API server.
Execution permission

Security Administrator (View Only) or Security Administrator (View & Modify)

Request line
PUT base-URL/v1/objects/storages/storage-device-ID

You can run this API request in a PATCH method.

Request message
  • Object ID

    Specify the storageDeviceId value obtained by getting information about the storage systems.

    Attribute

    Type

    Description

    storageDeviceId

    string

    (Required) Storage device ID

  • Query parameters

    None.

  • Body

    {
      "isSecure": true
    }

    Attribute

    Type

    Description

    isSecure#

    boolean

    (Optional) Settings for SSL communication between the REST API server and the storage system

    You cannot specify this attribute when the communication mode for the REST API server is proxyMode.

    • true: SSL communication is enabled.
    • false: SSL communication is disabled

    For VSP 5000 series, VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900 storage systems, false cannot be specified.

    For VSP G1000, VSP G1500, and VSP F1500 storage systems, we recommend using microcode version 80-05-2X-XX/XX or later.

    mappWebServerHttpsPort

    int

    (Optional) Port number used by the SVP for HTTPS communication

    If the port number is changed from the default value 443, specify the new value.

    • For VSP G200, G400, G600, G800, VSP F400, F600, F800 (when the microcode version is 83-04-44-XX/XX or later)

      Use this attribute when SSL communication is used between the REST API server and the storage system.

      If this value has been changed, be sure to set the same value for the mappWebServerHttpsPort attribute that is specified during the registration of the destination for notifications about storage system configuration changes.

    • For VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900

      Specify this attribute for a configuration that includes linkage to an SVP.

    lanConnectionProtocol#

    string

    (Optional) Specifies the encrypted communication mode used for SSL communication between the REST API server and the storage system

    You can set any of these values when true is set for the isSecure attribute.

    • For VSP G200, G400, G600, G800, VSP F400, F600, F800 (when the microcode version is 83-04-44-XX/XX or later)

      • DTLS
      • DTLS SVP
      • SSL TLS
    • For VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900

      Specify this attribute for a configuration that includes linkage to an SVP.

      • DTLS SVP
      • SSL TLS

    targetCtl

    string

    (Optional) Controller operated by the REST API

    You can use this attribute for VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

    Specify one of the following values:

    • CTL1: Controller 1
    • CTL2: Controller 2

    #: If the management server is running a Linux OS and the REST API is installed by a non-root user, the values that can be specified will be restricted. For details, see the description of operation in an environment where the REST API is installed by a non-root user.

Response message
  • Body

    {
      "storageDeviceId" : "834000123456",
      "model" : "VSP G400",
      "serialNumber" : 123456
    }

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID of the storage system about which information was changed

    model

    string

    Model name of the storage system about which information was changed

    serialNumber

    int

    Serial number of the storage system about which information was changed

Action template

None.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -u rest-test:rest-api -X PUT https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/834000123456

Deleting information about a storage system

To remove a storage system from the management of the REST API, delete information about the storage system. If settings, such as the IP address or port number of the storage system, are changed or the storage system is removed, run this API request to delete information about the storage system, and then change the settings for the storage system. If you change the settings before deleting information about the storage system, you must specify the force attribute to forcibly delete the information. Processing for this API request might take a few minutes to finish.
Execution permission

Security Administrator (View Only) or Security Administrator (View & Modify)

Request line

DELETE base-URL/v1/objects/storages/storage-device-ID
Request message
  • Object ID

    Specify the storageDeviceId value obtained by getting information about the storage systems.

    Attribute

    Type

    Description

    storageDeviceId

    string

    (Required) Storage device ID

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "storageDeviceId" : "834000123456",
      "model" : "VSP G400",
      "serialNumber" : 123456
    }

    Attribute

    Type

    Description

    storageDeviceId

    string

    Storage device ID of the deleted storage system

    model

    string

    Model name of the deleted storage system

    serialNumber

    int

    Serial number of the deleted storage system

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X DELETE https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/834000123456
Forcibly deleting storage system information

Before you run this API request, if the settings for the target storage system were changed or the storage system was removed, you can forcibly delete the information about the storage system by specifying the force attribute. If you specify the force attribute, specify the local host (localhost, 127.0.0.1, or ::1) for the host name from the management server, and then run this API request. The following is a coding example and description for the force attribute:

{
  "force": true
}

Attribute

Type

Description

force

boolean

(Optional) Specify whether to forcibly delete the storage system information in the REST API.

true: Forcibly deletes the storage system information.

false: Does not forcibly delete the storage system information.

If you do not specify a value, false is assumed.

Note

Even if you forcibly delete information about a storage system, information about a REST API server that was registered as a configuration-change notification destination will not be deleted. To delete information about notification destinations, register the storage system again, and then run the API request for deleting notification destinations.

Getting summary information about storage systems

This request gets summary information about storage systems.
Note
  • You can use this API function for the following storage systems: VSP 5000 series, VSP E series, VSP Gx00 models, VSP G1000, VSP G1500, VSP Fx00 models, VSP F1500, Virtual Storage Platform, HUS VM. You can use this API function for VSP E series, VSP G350, G370, G700, G900 and VSP F350, F370, F700, F900 model storage systems if the storage system is in a configuration that is linked to an SVP.

  • To get up-to-date information, you must run the API request that refreshes the storage system's cache before running this request. For details, see "Updating the cache of storage system configuration information".

Execution permission

Storage Administrator (View Only)

Request line
GET base-URL/v1/objects/storages/storage-device-ID/storage-summaries/instance
Request message
  • Object ID

    Specify a value for instance. For objects that have only one instance, the value of instance is a fixed value (the object ID).

  • Query parameters

    Parameter

    Type

    Description

    detailInfoType

    string

    (Optional) Type of detailed information to be obtained

    • parityGroupCapacity

      Gets additional capacity information about parity groups.

  • Body

    None.

Response message
  • Body

    {
      "name" : "VSP 5500",
      "svpMicroVersion" : "90-01-40/02",
      "rmiServerVersion" : "10_00_05",
      "numOfDiskBoards" : 8,
      "cacheMemoryCapacity" : 169984,
      "numOfSpareDrives" : 0,
      "totalOpenVolumeCapacity" : 5487,
      "totalOpenVolumeCapacityInKB" : 5754301448,
      "allocatedOpenVolumeCapacity" : 1853,
      "allocatedOpenVolumeCapacityInKB" : 1943911065,
      "allocatableOpenVolumeCapacity" : 877,
      "allocatableOpenVolumeCapacityInKB" : 919741295,
      "unallocatedOpenVolumeCapacity" : 3633,
      "unallocatedOpenVolumeCapacityInKB" : 3810390383,
      "reservedOpenVolumeCapacity" : 2756,
      "reservedOpenVolumeCapacityInKB" : 2890649088,
      "allocatedOpenVolumePhysicalCapacity" : 760,
      "allocatedOpenVolumePhysicalCapacityInKB" : 797214657,
      "allocatableOpenVolumePhysicalCapacity" : 328,
      "allocatableOpenVolumePhysicalCapacityInKB" : 344242149,
      "reservedOpenVolumePhysicalCapacity" : 1745,
      "reservedOpenVolumePhysicalCapacityInKB" : 1829765120,
      "allocatedMainframeVolumeCapacity" : 10,
      "allocatedMainframeVolumeCapacityInKB" : 11397000,
      "reservedMainframeVolumeCapacity" : 9,
      "reservedMainframeVolumeCapacityInKB" : 9744000,
      "totalAllocatedVolumeCapacity" : 1864,
      "totalAllocatedVolumeCapacityInKB" : 1955308065,
      "totalUnallocatedVolumeCapacity" : 3643,
      "totalUnallocatedVolumeCapacityInKB" : 3820134383,
      "totalReservedVolumeCapacity" : 2766,
      "totalReservedVolumeCapacityInKB" : 2900393088,
      "totalMainframeVolumeCapacity" : 20,
      "totalMainframeVolumeCapacityInKB" : 21141000,
      "totalVolumeCapacity" : 5507,
      "totalVolumeCapacityInKB" : 5775442448,
      "numOfOpenVolumes" : 6502,
      "numOfAllocatedOpenVolumes" : 509,
      "numOfAllocatableOpenVolumes" : 5671,
      "numOfReservedOpenVolumes" : 322
    }

    In the descriptions in this table, the following volumes include internal volumes and external volumes:

    • Open system volumes
    • Mainframe volumes
    • Intermediate volumes

    Attribute

    Type

    Description

    name

    string

    Name of the storage system

    svpMicroVersion

    string

    Microcode version of the SVP

    rmiServerVersion

    string

    Version of the RMI server

    numOfDiskBoards

    int

    Number of disk boards

    Replace "disk board" with "disk adapter" or "disk blade" depending on the storage system.

    cacheMemoryCapacity

    long

    Current cache capacity (MB)

    numOfSpareDrives

    int

    Number of spare drives

    This parameter is output if the storage system is VSP 5000 series, VSP G200, G400, G600, G800, VSP F400, F600, F800. This parameter is output if the storage system is VSP E series, VSP G350, G370, G700, G900, or VSP F350, F370, F700, F900, in a configuration that is linked to an SVP.

    totalOpenVolumeCapacity

    long

    The total capacity of the open system volumes (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalOpenVolumeCapacityInKB

    long

    The total capacity of the open system volumes (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatedOpenVolumeCapacity

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are allocated or to which namespaces are set (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatedOpenVolumeCapacityInKB

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are allocated or to which namespaces are set (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatableOpenVolumeCapacity

    long

    From among the open system volumes, the total capacity of volumes to which LU paths can be allocated or to which namespaces can be set (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatableOpenVolumeCapacityInKB

    long

    From among the open system volumes, the total capacity of volumes to which LU paths can be allocated or to which namespaces can be set (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    unallocatedOpenVolumeCapacity

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are not allocated and to which namespaces are not set (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    unallocatedOpenVolumeCapacityInKB

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are not allocated and to which namespaces are not set (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    reservedOpenVolumeCapacity

    long

    From among the open system volumes, the total capacity of reserved volumes, pool volumes, and the S-VOLs of snapshots (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    reservedOpenVolumeCapacityInKB

    long

    From among the open system volumes, the total capacity of reserved volumes, pool volumes, and the S-VOLs of snapshots (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatedOpenVolumePhysicalCapacity

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are allocated or to which namespaces are set (GB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    allocatedOpenVolumePhysicalCapacityInKB

    long

    From among the open system volumes, the total capacity of volumes to which LU paths are allocated or to which namespaces are set (KB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    allocatableOpenVolumePhysicalCapacity

    long

    From among the open system volumes, the total capacity of volumes to which LU paths can be allocated or to which namespaces can be set (GB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    allocatableOpenVolumePhysicalCapacityInKB

    long

    From among the open system volumes, the total capacity of volumes to which LU paths can be allocated or to which namespaces can be set (KB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    reservedOpenVolumePhysicalCapacity

    long

    From among the open system volumes, the total capacity of reserved volumes and pool volumes (GB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    reservedOpenVolumePhysicalCapacityInKB

    long

    From among the open system volumes, the total capacity of reserved volumes and pool volumes (KB)

    This is the total capacity of physical volumes, excluding the capacity of DP volumes and other virtual volumes.

    numOfOpenVolumes

    int

    Total number of open system volumes

    numOfAllocatedOpenVolumes

    int

    Total number of open system volumes to which LU paths are allocated or to which namespaces are set

    numOfAllocatableOpenVolumes

    int

    Total number of open system volumes to which LU paths are not allocated and to which namespaces are not set

    numOfReservedOpenVolumes

    int

    From among the open system volumes, the total number of reserved volumes, pool volumes, and the S-VOLs of snapshots

    allocatedMainframeVolumeCapacity

    long

    From among the mainframe volumes and intermediate volumes, the total capacity of normal volumes (excluding reserved volumes and pool volumes) (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    allocatedMainframeVolumeCapacityInKB

    long

    From among the mainframe volumes and intermediate volumes, the total capacity of normal volumes (excluding reserved volumes and pool volumes) (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    reservedMainframeVolumeCapacity

    long

    From among the mainframe volumes and intermediate volumes, the total capacity of reserved volumes, pool volumes, and the S-VOLs of snapshots (GB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    reservedMainframeVolumeCapacityInKB

    long

    From among the mainframe volumes and intermediate volumes, the total capacity of reserved volumes, pool volumes, and the S-VOLs of snapshots (KB)

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalAllocatedVolumeCapacity

    long

    Total capacity of the volumes (in GB) to which LU paths are allocated or to which namespaces are set from among the open system volumes, and normal volumes (excluding reserved volumes and pool volumes) from among the mainframe volumes and intermediate volumes

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalAllocatedVolumeCapacityInKB

    long

    Total capacity of the volumes (in KB) to which LU paths are allocated or to which namespaces are set from among the open system volumes, and normal volumes (excluding reserved volumes and pool volumes) from among the mainframe volumes and intermediate volumes

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalUnallocatedVolumeCapacity

    long

    Total capacity of the volumes (in GB) to which LU paths are not allocated and to which namespaces are not set from among the open system volumes, and the reserved volumes, pool volumes, and the S-VOLs of snapshots from among the mainframe volumes and intermediate volumes

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalUnallocatedVolumeCapacityInKB

    long

    Total capacity of the volumes (in KB) to which LU paths are not allocated and to which namespaces are not set from among the open system volumes, and the reserved volumes, pool volumes, and the S-VOLs of snapshots from among the mainframe volumes and intermediate volumes

    This total capacity includes the capacity of DP volumes and other virtual volumes.

    totalReservedVolumeCapacity

    long

    Total number of reserved volumes, pool volumes, and the S-VOLs of snapshots (GB)

    totalReservedVolumeCapacityInKB

    long

    Total number of reserved volumes, pool volumes, and the S-VOLs of snapshots (KB)

    totalMainframeVolumeCapacity

    long

    Total capacity of the mainframe volumes and intermediate volumes (GB)

    totalMainframeVolumeCapacityInKB

    long

    Total capacity of the mainframe volumes and intermediate volumes (KB)

    totalVolumeCapacity

    long

    Total capacity of the open system volumes, mainframe volumes, and intermediate volumes (GB)

    totalVolumeCapacityInKB

    long

    Total capacity of the open system volumes, mainframe volumes, and intermediate volumes (KB)

    If you run this request with parityGroupCapacity specified for the query parameter detailInfoType, capacity information about parity groups is also obtained.

    Attribute

    Type

    Description

    totalAvailableParityGroupCapacity

    long

    Total free capacity of available parity groups and external parity groups (GB)

    totalAvailableParityGroupCapacityInKB

    long

    Total free capacity of available parity groups and external parity groups (KB)

    If the information cannot be obtained, -1 is output, indicating an invalid value.

    largestAvailableParityGroupCapacity

    long

    Free capacity of the parity group that has the largest available capacity or of external parity groups (KB)

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/900000012345/storage-summaries/instance?detailInfoType=parityGroupCapacity

Getting a list of sessions

The following request gets a list of valid sessions on the REST API server. Only a user who belongs to the Administrator user group (built-in user group) for the VSP 5000 series, VSP E series, VSP Gx00 models, VSP G1000, VSP G1500, VSP Fx00 models, or VSP F1500, or a maintenance user for Virtual Storage Platform or Unified Storage VM can perform this operation.
Execution permission

Administrator user group (built-in user group) for the VSP 5000 series, VSP E series, VSP Gx00 models, VSP G1000, VSP G1500, VSP Fx00 models, or VSP F1500

Maintenance user for Virtual Storage Platform or Unified Storage VM

Request line

GET base-URL/v1/objects/storages/storage-device-ID/sessions
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "data": [
        {
          "sessionId": 8,
          "userId": "rest-user",
          "ipAddress": "192.0.2.100",
          "createdTime": "2015-09-14T01:02:24Z",
          "lastAccessedTime": "2015-09-14T01:02:24Z"
        },
        {
          "sessionId": 6,
          "userId": "api-user",
          "ipAddress": "192.0.2.100",
          "createdTime": "2015-09-14T00:59:58Z",
          "lastAccessedTime": "2015-09-14T00:59:58Z"
        },
        {
          "sessionId": 5,
          "userId": "admin-user",
          "ipAddress": "192.0.2.100",
          "createdTime": "2015-09-14T00:59:53Z",
          "lastAccessedTime": "2015-09-14T00:59:53Z"
        }
      ]
    }

    Attribute

    Type

    Description

    sessionId

    int

    Session ID

    userId

    string

    User ID that was used to generate the session

    ipAddress

    string

    IP address of the REST API client that was used to generate the session

    If the REST API client accesses the REST API server via another server, a character string consisting of the concatenated IP addresses of the client and of the server used to access the REST API server (the content of the X-Forwarded-For header received by the REST API server) will be output.

    createdTime

    ISO8601string

    Time the session was generated

    lastAccessedTime

    ISO8601string

    Time the session was last used

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/sessions/

Getting information about a specific session

The following request gets information about a valid session on the REST API server by specifying a session ID. For the Authorization header of the request, specify the token of the session.
Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/storages/storage-device-ID/sessions/object-ID
Request message
  • Object ID

    Specify the value of sessionId that was obtained when the session was generated.

    Attribute

    Type

    Description

    sessionId

    int

    (Required) Session ID

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "token": "97c13b80-8244-4b36-bc21-03026205fa64",
      "sessionId": 9
    }

    Attribute

    Type

    Description

    sessionId

    int

    Session ID

    token

    string

    Token

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/sessions/9

Generating sessions

The following request generates sessions and manages the sessions on the REST API server. A maximum of 64 sessions can be generated for each storage system. When the number of sessions exceeds the maximum number of sessions, the HTTP status code 503 is returned. In this case, wait a while and then run the request again.
NoteFor remote copy, specify at least 60 seconds for the aliveTime attribute of the sessions generated on the remote storage system. If you specify less than 60 seconds, the session on the remote storage system might time out, causing the execution of a request to fail.
Execution permission

Storage Administrator (View Only)

Request line
POST base-URL/v1/objects/storages/storage-device-ID/sessions
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    The following coding example specifies the time until a session timeout:

    {
      "aliveTime": 5
    }

    Attribute

    Type

    Description

    aliveTime

    long

    (Optional) Session timeout value (in seconds)

    Specify a value in the range from 1 to 300#.

    If this attribute is omitted, 300 is assumed.

    authenticationTimeout

    long

    (Optional) Timeout value for authentication processing (in seconds)

    Specify this value if an external authentication server is being used to authenticate users.

    You can specify this parameter if the storage system model is VSP 5000 series, VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

    Change the value according to the external authentication settings of the storage system.

    Specify a value in the range from 1 to 900.

    If this attribute is omitted, 120 is assumed.

    #:

    • There is a margin of error of between -20 seconds to +5 seconds before the session times out. If the execution of an API request fails with the KART40047-E error, which indicates an invalid session, generate a new session and then run the API request again.

    • If either of the following conditions applies and you generate a session with less than 20 seconds specified for the aliveTime attribute, you might not be able to run API requests depending on the load on the system. Specify 20 seconds or more for the aliveTime attribute.

      • The storage system is a VSP 5000 series, VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900, and the communication mode for the REST API server is fcConnectionMode.

      • The storage system is a VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900, and a linkage to the SVP is established in the configuration.

Response message
  • Body

    {
      "token": "b74777a3-f9f0-4ea8-bd8f-09847fac48d3",
      "sessionId": 3
    }

    Attribute

    Type

    Description

    sessionId

    int

    Session ID

    An ID that is used to manage sessions.

    token

    string

    Token

    Information that is used to identify the source that issues requests as a specific user.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -u rest-test:rest-api -X POST https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/sessions/ -d ""

Discarding sessions

The following request discards the sessions that are no longer required. If a session is discarded, the lock obtained in that session is unlocked at the same time. For the Authorization header of the request, specify the token for a session to be discarded.
Execution permission

Storage Administrator (View Only)

Request line

DELETE base-URL/v1/objects/storages/storage-device-ID/sessions/object-ID
Request message
  • Object ID

    Specify the value of sessionId that was obtained when the session was generated. A user who belongs to the Administrator user group (built-in user group) for the VSP 5000 series, VSP E series, VSP Gx00 models, VSP G1000, VSP G1500, VSP Fx00 models, or VSP F1500, or a maintenance user for Virtual Storage Platform or Unified Storage VM can specify the value of sessionId that was obtained by the processing to get information about sessions.

    Attribute

    Type

    Description

    sessionId

    int

    (Required) Session ID

  • Query parameters

    None.

  • Body

    {
      "force": true
    }

    Attribute

    Type

    Description

    force

    boolean

    Specify whether to force discarding of the session generated by other users, in addition to the session you generated. Only a user who belongs to the Administrator user group (built-in user group) for the VSP 5000 series, VSP E series, VSP Gx00 models, VSP G1000, VSP G1500, VSP Fx00 models, or VSP F1500, or a maintenance user for Virtual Storage Platform or Unified Storage VM can specify this attribute.

    • true: Forces discarding of the session generated by other users, in addition to the session you generated.
    • false: Forces discarding of only the session you generated.

    If you omit this value, false is used.

Response message
  • Body

    None.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X DELETE --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/sessions/1

Getting a list of job information

The following request gets a list of information about jobs that were submitted by the user from the REST API. Only a user who belongs to a user group with the Storage Administrator (System Resource Management) role can get information about all the registered jobs. Job information can be used to check APIs that were issued and to identify the cause of a problem in the storage system.
Execution permission

No role is required to run this API request. Only the users authenticated by the storage system can issue this API request.

Request line

GET base-URL/v1/objects/storages/storage-device-ID/jobs
Request message
  • Object ID

    None.

  • Query parameters

    If no query parameters are specified, the request gets information about 100 jobs that can be referenced by the user and were submitted after the other jobs.

    Parameter

    Type

    Filter Condition

    startCreatedTime

    ISO8601string

    (Optional) Specify the submission start time of the jobs for which you want to get information. Specify the time in YYYY-MM-DDThh:mm:ssZ format.

    The request gets information about jobs that were submitted on and after the specified time.

    endCreatedTime

    ISO8601string

    (Optional) Specify the submission end time of the jobs for which you want to get information. Specify the time in YYYY-MM-DDThh:mm:ssZ format.

    The request gets information about jobs that were submitted before the specified time.

    count

    int

    (Optional) Specify a number from 1 to 100 for the number of jobs for which you want to get information.

    The specified number is the maximum number of jobs for which information will be obtained.

    If this is omitted, 100 is assumed.

    status

    string

    (Optional) Specify one of the following values for the status of the jobs for which information is to be obtained.

    • Initializing: The jobs are being initialized.

      If you also need to specify a value for "state", you must specify Queued for "state".

    • Running: The jobs are running.

      If you also need to specify a value for "state", you must specify Started for "state".

    • Completed: The jobs have been completed.

      If you also need to specify a value for "state", you must specify Succeeded, Failed, or Unknown for "state".

    state

    string

    (Optional) Specify one of the following values for the status (state) of the jobs for which information is to be obtained.

    • Queued: The jobs have been queued.
    • Started: The jobs have been started.
    • Succeeded: The jobs finished successfully.
    • Failed: The jobs failed.
    • Unknown: The state of the jobs is unknown.

    The following example gets information about a maximum of 30 jobs that ended normally and were submitted after other jobs during the period from "2015/05/01 08:00:00" to "2015/05/31 23:59:59".

    ?startCreatedTime=2015-05-01T08:00:00Z&endCreatedTime=2015-05-31T23:59:59Z&count=30&state=Succeeded
  • Body

    None.

Response message
  • Body

    {
      "data": [
        {
          "jobId": 2,
          "self": "/ConfigurationManager/v1/objects/storages/836000123456/jobs/2",
          "userId": "rest-test",
          "status": "Completed",
          "state": "Succeeded",
          "createdTime": "2015-09-14T02:08:13Z",
          "updatedTime": "2015-09-14T02:08:13Z",
          "completedTime": "2015-09-14T02:08:13Z",
          "request": {
            "requestUrl": "/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/lock/invoke",
            "requestMethod": "PUT",
            "requestBody": {
              "parameters": {
                "waitTime": null
              }
            }
          },
          "affectedResources": [
            "/ConfigurationManager/v1/objects/storages/836000123456/resource-groups"
          ]
        },
        {
          "jobId": 1,
          "self": "/ConfigurationManager/v1/objects/storages/836000123456/jobs/1",
          "userId": "rest-test",
          "status": "Completed",
          "state": "Failed",
          "createdTime": "2015-09-14T02:04:11Z",
          "updatedTime": "2015-09-14T02:04:12Z",
          "completedTime": "2015-09-14T02:04:12Z",
          "request": {
            "requestUrl": "/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/lock/invoke",
            "requestMethod": "PUT",
            "requestBody": {
              "parameters": {
                "waitTime": null
              }
            }
          },
          "error": {
            "errorSource": "/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/lock/invoke",
            "message": "An error occurred in the storage system. (message =  Access denied with Lock/Unlock)",
            "cause": "An error occurred during execution of a CCI command.",
            "solution": "See the manual of the CCI and remove the cause of the error.",
            "messageId": "KART30000-E",
            "errorCode": {
              "errorCode": "EX_EACCES"
            }
          }
        }
      ]
    }

    Attribute

    Type

    Description

    data

    object[]

    Job information (job objects) created by the user from the REST API.

    The maximum number of jobs for which you can get information at one time is 100.

    For details on the job object schema, see the section explaining job objects.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/jobs

Getting job information

The following request gets, at a specific timing, information about a specified job that was submitted by the user from the asynchronous API. Only a user who belongs to a user group with the Storage Administrator (System Resource Management) role can also obtain information about jobs submitted by other users. The obtained information can be used to check the job status.
Execution permission

No role is required to run this API request. Only the users authenticated by the storage system can issue this API request.

Request line

GET base-URL/v1/objects/storages/storage-device-ID/jobs/object-ID
Request message
  • Object ID

    Specify the jobId value obtained by getting information about the job list or the response message of the asynchronous API.

    Attribute

    Type

    Description

    jobId

    long

    (Required) Job object ID

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "jobId": 3,
      "self": "/ConfigurationManager/v1/objects/storages/836000123456/jobs/3",
      "userId": "rest-test",
      "status": "Completed",
      "state": "Succeeded",
      "createdTime": "2015-09-14T02:08:13Z",
      "updatedTime": "2015-09-14T02:08:13Z",
      "completedTime": "2015-09-14T02:08:13Z",
      "request": {
        "requestUrl": "/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/lock/invoke",
        "requestMethod": "PUT",
        "requestBody": {
          "parameters": {
            "waitTime": null
          }
        }
      },
      "affectedResources": [
        "/ConfigurationManager/v1/objects/storages/836000123456/resource-groups"
      ]
    }

    For details on the job object schema, see the description on job objects.

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the section explaining HTTP status codes.

Status codes

Message

Description

404

Not Found

  • There is no information corresponding to the specified job ID.
  • The user who issued the API request is not the user who submitted the job corresponding to the specified job ID.
Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X GET https://192.0.2.100:23451/ConfigurationManager/v1/objects/storages/836000123456/jobs/3

Locking a resource group

The following request locks resources of a resource group allocated to the user who runs API requests, preventing other users from performing operations on the resources. Exclusive control by locking is performed on a session basis. To run requests on the locked resources, specify as the Authorization header the token of the session that was specified when the resources were locked.
Execution permission

Storage Administrator (View Only)

Request line
PUT base-URL/v1/storage-device-ID/services/resource-group-service/actions/lock/invoke

You can run this API request in a POST method.

Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    {
      "parameters": {
        "waitTime": 30
      }
    }

    Attribute

    Type

    Description

    waitTime

    int

    The time that elapses before a lock timeout (in seconds)

    Specify a value from 0 to 7200 for the maximum wait time that elapses before a lock timeout occurs, for cases such as when the target resource is already locked by other sessions.

    If this value is omitted, 0 is specified.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description on job objects.

    Attribute

    Description

    affectedResources

    URL of the resource group that obtained a lock

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Status code

Message

Description

503

Service unavailable

The operation cannot be performed because an API operation that locks or unlocks resources is being run by using the same session.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT --data-binary @./InputParameters.json https://192.0.2.100:23451/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/lock/invoke

Unlocking a resource group

The following request unlocks a resource group. For the Authorization header of the request for releasing the lock, specify the token of the session that got the lock.
Execution permission

Storage Administrator (View Only)

Request line
PUT base-URL/v1/storage-device-ID/services/resource-group-service/actions/unlock/invoke

You can run this API request in a POST method.

Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

    Attribute

    Description

    affectedResources

    URL of the resource group that was unlocked

Status codes

For details on the status codes of the request for this operation, see the section explaining HTTP status codes.

Status code

Message

Description

503

Service unavailable

The operation cannot be performed because an API operation that locks or unlocks resources is being run by using the same session.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3-f9f0-4ea8-bd8f-09847fac48d3" -X PUT https://192.0.2.100:23451/ConfigurationManager/v1/836000123456/services/resource-group-service/actions/unlock/invoke -d ""