Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
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 session. 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.22.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/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": "886000123456",
          "model": "VSP G700",
          "serialNumber": 123456,
          "ctl1Ip": "192.0.2.100",
          "ctl2Ip": "192.0.2.101"
        }
      ]
    }

    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

    This attribute is displayed for storage systems VSP 5000 series.

    ctl1Ip

    string

    IP address of controller 1 of the storage system

    This attribute is displayed for storage systems VSP E, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

    ctl2Ip

    string

    IP address of controller 2 of the storage system

    This attribute is displayed for storage systems VSP E, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

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/ConfigurationManager/v1/objects/storages

Getting information about a specific storage system

The following request gets information about the storage system for which an operation is to be performed.
Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/storages/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

    Attribute

    Type

    Filter Condition

    detailInfoType

    string

    (Optional) Type of detailed information to be obtained

    • version

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

  • Body

    None.

Response message
  • Body

    {
      "storageDeviceId" : "886000123456",
      "model" : "VSP G700",
      "serialNumber" : 123456,
      "ctl1Ip": "192.0.10.10",
      "ctl2Ip": "192.0.10.11",
      "dkcMicroVersion" : "88-01-01/00",
      "communicationModes": [
        {
          "communicationMode": "lanConnectionMode"
        }
      ],
      "isSecure": 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

    svpIp

    string

    IP address of the SVP

    This attribute is displayed for storage systems VSP 5000 series

    ctl1Ip

    string

    IP address of controller 1 of the storage system

    This attribute is displayed for storage systems VSP E, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900

    ctl2Ip

    string

    IP address of controller 2 of the storage system

    This attribute is displayed for storage systems VSP E, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900

    dkcMicroVersion

    string

    Microcode version of the storage system

    communicationModes

    object[]

    Array of communication modes

    The following attributes are output for the communication modes between the REST API server and the storage system:

    • communicationMode (string)

      Communication mode

      lanConnectionMode is displayed.

    isSecure

    boolean

    Whether the communication between the REST API server and the storage system is secure.

    The default value is true.

    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, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

    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, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

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

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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/storages/instance

Getting summary information about storage systems

This request gets summary information about storage systems.
Note
  • You can use this API function for VSP 5000 series.

  • 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/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

    cacheMemoryCapacity

    long

    Current cache capacity (MB)

    numOfSpareDrives

    int

    Number of spare drives

    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 paths are allocated (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 paths are allocated (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 paths can be allocated (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 paths can be allocated (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 paths are not allocated (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 paths are not allocated (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 paths are allocated (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 paths are allocated (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 paths can be allocated (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 paths can be allocated (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 paths are allocated

    numOfAllocatableOpenVolumes

    int

    Total number of open system volumes to which paths are not allocated

    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 paths are allocated 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 paths are allocated 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 paths are not allocated 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 paths are not allocated 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)

    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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/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) can perform this operation.
Execution permission

Administrator user group (built-in user group)

Request line

GET base-URL/v1/objects/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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/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/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": "97c13b8082444b36bc2103026205fa64",
      "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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/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/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.

    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 might be a delay of up to five seconds after the specified amount of time has elapsed, before the session times out.

Response message
  • Body

    {
      "token": "d7b673af189048468c5af9bcf3bbbb6f",
      "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/ConfigurationManager/v1/objects/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/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) 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) 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 d7b673af189048468c5af9bcf3bbbb6f" -X DELETE --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/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/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/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/services/resource-group-service/actions/lock/invoke",
            "requestMethod": "POST",
            "requestBody": {
              "parameters": {
                "waitTime": null
              }
            }
          },
          "affectedResources": [
            "/ConfigurationManager/v1/objects/resource-groups"
          ]
        },
        {
          "jobId": 1,
          "self": "/ConfigurationManager/v1/objects/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/services/resource-group-service/actions/lock/invoke",
            "requestMethod": "POST",
            "requestBody": {
              "parameters": {
                "waitTime": null
              }
            }
          },
          "error": {
            "errorSource": "/ConfigurationManager/v1/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.",
            "solutionType": "SEE_ERROR_DETAIL",
            "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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/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/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/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/services/resource-group-service/actions/lock/invoke",
        "requestMethod": "POST",
        "requestBody": {
          "parameters": {
            "waitTime": null
          }
        }
      },
      "affectedResources": [
        "/ConfigurationManager/v1/objects/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 d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/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
POST base-URL/v1/services/resource-group-service/actions/lock/invoke
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 d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/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
POST base-URL/v1/services/resource-group-service/actions/unlock/invoke
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 d7b673af189048468c5af9bcf3bbbb6f" -X POST https://192.0.2.100/ConfigurationManager/v1/services/resource-group-service/actions/unlock/invoke -d ""