Skip to main content

We've Moved!

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

Storage component management methods

The management API includes storage component management methods.

NoteIf you're working with a storage component that is configured with multiple retries and long timeouts, and if the endpoint for the storage component is unreachable, and if as a result you send multiple verification or activation requests to the endpoint, the MAPI Gateway service can become unresponsive.

If the MAPI Gateway service becomes unresponsive, use the System Management Services function Repair on it.

Activate storage components

When you define a storage component, it is marked as UNVERIFIED and not available to serve requests until you activate it. The method storage_component/activate lets you activate a storage component that is in the UNVERIFIED state.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/activate
Request structure

The request body is:

{
    "id": "uuid"
    }
ParameterRequiredTypeDescription
idYesUUIDThe UUID of the storage component.
Response structure

The response body is:

{
  "id": "uuid",
  "storageType": "type",
  "verified": true|false,
  "httpStatus": nnn,
  "errorCode": "code_text",
  "errorMessage": "message_text",
  "daysUntilCertificateExpiration": nnn,
  "state": "state"
}

Parameter

Type

Description

idUUIDThe UUID of the storage component.
storageType StringThe type of storage component:
  • AMAZON_S3: An Amazon Web Services S3-compatible node
  • HCP_S3: A Hitachi Content Platform node
  • HCPS_S3: An HCP S Series node
  • GENERIC_S3: An S3-compatible node
verifiedBooleanIf true, the storage component has been activated. If false, it is not verified and awaits administrative action.
httpStatus32-bit integerThe HTTP status code with which the storage component responded to your request. If 0, the storage component can't be reached. You can use other values to diagnose the issue.
errorCodeStringAny error code associated with the storage component.
errorMessageStringAny error message associated with the storage component.
daysUntilCertificate​Expiration32-bit integerNumber of days until the current HTTPS certificate expires.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This condition can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe MAPI metadata ID is not valid.
401 Unauthorized Access was denied because credentials are not valid.
404Not FoundThe specified storage component does not exist.
405 Method Not AllowedThe specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/activate

JSON request:

{
  "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6"
}

JSON response:

{
  "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
  "storageType": "AMAZON_S3",
  "verified": true,
  "httpStatus": 200,
  "errorCode": null,
  "errorMessage": null,
  "daysUntilCertificateExpiration": 364,
  "state": "ACTIVE"
}

Configure S3 settings

You can configure custom S3 settings for buckets. You can use the method /s3_settings/set to configure settings, then use the method /s3_settings/get to verify them.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/s3_settings/set
Request structure

The request body is:

{
  "maxFileSizeBytes": nnnnnnnnnn,
  "maxBucketsPerUser": buckets,
  "maxBulkDeleteRequestSizeBytes": size,
  "maxBulkDeleteRequestSizeCount": count
}
ParameterRequiredTypeDescription
maxFileSizeBytesNoIntegerThe maximum size, in bytes, of a single object that can be uploaded to an HCP for cloud scale system. Limit: 5 GB, default: 5 GB.
maxBucketsPerUserNoIntegerThe maximum number of buckets that a single user can create and own. No limit, default: 100 buckets.
maxBulkDeleteRequest​Size​BytesNoIntegerThe maximum, total size of objects, in bytes, allowed in a single bulk deletion. Default: 3 MB.
maxBulkDeleteRequest​Size​CountNoIntegerThe maximum, total number of objects allowed in a single bulk deletion. Default: 1000 objects.
Response structure

The response returns the same parameters as the request. The response body structure is:

{
  "maxFileSizeBytes": ,
  "maxBucketsPerUser": ,
  "maxBulkDeleteRequestSizeBytes": ,
  "maxBulkDeleteRequestSizeCount": 
}
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not Allowed The specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/s3_settings/set

JSON request:

{
  "maxBucketsPerUser": 1000
}

JSON response:

{
  "maxFileSizeBytes": 1099511627776,
  "maxBucketsPerUser": 1000,
  "maxBulkDeleteRequestSizeBytes": 3145728,
  "maxBulkDeleteRequestSizeCount": 1000
}

Configure storage component

You can configure a storage component, which exposes the S3 buckets for storage of data on various storage back-end systems. Buckets must already be created on the storage component before you can configure it. Ensure that the buckets are empty.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/create
Request structure

The request body is:

