Overview of sample coding

REST API Reference Guide for Virtual Storage Platform 5000, Virtual Storage Platform E Series, and Virtual Storage Platform G/F Series

Version
93-07-0x
90-09-0x
88-08-10
Audience
anonymous
Part Number
MK-98RD9014-17
This section provides sample client coding written in Python, as reference information for calling and using the REST API. The sample client coding includes basic code constructs required for client programs, including those for getting information about, creating, and changing the attributes of objects. Each sample of client coding shows an operation example such as allocating a volume or creating a copy pair. You can apply the code constructs included in the sample client coding to other use cases.

Code constructs of sample coding

The following operations are performed by the sample coding:

  • Allocate a volume

    In one of the samples, an HDP volume is created from an HDP pool that has already been created, and the volume is made accessible by allocating it to a host.

  • Operate a ShadowImage pair

    In one of the samples, volumes that have already been created are used to create a ShadowImage pair. After the pair is split, the status of the pair is verified.

  • Register remote storage system information

    In one of the code samples, information about the remote storage systems is registered to the REST API server of the local storage system. This is a prerequisite operation for a remote copy operation.

  • Operate a TrueCopy pair

    In one of the code samples, a TrueCopy pair is created by using volumes that have already been created, and the pair status is checked. A resource group is locked while the pair is being created.

  • Upload files (specify the transfer destinations of audit log files)

    Specify settings so that the audit log files of storage systems are transferred to the syslog server. This sample coding includes the procedure for uploading the client certificates to a storage system.

  • Download a file (back up encryption keys)

    Back up the encryption keys by using a REST API client. This sample coding includes the procedure for downloading an encryption backup file to a client. The supported storage systems for this sample coding are VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

  • Re-create a parity group (encrypt data)

    Delete an existing parity group, and then create a parity group for which encryption is enabled. This operation is performed as part of the procedure for encrypting existing data without changing the drive configuration. For details on the entire procedure, see the description of the flow of data encryption operations. The supported storage systems for this sample coding are VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

Code constructs such as the following are included in the previously listed operations:

  1. Processing that is run before the REST API is called
    • Generating request bodies in JSON format
    • Creating form data
    • Specifying request headers (for the default HTTP headers or for the custom HTTP headers)
    • Setting user authentication information (for authentication by using a user ID and a password, or for authentication by using session-based authentication)
    • Getting the URLs of the resources (when object IDs are not specified or when object IDs that are obtained from the operation results are specified, or when fixed object IDs such as those for single instances are specified)
  2. Processing to call the REST API
    • Getting information about the version of the REST API by performing a GET operation
    • Getting the action template by performing a GET operation
    • Changing object attributes by performing a PATCH operation
    • Running actions that use the action template by performing a POST operation
    • Running actions for objects by using the POST operation
    • Running actions for services by performing a POST operation
    • Creating objects by performing a POST operation
    • Running actions for objects by using the POST operation
    • Operations that require sessions to be generated on multiple devices (remote copy operation)
    • Deleting objects by performing a DELETE operation
  3. Processing that is run after the REST API is called
    • Outputting obtained information
    • Getting job execution results
    • Getting the URLs of the resources to which the operation results have been applied
    • Getting error codes
    • Outputting error messages
The following table shows an example of using each code construct included in the samples. For details about each code, see the description of each sample coding.

Code constructs

Example of using sample coding

Corresponding sample coding

Generating a request body in JSON format

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing.

Volume allocation

Operate a ShadowImage pair

Create an HDP volume.

Volume allocation

Create a ShadowImage pair.

Operate a ShadowImage pair

Creating form data

Upload the root certificate of the syslog server to which audit log files are to be transferred.

Upload the client certificate of the syslog server to which audit log files are to be transferred.

Upload files (specify the transfer destinations of audit log files)

Specifying request headers (for the default HTTP headers)

Define headers.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Operate a TrueCopy pair

Specifying request headers (for the custom HTTP headers)

Define headers.

Operate a ShadowImage pair

Setting user authentication information (for authentication by using a user ID and a password)

Generate a session.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Operate a TrueCopy pair

Setting user authentication information (for authentication by using session-based authentication)

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing.

Volume allocation

Operate a ShadowImage pair

Create an HDP volume.

Volume allocation

Split a ShadowImage pair.

Operate a ShadowImage pair

Getting the URLs of the resources (when object IDs are not specified)

Create an HDP volume. (BlockStorageAPI.ldevs)

Volume allocation

Create a host group. (BlockStorageAPI.host_groups)

Volume allocation

Create a ShadowImage pair. (BlockStorageAPI.local_copy_pairs)

Operate a ShadowImage pair

Getting the URLs of the resources (when object IDs that are obtained from the operation results are specified)

Create a host group. (BlockStorageAPI.affected_resource)

Volume allocation

Create a ShadowImage pair. (BlockStorageAPI.affected_resource)

Operate a ShadowImage pair

Getting the URLs of the resources (when fixed object IDs such as those for single instances are specified)

Specify the syslog server to which audit log files are to be transferred. (BlockStorageAPI.auditlog_syslog)

Send a test message to the syslog server to which audit log files are to be transferred. (BlockStorageAPI.auditlog_syslog_send_test)

Upload files (specify the transfer destinations of audit log files)

Download the encryption key backup file. (BlockStorageAPI.encryption_key_file_backup)

