Update Virtual Storage Resource Properties

The Update Virtual Storage Resource Properties operation updates one or more of the writable properties of a virtual storage resource.

HTTP method and URI

POST /api/storage-groups/{storage-group-id}/virtual-storage-resources/{virtual-storage-resource-id}

In this request, the URI variable {storage-group-id} is the object ID of the storage group object and the URI variable {virtual-storage-resource-id} is the element ID of the virtual storage resource element.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable property that is to be updated by this operation. Field names and data types in this JSON object are expected to match the corresponding property names and data types defined in the Virtual Storage Resource element object. The JSON object can and should omit fields for properties whose values are not to be changed by this operation.

Description

This operation updates a virtual storage resource's properties with the values specified.

If the API user does not have action/task permission to the Configure Storage – System Programmer task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a Storage Group object to which the API user has object-access permission, or does not identity an FCP storage group, or if the element ID {virtual-storage-resource-id} does not identify a Virtual Storage Resource element object in the storage group. In addition to object-access to the parent storage group, updates to the adapter-port-uri or device-number properties also require object-access permission to the partition that is associated with the target virtual storage resource. If these properties appear in the request body and the user does not have object-access to the partition identified in the partition-uri property, a 403 (Forbidden) status code is returned. If the CPC on which this virtual storage resource exists is not active, or if the adapter-port-uri field references a storage adapter port that does not reside in the target virtual storage resource's CPC, a 409 (Conflict) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because the document defines an adapter-port-uri field that references a non-FCP adapter, because the parent storage group already contains a virtual storage resource with the specified name, or because the partition associated with this virtual storage resource already contains a device with the supplied device number.

If the request body contents are valid, the virtual storage resource's properties are updated to their corresponding request body content's field's values. All fields are optional and may be excluded from the request body; if a field is not found in the request body, its property's value will not be modified.

If the update changes the value of any property for which property-change notifications are due, those notifications are emitted asynchronously to this operation.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the storage group whose object-id is {storage-group-id}.
  • Object-access permission to the partition referenced by the virtual storage resource's partition-uri property. This requirement only applies when updating the adapter-port-uri or device-number properties.
  • Action/task permission to the Configure Storage – System Programmer task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Update Virtual Storage Resource Properties: HTTP status and reason codes
HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
8 A virtual storage resource with the name specified in the request body already exists within the parent storage group.
18 The request body contains the adapter-port-uri field, but the type property of the parent adapter is not "fcp".
452 The new value supplied in the device-number field conflicts with an existing device number for another device attached to the partition associated with this virtual storage resource.
403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage – System Programmer task.
450 The adapter-port-uri or device-number fields are present in the request body and the API user does not have object-access permission to the partition referenced by the current value of the virtual storage resource's partition-uri property
404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC, or is a storage group of the wrong type, or the API user does not have object-access permission to it.
5 A virtual storage resource with element-id {virtual-storage-resource-id} does not exist in the storage group on the HMC.
409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions").
2 The parent storage group with object-id {storage-group-id}or the partition identified by this virtual storage resource's partition-uri property value was busy and the request timed out.
6 The status property value for the partition identified by this virtual storage resource's partition-uri property is not valid to perform the operation (must be in one of the following states: "active", "degraded", "paused", "reservation-error", "stopped", or "terminated").
441 The storage adapter port referenced by the adapter-port-uri field resides in a different CPC than the targeted virtual storage resource.
498 The adapter-port-uri field was present in the request body when the current value of that property in the virtual storage resource element with object-id {virtual-storage-resource-id} is null.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Update Virtual Storage Resource Properties: Request
POST /api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources/
  4ce7feea-9fe9-11e8-b6db-fa163e3c2af4 HTTP/1.1
x-api-session: 3f4ojo8469608kk498sr9e96l05yrsyapyheb1icwn355ws0pd
content-type: application/json
content-length: 44
{
   "description":"vHBA in FCP Storage Group"
}
Figure 2. Update Virtual Storage Resource Properties: Response
204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 14 Aug 2018 18:49:28 GMT

<No response body>