{
  "storageType": "type",
  "storageComponentConfig": {
    "label": "[label]",
    "host": "url",
    "https": {true|false},
    "port": [nnnnn],
    "bucket": "bucket_name",
    "region": "[region_name]",
    "authType": "[V2|V4]",
    "siteAffiliation": {
      "id": "uuid"
    },
    "accessKey": "key",
    "secretKey": "key",
    "useProxy": [true|false],
    "proxyHost": "[host_name]",
    "proxyPort": [nnnnn],
    "proxyUserName": "[user_name]",
    "proxyPassword": "[password]",
    "proxyDomain": "[domain_name]",
    "usePathStyleAlways": [true|false],
    "connectionTimeout": [ms],
    "socketTimeout": [ms],
    "connectionTTL": [ms],
    "maxConnections": [nnnnnnn],
    "userAgentPrefix": "[prefix]",
    "socketSendBufferSizeHint": [nnnnnnn],
    "socketRecvBufferSizeHint": [nnnnnnn],
    "managementProtocol": [http|https],
    "managementHost": "[host_name]",
    "managementUser": "[user_name]",
    "managementPassword": "[password]",
    "activateNow": [true|false]
  }
}
ParameterRequiredType Description
storageType YesStringThe type of storage component:
  • AMAZON_S3: An Amazon Web Services S3-compatible node
  • HCP_S3: A Hitachi Content Platform node
  • HCPS_S3: An HCP S Series node
  • GENERIC_S3: An S3-compatible node
storageComponent​ConfigYesListThe following storage component configuration values:
labelNoStringThe name of the storage component.
hostYesStringThe URL of the storage component back-end host domain.
httpsYesBooleanIf true, use an HTTPS connection to the back-end system. If false, use an HTTP connection. Default: false.
portNoIntegerHTTP port of back-end system.
bucketYesStringName of the bucket. The bucket must already exist.
regionNoStringThe S3 region. Default: us-west-2.
authTypeNoStringThe AWS Signature Version for authenticating all interactions with Amazon S3:
  • V2
  • V4

Default: V4.

siteAffiliationYesUUIDFor id, the UUID representing the storage component or the user.
accessKeyYesAccess key of the S3 credentials for access to the bucket.
secretKeyYesSecret key of the S3 credentials for access to the bucket.
useProxyNoBooleanIf true, a proxy server is defined. If false, it is not. If true, then values are required for proxyHost and proxyHost. Default: false.
proxyHostNoStringThe proxy host, if used.
proxyPortNoIntegerThe proxy port number, if used.
proxyUserNameNoStringThe proxy domain user name, if used.
proxyPasswordNoStringThe proxy domain password, if used.
proxyDomainNoStringThe proxy domain. Not supported.
usePathStyleAlwaysNoBooleanIf true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style. Default: true.
connectionTimeoutNo32-bit integerThe amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out.
socketTimeoutNo32-bit integerThe timeout value for reading from a connected socket.
connectionTTLNo64-bit integerThe connection time to live (TTL) for a request.
maxConnectionsNo32-bit integerThe maximum number of open HTTP connections to a storage component. If not specified, the defaults are:
  • HCPS_S3: 1024
  • HCP_S3: 50
  • AMAZON_S3: 50
  • GENERIC_S3: 50
userAgentPrefixNoStringThe HTTP user agent prefix header, used in requests to a storage component.
socketSendBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint.
socketRecvBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint.
managementProtocolYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
  • http
  • https

There is no default; if you use the parameter you must specify a value.

managementHostYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name.
managementUserYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The administrative user name credential. The account must have permissions to execute MAPI methods on the storage component.
managementPasswordYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The password credential. The account must have permissions to execute MAPI methods on the storage component.
activateNowNoBooleanIf true, activate the storage component immediately. If false, do not activate the storage component. Default: true.
Response structure

The response returns the same parameters as the request with the following additions. The response body structure is:

[
  {
    "id": "uuid",
    "storageType": "",
    "storageComponentConfig": {
      "label": "",
      "host": "",
      "https": ,
      "port": ,
      "bucket": "",
      "region": "",
      "authType": "",
      "siteAffiliation": {
        "id": ""
      },
      "useProxy": ,
      "proxyHost": "",
      "proxyPort": ,
      "proxyUserName": "",
      "proxyPassword": "",
      "proxyDomain": "",
      "usePathStyleAlways": ,
      "connectionTimeout": ,
      "socketTimeout": ,
      "connectionTTL": ,
      "maxConnections": ,
      "userAgentPrefix": "",
      "socketSendBufferSizeHint": ,
      "socketRecvBufferSizeHint": ,
      "managementProtocol": ,
      "managementHost": ,
      "readOnly": ,
      "state": "state"
    }
  }
]

Parameter

Type

Description

id UUID The ID of the storage component.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This condition can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe request is missing a valid storage component or parameter.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not AllowedThe specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/create

JSON request:

{
  "storageType": "AMAZON_S3",
  "storageComponentConfig": {
    "label": "Cloud AWS Bucket",
    "host": "URL of an existing storage component backend",
    "https": true,
    "port": 0,
    "bucket": "string",
    "region": "string",
    "authType": "V2",
    "siteAffiliation": {
      "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6"
    },
    "accessKey": "string",
    "secretKey": "string",
    "useProxy": true,
    "proxyHost": "string",
    "proxyPort": null,
    "proxyUserName": "string",
    "proxyPassword": "string",
    "proxyDomain": "string",
    "usePathStyleAlways": true,
    "connectionTimeout": null,
    "socketTimeout": null,
    "connectionTTL": null,
    "maxConnections": null,
    "userAgentPrefix": "string",
    "socketSendBufferSizeHint": null,
    "socketRecvBufferSizeHint": null,
    "activateNow": true
  }
}