Download a file (back up encryption keys)

Getting information about the version of the REST API by performing the GET operation

Check the version of the REST API. (BlockStorageAPI.api_version)

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Operate a TrueCopy pair

Getting an object by performing the GET operation

Get HDP volume information. (BlockStorageAPI.ldev)

Volume allocation

Get information about a ShadowImage pair.

Operate a ShadowImage pair

Getting the action template by performing the GET operation

Split a ShadowImage pair. (BlockStorageAPI.split_local_copy _pair_template)

Operate a ShadowImage pair

Getting information about the job status by performing the GET operation

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Define the function for getting status changes for asynchronous processing.

Operate a TrueCopy pair

Changing the object attribute by performing the PATCH operation

Change the host mode.

Volume allocation

Running actions that use the action template by performing a POST operation

Split a ShadowImage pair. (BlockStorageAPI.split_local_copy_pair)

Operate a ShadowImage pair

Running actions for objects by using the POST operation

Send a test message to the syslog server to which audit log files are to be transferred.

Upload files (specify the transfer destinations of audit log files)

Running actions for services by performing a POST operation

Lock resources.

Unlock resources.

Operate a TrueCopy pair

Creating objects by performing a POST operation

Create an HDP volume. (BlockStorageAPI.ldevs)

Register the WWN of the host. (BlockStorageAPI.host_wwns)

Create a host group. (BlockStorageAPI.host_groups)

Set an LU path. (BlockStorageAPI.luns)

Volume allocation

Create a ShadowImage pair. (BlockStorageAPI.local_copy_pairs)

Operate a ShadowImage pair

Running actions for objects by using the POST operation

Upload the root certificate of the syslog server to which audit log files are to be transferred.

Upload the client certificate of the syslog server to which audit log files are to be transferred.

Upload files (specify the transfer destinations of audit log files)

Operations that require sessions to be generated on multiple devices (remote copy operation)

Create a TrueCopy pair.

Operate a TrueCopy pair

Deleting objects by performing a DELETE operation

Discard the session.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Operate a TrueCopy pair

Outputting the obtained information

Get HDP volume information.

Volume allocation

Get information about a ShadowImage pair.

Operate a ShadowImage pair

Getting the job execution results

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing. (BlockStorageAPI.job)

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Define the function for getting status changes for asynchronous processing.

Operate a TrueCopy pair

Getting the URLs of the resources to which the operation results have been applied

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Define the function for getting status changes for asynchronous processing.

Operate a TrueCopy pair

Getting error codes

Define functions for issuing an HTTP request and for verifying the status of asynchronous processing.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Define the function for getting status changes for asynchronous processing.

Operate a TrueCopy pair

Outputting error messages

Output error messages.

Volume allocation

Operate a ShadowImage pair

Register remote storage system information

Operate a TrueCopy pair

Structure of sample coding

The following operations are shared by the samples. These operations are implemented as functions, which are called and executed by the main operation. For details on each function, see the section explaining the functions used in the sample coding.
  • Generating a URL (BlockStorageAPI class)

    Creates a URL to issue an HTTP request to the storage system.

  • Issuing an HTTP request and verify the status of the asynchronous processing (invoke_async_command)

    Issues an HTTP request, verifies whether the execution results of the asynchronous processing have been applied, and then returns the result.

  • Getting status changes for asynchronous processing (wait_until_jobstatus_is_changed)

    Verifies that jobs have moved to the status specified in the parameter, and then returns the result.

Sample coding files

The following describes files that are provided as sample coding and their content:
  • provisioning.py

    This file contains sample coding for volume allocation.

  • local_copy.py

    This file contains sample coding for ShadowImage pair operations.

  • register_remote_storage.py

    This file contains sample coding for registering remote storage system information.

  • synchronous_remote_copy.py

    This file contains sample coding for TrueCopy pair operations.

  • auditlog_syslog_server_setting.py

    This file contains sample coding for uploading files (specifying the transfer destinations of audit log files).

  • backup_encryption_keys.py

    This file contains sample coding for downloading a file (backing up encryption keys).

  • recreate_parity_group.py

    This file contains sample coding for re-creating a parity group (encrypting data).

  • block_storage_api.py

    This file defines the BlockStorageAPI class.

  • rest_server_param.py

    This file defines information about the server where the REST API server is installed.

  • storage_param.py

    This file defines information about the local storage system.

  • remote_copy_param.py

    This file defines information about the remote and the local storage systems.

You can download the sample coding file from the following URL:
For VSP 5000 series storage systems:

http://SVP-IP-address/download/samplecode.zip

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

http://GUM-IP-address/download/restapi/samplecode.zip

Operation environment for sample coding

The samples are coded in the script language Python. Python code has excellent readability. Python is a versatile programming language widely used by Web service developers. Please download Python from the official Python website (https://www.python.org/) and configure the operation environment.

The code samples provided in this chapter use the standard library (json, sys, http.client, time, and traceback). Along with the standard library, you are also going to use the Requests library, which is a third-party library. Please download it from the web page for downloading the Requests library.

Note that the operations of the code samples described in this chapter have been checked in an environment of Python 3.7.5 and Requests 2.13.0.

Tip: To prevent errors that occur when the server certificate used for SSL communication between the REST API client and the storage system is a self-signed certificate, the sample coding specifies that verification of the server certificate is skipped when a request is issued.