JSON response:

[
  {
    "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
    "storageType": "AMAZON_S3",
    "storageComponentConfig": {
      "label": "Cloud AWS Bucket",
      "host": "URL of an existing storage component backend",
      "https": true,
      "port": 0,
      "bucket": "string",
      "region": "string",
      "authType": "V2",
      "siteAffiliation": {
        "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6"
      },
      "useProxy": true,
      "proxyHost": "string",
      "proxyPort": 0,
      "proxyUserName": "string",
      "proxyPassword": "string",
      "proxyDomain": "string",
      "usePathStyleAlways": true,
      "connectionTimeout": 0,
      "socketTimeout": 0,
      "connectionTTL": 0,
      "maxConnections": 50,
      "userAgentPrefix": "string",
      "socketSendBufferSizeHint": 0,
      "socketRecvBufferSizeHint": 0,
      "readOnly": true,
      "state": "ACTIVE"
    }
  }
]

Get S3 settings

You can retrieve the current S3 settings. You can use the method /s3_settings/set configures settings, then use the method /s3_settings/get to verify them.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/s3_settings/get
Request structure

Not applicable.

Response structure

The response body is:

{
  "maxFileSizeBytes": nnnnnnnnnn,
  "maxBucketsPerUser": buckets,
  "maxBulkDeleteRequestSizeBytes": size,
  "maxBulkDeleteRequestSizeCount": count
}
ParameterRequiredTypeDescription
maxFileSizeBytesNoIntegerThe maximum size, in bytes, of a single object that can be uploaded to an HCP for cloud scale system. Limit: 5 GB, default: 5 GB.
maxBucketsPerUserNoIntegerThe maximum number of buckets that a single user can create and own. No limit, default: 100 buckets.
maxBulkDeleteRequest​Size​BytesNoIntegerThe maximum, total size of objects, in bytes, allowed in a single bulk deletion. Default: 3 MB.
maxBulkDeleteRequest​Size​CountNoIntegerThe maximum, total number of objects allowed in a single bulk deletion. Default: 1000 objects.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not Allowed The specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/s3_settings/get

JSON response:

{
  "maxFileSizeBytes": 4294967296,
  "maxBucketsPerUser": 100,
  "maxBulkDeleteRequestSizeBytes": 3145728,
  "maxBulkDeleteRequestSizeCount": 1000
}

Get storage component capacity

The method storage_component/get_capacity retrieves capacity information for storage components, and if available the total capacity of the system.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/get_capacity
Request structure

Not applicable.

Response structure

The response body is:

[
  {
    "storageCapacities": {
      "uuid": {
        "availableBytes": nnnnn,
        "totalBytes": nnnnn,
        "usedBytes": nnnnn,
        "warnThreshold": nnnnn
      },
      .
      .
      .
      "aggregate": {
        "availableBytes": nnnnn,
        "totalBytes": nnnnn,
        "usedBytes": nnnnn,
        "warnThreshold": nnnnn
      }
    }
  }
]

Parameter

Type

Description

id UUID The ID of the storage component.
availableBytes 64-bit integerThe available capacity of the storage component in bytes. A returned value of -1 means that the value is not available.
totalBytes64-bit integerThe total capacity of the storage component in bytes. A returned value of -1 means that the value is not available.
usedBytes64-bit integerThe used capacity of the storage component in bytes. A returned value of -1 means that the value is not available.
warnThreshold64-bit integerThe threshold for a capacity warning, as compared with the value availableBytes. A returned value of -1 means that the value is not available.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/get_capacity

JSON response:

[
  {
    "storageCapacities": {
      "494bc750-5f7e-42f3-af7d-64f1024ce2e6": {
        "availableBytes": 1647056204595200,
        "totalBytes": 1993620471152640,
        "usedBytes": 346564266557440,
        "warnThreshold": 598086141345792
      },
      "1954051f-fa79-4e69-bec3-c933bc7dde2a": {
        "availableBytes": -1,
        "totalBytes": -1,
        "usedBytes": -1,
        "warnThreshold": -1
      },
      "aggregate": {
        "availableBytes": -1,
        "totalBytes": -1,
        "usedBytes": -1,
        "warnThreshold": -1
      }
    }
  }
]

List storage component alerts

You can retrieve a list of active storage component alerts. Alerts are triggered by events and remain active until the condition that caused the event is removed. For example, HCP for cloud scale sends an alert when a storage component is unavailable or its certificate is about to expire. When the event is resolved, the alert is cleared.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/alert/list
Request structure

Not applicable.

Response structure

The response body is:

[
  {
    "id": "uuid",
    "timestamp": date_time,
    "category": "STORAGECOMPONENT",
    "description": "alert_description"
  }
  .
  .
  .
]

Parameter

Type

Description

id UUID The ID of the storage component.
timestamp 64-bit integerThe date and time, in milliseconds since 00:00:00 on 1 January 1970 GMT, when the alert was generated.
categoryStringAlert category:
  • STORAGECOMPONENT
descriptionStringThe text of the alert.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/alert/list

JSON response:

[
  {
    "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
    "timestamp": 1571912640205,
    "category": "STORAGECOMPONENT",
    "description": "string"
  }
]

List storage components

The method storage_component/list retrieves a list of all storage components created in the HCP for cloud scale system along with their component settings.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/list
Request structure

Not applicable.

Response structure

The response body is:

[
  {
    "id": "uuid",
    "storageType": "enum",
    "storageComponentConfig": {
      "label": "label",
      "host": "url",
      "https": true|false,
      "port": nnnnn,
      "bucket": "bucket_name",
      "region": "region_name",
      "authType": "V2|V4",
      "siteAffiliation": {
        "id": "uuid"
      },
      "useProxy": true|false,
      "proxyHost": "host_name",
      "proxyPort": nnnnn,
      "proxyUserName": "user_name",
      "proxyPassword": "password",
      "proxyDomain": "domain_name",
      "usePathStyleAlways": true|false,
      "connectionTimeout": ms,
      "socketTimeout": ms,
      "connectionTTL": ms,
      "maxConnections": nnnnnnn,
      "userAgentPrefix": "prefix",
      "socketSendBufferSizeHint": nnnnnnn,
      "socketRecvBufferSizeHint": nnnnnnn,
      "managementProtocol": http|https,
      "managementHost": "host_name",
      "readOnly": true|false,
      "state": "state"
    }
  }
]

Parameter

Type

Description

id UUID The ID of the storage component.
storageType EnumThe type of storage component:
  • AMAZON_S3: An Amazon Web Services S3-compatible node
  • HCP_S3: A Hitachi Content Platform node
  • HCPS_S3: An HCP S Series node
  • GENERIC_S3: An S3-compatible node
storageComponentConfigListThe following storage component configuration values:
labelStringThe name of the storage component.
hostStringThe URL of the storage component back-end host domain.
httpsBooleantrue for HTTPS connection to back-end system, false for HTTP.
port32-bit integerHTTP port to back-end system.
bucketStringThe name of the bucket.
regionStringThe S3 region.
authTypeStringAWS Signature Version, used for authenticating all interactions with Amazon S3:
  • V2
  • V4
siteAffiliationUUIDThe value of id, a UUID representing the storage component or the user.
useProxyBooleanIf true, a proxy server is defined. If false, a proxy server is not defined.
proxyHostStringThe proxy host, if used; otherwise, null.
proxyPort32-bit integerThe proxy port number, if used; otherwise, null.
proxyUserNameStringThe proxy domain user name, if used; otherwise, null.
proxyPasswordStringThe proxy domain password, if used; otherwise, null).
proxyDomainStringThe proxy domain, if used; otherwise, null.
usePathStyleAlwaysBooleanIf true, use path-style syntax to send requests to the back-end system; if false, use virtual-hosted style.
connectionTimeout32-bit integerThe amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out.
socketTimeout32-bit integerThe timeout value for reading from a connected socket.
connectionTTL64-bit integerThe connection time to live (TTL) for a request.
maxConnections32-bit integerThe maximum number of open HTTP connections to a storage component.
userAgentPrefixStringThe HTTP user agent prefix header, used in requests to a storage component.
socketSendBuffer​Size​Hint32-bit integerThe size hint, in bytes, for the low-level TCP send buffer.
socketRecvBuffer​Size​Hint32-bit integerThe size hint, in bytes, for the low-level TCP receive buffer.
managementProtocolStringThe communication protocol for HCP S Series MAPI requests:
  • http
  • https
managementHostStringThe host managing an HCP S Series storage component.
readOnlyBooleanIf true, the storage component is marked as read-only. If false, the storage component is available for reading and writing data.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not AllowedThe specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/list

JSON response:

[
  {
    "id": "8bff981b-5894-43ce-bd41-5a6f548cc241",
    "storageType": "GENERIC_S3",
    "storageComponentConfig": {
      "label": null,
      "host": "172.19.54.102",
      "https": false,
      "port": 9000,
      "bucket": "samplebucket",
      "region": "us-west-2",
      "authType": null,
      "siteAffiliation": {
        "id": "19b96ae2-38dd-4686-b298-b5bebe173e96"
      },
      "useProxy": false,
      "proxyHost": null,
      "proxyPort": null,
      "proxyUserName": null,
      "proxyPassword": null,
      "proxyDomain": null,
      "usePathStyleAlways": true,
      "connectionTimeout": null,
      "socketTimeout": null,
      "connectionTTL": null,
      "maxConnections": 50,
      "userAgentPrefix": null,
      "socketSendBufferSizeHint": null,
      "socketRecvBufferSizeHint": null,
      "managementProtocol": null,
      "managementHost": null,
      "readOnly": false,
      "state": "ACTIVE"
    }
  }
]

Patch storage component configuration

You can update the configuration of specific storage component settings. Use the method /storage_component/list to verify existing settings or changes. Use the method /storage_component/update to update all settings.

HTTP request syntax (URI)
PATCH https://host_ip:9099/mapi/v1/storage_component/update
Request structure

The full request body is:

{
  "id": "uuid",
  "storageType": "type",
  "storageComponentConfig": {
    "label": "[label]",
    "host": "url",
    "https": {true|false},
    "port": [nnnnn],
    "bucket": "bucket_name",
    "region": "[region_name]",
    "authType": "[V2|V4]",
    "siteAffiliation": {
      "id": "uuid"
    },
    "accessKey": "key",
    "secretKey": "key",
    "useProxy": [true|false],
    "proxyHost": "[host_name]",
    "proxyPort": [nnnnn],
    "proxyUserName": "[user_name]",
    "proxyPassword": "[password]",
    "proxyDomain": "[domain_name]",
    "usePathStyleAlways": [true|false],
    "connectionTimeout": [ms],
    "socketTimeout": [ms],
    "connectionTTL": [ms],
    "maxConnections": [nnnnnnn],
    "userAgentPrefix": "[prefix]",
    "socketSendBufferSizeHint": [nnnnnnn],
    "socketRecvBufferSizeHint": [nnnnnnn],
    "managementProtocol": [http|https],
    "managementHost": "[host_name]",
    "managementUser": "[user_name]",
    "managementPassword": "[password]",
    "readOnly": 
  }
}
ParameterRequiredType Description
id YesUUIDThe ID of the storage component.
storageComponent​ConfigNoListThe following storage component configuration values as needed:
labelNoStringThe name of the storage component.
hostNoStringThe URL of the storage component back-end host domain.
httpsNoBooleanIf true, use an HTTPS connection to the back-end system. If false, use an HTTP connection.
portNo32-bit integerHTTP port of back-end system.
bucketNoStringThe name of the bucket. The bucket must already exist.
regionNoStringThe S3 region.
authTypeNoStringThe AWS Signature Version for authenticating all interactions with Amazon S3:
  • V2
  • V4
siteAffiliationNoUUIDFor id, the UUID representing the storage component or the user.
accessKeyNoStringThe access key of the S3 credentials for access to the bucket.
secretKeyNoStringThe secret key of the S3 credentials for access to the bucket.
useProxyNoBooleanIf true, a proxy server is defined. If false, a proxy server is not defined. If true, then you must provide values for proxyHost and proxyHost.
proxyHostNoStringThe proxy host, if used.
proxyPortNo32-bit integerThe proxy port number, if used.
proxyUserNameNoStringThe proxy domain user name, if used.
proxyPasswordNoStringThe proxy domain password, if used.
proxyDomainNoStringThe proxy domain. This is not supported.
usePathStyleAlwaysNoBooleanIf true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style.
connectionTimeoutNo32-bit integerThe amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out.
socketTimeoutNo32-bit integerThe timeout value for reading from a connected socket.
connectionTTLNo64-bit integerThe connection time to live (TTL) for a request.
maxConnectionsNo32-bit integerThe maximum number of open HTTP connections to a storage component.
userAgentPrefixNoStringThe HTTP user agent prefix header, used in requests to a storage component.
socketSendBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint.
socketRecvBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint.
managementProtocolYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
  • http
  • https

There is no default; if you use the parameter you must specify a value.

managementHostYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name.
managementUserYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The administrative user name credential. The account must have permissions to execute MAPI methods on the storage component.
managementPasswordYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The password credential. The account must have permissions to execute MAPI methods on the storage component.
readOnlyNoBooleanIf true, objects can be read and deleted but writes aren't allowed. If false, writes are allowed.
Response structure

The response returns the same parameters as the request with the following additions. The response body structure is:

[
  {
    "id": "uuid",
    "storageType": "",
    "storageComponentConfig": {
      "label": "",
      "host": "",
      "https": ,
      "port": ,
      "bucket": "",
      "region": "",
      "authType": "",
      "siteAffiliation": {
        "id": ""
      },
      "useProxy": ,
      "proxyHost": "",
      "proxyPort": ,
      "proxyUserName": "",
      "proxyPassword": "",
      "proxyDomain": "",
      "usePathStyleAlways": ,
      "connectionTimeout": ,
      "socketTimeout": ,
      "connectionTTL": ,
      "maxConnections": ,
      "userAgentPrefix": "",
      "socketSendBufferSizeHint": ,
      "socketRecvBufferSizeHint": ,
      "managementProtocol": ,
      "managementHost": ,
      "readOnly": ,
      "state": "state"
    }
  }
]

Parameter

Type

Description

id UUID The ID of the storage component.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This condition can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe request is missing a valid storage component or parameter.
401 Unauthorized Access was denied because credentials are not valid.
404Not FoundThe specified storage component was not found.
405 Method Not AllowedThe specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

PATCH https://10.10.24.195:9099/mapi/v1/storage_component/update

JSON request:

{
  "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
  "storageComponentConfig": {
    "label": "Test cloud"
  }
}

JSON response:

[
  {
    "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
    "storageType": "AMAZON_S3",
    "storageComponentConfig": {
      "label": "Test cloud",
      "host": "172.19.54.102",
      "https": false,
      "port": 9000,
      "bucket": "testbucket",
      "region": "us-west-2",
      "authType": null,
      "siteAffiliation": {
        "id": "19546ae2-38dd-4686-b298-b5beb9173e96"
      },
      "useProxy": false,
      "proxyHost": null,
      "proxyPort": null,
      "proxyUserName": null,
      "proxyPassword": null,
      "proxyDomain": null,
      "usePathStyleAlways": true,
      "connectionTimeout": null,
      "socketTimeout": null,
      "connectionTTL": null,
      "maxConnections": null,
      "userAgentPrefix": null,
      "socketSendBufferSizeHint": null,
      "socketRecvBufferSizeHint": null,
      "readOnly": false,
      "state": "ACTIVE"
    }
  }
]

Set storage component state

You can set the state of a storage component to either ACTIVE or INACTIVE.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/update_state
Request structure

The request body is:

{
  "id": "uuid",
  "storageComponentState": "{ACTIVE|INACTIVE}"
}
ParameterRequiredType Description
id YesUUIDThe ID of the storage component.
storageComponent​StateYesStringThe storage component state:
  • ACTIVE: Available to serve requests.
  • INACTIVE: Not available to serve requests (administrative pause).
Response structure

The response body structure is:

[
  {
    "id": "uuid",
    "storageType": "",
    "storageComponentConfig": {
      "label": "",
      "host": "",
      "https": ,
      "port": ,
      "bucket": "",
      "region": "",
      "authType": "",
      "siteAffiliation": {
        "id": ""
      },
      "useProxy": ,
      "proxyHost": "",
      "proxyPort": ,
      "proxyUserName": "",
      "proxyPassword": "",
      "proxyDomain": "",
      "usePathStyleAlways": ,
      "connectionTimeout": ,
      "socketTimeout": ,
      "connectionTTL": ,
      "maxConnections": ,
      "userAgentPrefix": "",
      "socketSendBufferSizeHint": ,
      "socketRecvBufferSizeHint": ,
      "managementProtocol": ,
      "managementHost": ,
      "readOnly": ,
      "state": "state"
    }
  }
]

Parameter

Type

Description

id UUID The ID of the storage component.
storageType EnumThe type of storage component:
  • AMAZON_S3: An Amazon Web Services S3-compatible node
  • HCP_S3: A Hitachi Content Platform node
  • HCPS_S3: An HCP S Series node
  • GENERIC_S3: An S3-compatible node
storageComponentConfigListThe following storage component configuration values:
labelStringThe name of the storage component.
hostStringThe URL of the storage component back-end host domain.
httpsBooleantrue for HTTPS connection to back-end system, false for HTTP.
port32-bit integerHTTP port to back-end system.
bucketStringThe name of the bucket.
regionStringThe S3 region.
authTypeStringAWS Signature Version, used for authenticating all interactions with Amazon S3:
  • V2
  • V4
siteAffiliationUUIDThe value of id, a UUID representing the storage component or the user.
useProxyBooleanIf true, a proxy server is defined. If false, a proxy server is not defined.
proxyHostStringThe proxy host, if used; otherwise, null.
proxyPort32-bit integerThe proxy port number, if used; otherwise, null.
proxyUserNameStringThe proxy domain user name, if used; otherwise, null.
proxyPasswordStringThe proxy domain password, if used; otherwise, null).
proxyDomainStringThe proxy domain, if used; otherwise, null.
usePathStyleAlwaysBooleanIf true, use path-style syntax to send requests to the back-end system; if false, use virtual-hosted style.
connectionTimeout32-bit integerThe amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out.
socketTimeout32-bit integerThe timeout value for reading from a connected socket.
connectionTTL64-bit integerThe connection time to live (TTL) for a request.
maxConnections32-bit integerThe maximum number of open HTTP connections to a storage component.
userAgentPrefixStringThe HTTP user agent prefix header, used in requests to a storage component.
socketSendBuffer​Size​Hint32-bit integerThe size hint, in bytes, for the low-level TCP send buffer.
socketRecvBuffer​Size​Hint32-bit integerThe size hint, in bytes, for the low-level TCP receive buffer.
managementProtocolStringThe communication protocol for HCP S Series MAPI requests:
  • http
  • https
managementHostStringThe host managing an HCP S Series storage component.
readOnlyBooleanIf true, the storage component is marked as read-only. If false, the storage component is available for reading and writing data.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe request is missing a valid storage component or parameter.
401 Unauthorized Access was denied because credentials are not valid.
404Not FoundThe specified storage component was not found.
405 Method Not AllowedThe specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/update_state

JSON request:

{
  "id": "8bff981b-5894-43ce-bd41-5a6f558cc241",
  "storageComponentState": "INACTIVE"
}

JSON response:

[
  {
  "id": "8bff981b-5894-43ce-bd41-5a6f558cc241",
  "storageType": "GENERIC_S3",
  "storageComponentConfig": {
    "label": null,
    "host": "172.19.54.102",
    "https": false,
    "port": 9000,
    "bucket": "samplebucket",
    "region": "us-west-2",
    "authType": null,
    "siteAffiliation": {
      "id": "19b96ae2-38ef-4686-b298-b5bebe173e96"
    },
    "useProxy": false,
    "proxyHost": null,
    "proxyPort": null,
    "proxyUserName": null,
    "proxyPassword": null,
    "proxyDomain": null,
    "usePathStyleAlways": true,
    "connectionTimeout": null,
    "socketTimeout": null,
    "connectionTTL": null,
    "maxConnections": null,
    "userAgentPrefix": null,
    "socketSendBufferSizeHint": null,
    "socketRecvBufferSizeHint": null,
    "managementProtocol": ,
    "managementHost": ,
    "readOnly": false,
    "state": "INACTIVE"
  }
}
]

Test storage component access

The method storage_component/test tests whether a storage component is accessible.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/test
Request structure

The request body is:

{
  "id": "uuid"
}
ParameterRequiredType Description
id YesUUIDThe ID of the storage component.
Response structure

The response body is:

{
  "id": "uuid",
  "storageType": "type",
  "verified": true|false,
  "httpStatus": nnn,
  "errorCode": "code_text",
  "errorMessage": "error_text",
  "daysUntilCertificateExpiration": nnn,
  "state": "state"
}

Parameter

Type

Description

id UUID The ID of the storage component.
storageType StringThe type of storage component:
  • AMAZON_S3: An Amazon Web Services S3-compatible node
  • HCP_S3: A Hitachi Content Platform node
  • HCPS_S3: An HCP S Series node
  • GENERIC_S3: An S3-compatible node
verifiedBooleanIf true, the storage component is activated. If false, it has not been verified and is awaiting for an administrative action.
httpStatusIntegerThe HTTP status code the storage component responded with. If 0, the storage component can't be reached. Otherwise, the code can help explain why it can't be verified.
errorCodeStringAny error codes associated with the storage component; otherwise, null.
errorMessageStringAny error messages associated with the storage component; otherwise, null.
daysUntilCertificate​Expiration32-bit integerThe number of days left until the current HTTP certificate expires.
stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This condition can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe request is missing a valid storage component ID.
401 Unauthorized Access was denied because credentials are not valid.
404Not FoundThe specified storage component was not found.
405 Method Not Allowed The specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/test

JSON request:

{
  "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6"
}

JSON response:

{
  "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
  "storageType": "AMAZON_S3",
  "verified": true,
  "httpStatus": 200,
  "errorCode": null,
  "errorMessage": null,
  "daysUntilCertificateExpiration": null,
  "state": "ACTIVE"
}

Update storage component configuration

You can update the configuration of a storage component, which overwrites the existing settings. Use the method /storage_component/list to verify existing settings or changes. Use the method PATCH /storage_component/update to update specific settings.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/storage_component/update
Request structure

The request body is:

{
  "id": "uuid",
  "storageComponentConfig": {
    "label": "[label]",
    "host": "url",
    "https": {true|false},
    "port": [nnnnn],
    "bucket": "bucket_name",
    "region": "[region_name]",
    "authType": "[V2|V4]",
    "siteAffiliation": {
      "id": "uuid"
    },
    "accessKey": "key",
    "secretKey": "key",
    "useProxy": [true|false],
    "proxyHost": "[host_name]",
    "proxyPort": [nnnnn],
    "proxyUserName": "[user_name]",
    "proxyPassword": "[password]",
    "proxyDomain": "[domain_name]",
    "usePathStyleAlways": [true|false],
    "connectionTimeout": [ms],
    "socketTimeout": [ms],
    "connectionTTL": [ms],
    "maxConnections": [nnnnnnn],
    "userAgentPrefix": "[prefix]",
    "socketSendBufferSizeHint": [nnnnnnn],
    "socketRecvBufferSizeHint": [nnnnnnn],
    "managementProtocol": [http|https],
    "managementHost": "[host_name]",
    "managementUser": "[user_name]",
    "managementPassword": "[password]",
    "readOnly": {true|false}
  }
}
ParameterRequiredType Description
id YesUUIDThe ID of the storage component.
storageComponent​ConfigYesListThe following storage component configuration values:
labelNoStringThe name of the storage component.
hostYesStringThe URL of the storage component back-end host domain.
httpsYesBooleanIf true, use an HTTPS connection to the back-end system. If false, use an HTTP connection to the back-end system. Default: false.
portNoIntegerThe HTTP port of the back-end system.
bucketYesStringThe name of the bucket. The bucket must already exist.
regionNoStringThe S3 region. Default: us-west-2.
authTypeNoStringThe AWS Signature Version for authenticating all interactions with Amazon S3:
  • V2
  • V4
siteAffiliationYesUUIDFor id, the UUID representing the storage component or the user.
accessKeyYesThe access key of the S3 credentials for access to the bucket.
secretKeyYesThe secret key of the S3 credentials for access to the bucket.
useProxyNoBooleanIf true, a proxy server is defined. If false, a proxy server is not defined. If true, then values are required for proxyHost and proxyHost. Default: false.
proxyHostNoStringThe proxy host, if used.
proxyPortNoIntegerThe proxy port number, if used.
proxyUserNameNoStringThe proxy domain user name, if used.
proxyPasswordNoStringThe proxy domain password, if used.
proxyDomainNoStringThe proxy domain. This is not supported.
usePathStyleAlwaysNoBooleanIf true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style. Default: true.
connectionTimeoutNo32-bit integerThe amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out.
socketTimeoutNo32-bit integerThe timeout value for reading from a connected socket.
connectionTTLNo64-bit integerThe connection time to live (TTL) for a request.
maxConnectionsNo32-bit integerThe maximum number of open HTTP connections to a storage component. If not specified, the defaults are:
  • HCPS_S3: 1024
  • HCP_S3: 50
  • AMAZON_S3: 50
  • GENERIC_S3: 50
userAgentPrefixNoStringThe HTTP user agent prefix header, used in requests to a storage component.
socketSendBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint.
socketRecvBuffer​Size​HintNo32-bit integerThe size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint.
managementProtocolYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
  • http
  • https

There is no default; if you use the parameter you must specify a value.

managementHostYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name.
managementUserYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The administrative user name credential. The account must have permissions to execute MAPI methods on the storage component.
managementPasswordYes (for HCP S Series)StringRequired for an HCP S Series storage component; do not provide for other storage component types. The password credential. The account must have permissions to execute MAPI methods on the storage component.
readOnlyNoBooleanIf true, objects can be read and removed but writes aren't allowed. If false, writes are allowed.
Response structure

The response returns the same parameters as the request with one addition. The response body structure is:

[
  {
    "id": "",
    "storageType": "",
    "storageComponentConfig": {
      "label": "",
      "host": "",
      "https": ,
      "port": ,
      "bucket": "",
      "region": "",
      "authType": "",
      "siteAffiliation": {
        "id": ""
      },
      "useProxy": ,
      "proxyHost": "",
      "proxyPort": ,
      "proxyUserName": "",
      "proxyPassword": "",
      "proxyDomain": "",
      "usePathStyleAlways": ,
      "connectionTimeout": ,
      "socketTimeout": ,
      "connectionTTL": ,
      "maxConnections": ,
      "userAgentPrefix": "",
      "socketSendBufferSizeHint": ,
      "socketRecvBufferSizeHint": ,
      "managementProtocol": ,
      "managementHost": ,
      "readOnly": true|false,
      "state": "state"
    }
  }
]

Parameter

Type

Description

stateEnumThe state of the storage component, indicating its availability to serve requests:
  • ACTIVE: The storage component is ready for requests.
  • INACTIVE: The storage component is on an administrative pause.
  • INACCESSIBLE: The storage component is not accessible. This can be caused by network, authentication, or certificate errors.
  • UNVERIFIED: The storage component has not been activated or has failed to activate.
Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400Bad RequestThe request is missing a valid storage component or parameter.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not Allowed The specified HTTP method is not allowed for a storage component. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/storage_component/update

JSON request:

{
  "storageType": "AMAZON_S3",
  "storageComponentConfig": {
    "label": "Cloud AWS Bucket",
    "host": "172.19.54.102",
    "https": false,
    "port": 9000,
    "bucket": "testbucket",
    "region": "us-west-2",
    "authType": "V2",
    "siteAffiliation": {
      "id": "3fa85f64-1024-4562-bffc-2c963f66afa6"
    },
    "useProxy": false,
    "proxyHost": ,
    "proxyPort": ,
    "proxyUserName": ,
    "proxyPassword": ,
    "proxyDomain": ,
    "usePathStyleAlways": true,
    "connectionTimeout": ,
    "socketTimeout": ,
    "connectionTTL": ,
    "maxConnections": ,
    "userAgentPrefix": ,
    "socketSendBufferSizeHint": ,
    "socketRecvBufferSizeHint": ,
    "readOnly": 
  }
}

JSON response:

[
  {
    "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6",
    "storageType": "AMAZON_S3",
    "storageComponentConfig": {
      "label": "Cloud AWS Bucket",
      "host": "URL of an existing storage component backend",
      "https": false,
      "port": 0,
      "bucket": "string",
      "region": "string",
      "authType": "V2",
      "siteAffiliation": {
        "id": "3fa85f64-1024-4562-b3fc-2c963f66afa6"
      },
      "useProxy": true,
      "proxyHost": "string",
      "proxyPort": 0,
      "proxyUserName": "string",
      "proxyPassword": "string",
      "proxyDomain": "string",
      "usePathStyleAlways": true,
      "connectionTimeout": 0,
      "socketTimeout": 0,
      "connectionTTL": 0,
      "maxConnections": 50,
      "userAgentPrefix": "string",
      "socketSendBufferSizeHint": 0,
      "socketRecvBufferSizeHint": 0,
      "readOnly": false,
      "state": "ACTIVE"
    }
  }
]