Storage component management methods
The management API includes storage component management methods.
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.
POST https://host_ip:9099/mapi/v1/storage_component/activate
The request body is:
{ "id": "uuid" }
Parameter | Required | Type | Description |
id | Yes | UUID | The UUID of the storage component. |
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 |
id | UUID | The UUID of the storage component. |
storageType | String | The type of storage component:
|
verified | Boolean | If true, the storage component has been activated. If false, it is not verified and awaits administrative action. |
httpStatus | 32-bit integer | The 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. |
errorCode | String | Any error code associated with the storage component. |
errorMessage | String | Any error message associated with the storage component. |
daysUntilCertificateExpiration | 32-bit integer | Number of days until the current HTTPS certificate expires. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The MAPI metadata ID is not valid. |
401 | Unauthorized | Access was denied because credentials are not valid. |
404 | Not Found | The specified storage component does not exist. |
405 | Method Not Allowed | The specified HTTP method is not allowed for a storage component. Resend using POST. |
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.
POST https://host_ip:9099/mapi/v1/s3_settings/set
The request body is:
{ "maxFileSizeBytes": nnnnnnnnnn, "maxBucketsPerUser": buckets, "maxBulkDeleteRequestSizeBytes": size, "maxBulkDeleteRequestSizeCount": count }
Parameter | Required | Type | Description |
maxFileSizeBytes | No | Integer | The 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. |
maxBucketsPerUser | No | Integer | The maximum number of buckets that a single user can create and own. Limit: 1000 buckets, default: 100 buckets. |
maxBulkDeleteRequestSizeBytes | No | Integer | The maximum, total size of objects, in bytes, allowed in a single bulk deletion. Default: 3 MB. |
maxBulkDeleteRequestSizeCount | No | Integer | The maximum, total number of objects allowed in a single bulk deletion. Default: 1000 objects. |
The response returns the same parameters as the request. The response body structure is:
{ "maxFileSizeBytes": , "maxBucketsPerUser": , "maxBulkDeleteRequestSizeBytes": , "maxBulkDeleteRequestSizeCount": }
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. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/create
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] } }
Parameter | Required | Type | Description |
storageType | Yes | String | The type of storage component:
|
storageComponentConfig | Yes | List | The following storage component configuration values: |
label | No | String | The name of the storage component. |
host | Yes | String | The URL of the storage component back-end host domain. |
https | Yes | Boolean | If true, use an HTTPS connection to the back-end system. If false, use an HTTP connection. Default: false. |
port | No | Integer | HTTP port of back-end system. |
bucket | Yes | String | Name of the bucket. The bucket must already exist. |
region | No | String | The S3 region. Default: us-west-2. |
authType | No | String | The AWS Signature Version for authenticating all interactions with Amazon S3:
Default: V4. |
siteAffiliation | Yes | UUID | For id, the UUID representing the storage component or the user. |
accessKey | Yes | Access key of the S3 credentials for access to the bucket. | |
secretKey | Yes | Secret key of the S3 credentials for access to the bucket. | |
useProxy | No | Boolean | If true, a proxy server is defined. If false, it is not. If true, then values are required for proxyHost and proxyHost. Default: false. |
proxyHost | No | String | The proxy host, if used. |
proxyPort | No | Integer | The proxy port number, if used. |
proxyUserName | No | String | The proxy domain user name, if used. |
proxyPassword | No | String | The proxy domain password, if used. |
proxyDomain | No | String | The proxy domain. Not supported. |
usePathStyleAlways | No | Boolean | If true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style. Default: true. |
connectionTimeout | No | 32-bit integer | The amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out. |
socketTimeout | No | 32-bit integer | The timeout value for reading from a connected socket. |
connectionTTL | No | 64-bit integer | The connection time to live (TTL) for a request. |
maxConnections | No | 32-bit integer | The maximum number of open HTTP connections to a storage component. If not specified, the defaults are:
|
userAgentPrefix | No | String | The HTTP user agent prefix header, used in requests to a storage component. |
socketSendBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint . |
socketRecvBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint . |
managementProtocol | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
There is no default; if you use the parameter you must specify a value. |
managementHost | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name. |
managementUser | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
managementPassword | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
activateNow | No | Boolean | If true, activate the storage component immediately. If false, do not activate the storage component. Default: true. |
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. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The 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. |
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.
POST https://host_ip:9099/mapi/v1/s3_settings/get
Not applicable.
The response body is:
{ "maxFileSizeBytes": nnnnnnnnnn, "maxBucketsPerUser": buckets, "maxBulkDeleteRequestSizeBytes": size, "maxBulkDeleteRequestSizeCount": count }
Parameter | Required | Type | Description |
maxFileSizeBytes | No | Integer | The 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. |
maxBucketsPerUser | No | Integer | The maximum number of buckets that a single user can create and own. Limit: 1000 buckets, default: 100 buckets. |
maxBulkDeleteRequestSizeBytes | No | Integer | The maximum, total size of objects, in bytes, allowed in a single bulk deletion. Default: 3 MB. |
maxBulkDeleteRequestSizeCount | No | Integer | The maximum, total number of objects allowed in a single bulk deletion. Default: 1000 objects. |
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. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/get_capacity
Not applicable.
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 integer | The available capacity of the storage component in bytes. A returned value of -1 means that the value is not available. |
totalBytes | 64-bit integer | The total capacity of the storage component in bytes. A returned value of -1 means that the value is not available. |
usedBytes | 64-bit integer | The used capacity of the storage component in bytes. A returned value of -1 means that the value is not available. |
warnThreshold | 64-bit integer | The threshold for a capacity warning, as compared with the value availableBytes. A returned value of -1 means that the value is not available. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
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.
POST https://host_ip:9099/mapi/v1/alert/list
Not applicable.
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 integer | The date and time, in milliseconds since 00:00:00 on 1 January 1970 GMT, when the alert was generated. |
category | String | Alert category:
|
description | String | The text of the alert. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/list
Not applicable.
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 | Enum | The type of storage component:
|
storageComponentConfig | List | The following storage component configuration values: |
label | String | The name of the storage component. |
host | String | The URL of the storage component back-end host domain. |
https | Boolean | true for HTTPS connection to back-end system, false for HTTP. |
port | 32-bit integer | HTTP port to back-end system. |
bucket | String | The name of the bucket. |
region | String | The S3 region. |
authType | String | AWS Signature Version, used for authenticating all interactions with Amazon S3:
|
siteAffiliation | UUID | The value of id, a UUID representing the storage component or the user. |
useProxy | Boolean | If true, a proxy server is defined. If false, a proxy server is not defined. |
proxyHost | String | The proxy host, if used; otherwise, null. |
proxyPort | 32-bit integer | The proxy port number, if used; otherwise, null. |
proxyUserName | String | The proxy domain user name, if used; otherwise, null. |
proxyPassword | String | The proxy domain password, if used; otherwise, null). |
proxyDomain | String | The proxy domain, if used; otherwise, null. |
usePathStyleAlways | Boolean | If true, use path-style syntax to send requests to the back-end system; if false, use virtual-hosted style. |
connectionTimeout | 32-bit integer | The amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out. |
socketTimeout | 32-bit integer | The timeout value for reading from a connected socket. |
connectionTTL | 64-bit integer | The connection time to live (TTL) for a request. |
maxConnections | 32-bit integer | The maximum number of open HTTP connections to a storage component. |
userAgentPrefix | String | The HTTP user agent prefix header, used in requests to a storage component. |
socketSendBufferSizeHint | 32-bit integer | The size hint, in bytes, for the low-level TCP send buffer. |
socketRecvBufferSizeHint | 32-bit integer | The size hint, in bytes, for the low-level TCP receive buffer. |
managementProtocol | String | The communication protocol for HCP S Series Node MAPI requests:
|
managementHost | String | The host managing an HCP S Series Node storage component. |
readOnly | Boolean | If true, the storage component is marked as read-only. If false, the storage component is available for reading and writing data. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
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. |
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.
PATCH https://host_ip:9099/mapi/v1/storage_component/update
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": } }
Parameter | Required | Type | Description |
id | Yes | UUID | The ID of the storage component. |
storageType | No | String | The type of storage component:
|
storageComponentConfig | No | List | The following storage component configuration values as needed: |
label | No | String | The name of the storage component. |
host | No | String | The URL of the storage component back-end host domain. |
https | No | Boolean | If true, use an HTTPS connection to the back-end system. If false, use an HTTP connection. |
port | No | 32-bit integer | HTTP port of back-end system. |
bucket | No | String | The name of the bucket. The bucket must already exist. |
region | No | String | The S3 region. |
authType | No | String | The AWS Signature Version for authenticating all interactions with Amazon S3:
|
siteAffiliation | No | UUID | For id, the UUID representing the storage component or the user. |
accessKey | No | String | The access key of the S3 credentials for access to the bucket. |
secretKey | No | String | The secret key of the S3 credentials for access to the bucket. |
useProxy | No | Boolean | If 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. |
proxyHost | No | String | The proxy host, if used. |
proxyPort | No | 32-bit integer | The proxy port number, if used. |
proxyUserName | No | String | The proxy domain user name, if used. |
proxyPassword | No | String | The proxy domain password, if used. |
proxyDomain | No | String | The proxy domain. This is not supported. |
usePathStyleAlways | No | Boolean | If true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style. |
connectionTimeout | No | 32-bit integer | The amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out. |
socketTimeout | No | 32-bit integer | The timeout value for reading from a connected socket. |
connectionTTL | No | 64-bit integer | The connection time to live (TTL) for a request. |
maxConnections | No | 32-bit integer | The maximum number of open HTTP connections to a storage component. |
userAgentPrefix | No | String | The HTTP user agent prefix header, used in requests to a storage component. |
socketSendBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint . |
socketRecvBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint . |
managementProtocol | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
There is no default; if you use the parameter you must specify a value. |
managementHost | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name. |
managementUser | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
managementPassword | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
readOnly | No | Boolean | If true, objects can be read and deleted but writes aren't allowed. If false, writes are allowed. |
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. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The request is missing a valid storage component or parameter. |
401 | Unauthorized | Access was denied because credentials are not valid. |
404 | Not Found | The specified storage component was not found. |
405 | Method Not Allowed | The specified HTTP method is not allowed for a storage component. Resend using POST. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/update_state
The request body is:
{ "id": "uuid", "storageComponentState": "{ACTIVE|INACTIVE}" }
Parameter | Required | Type | Description |
id | Yes | UUID | The ID of the storage component. |
storageComponentState | Yes | String | The storage component state:
|
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 | Enum | The type of storage component:
|
storageComponentConfig | List | The following storage component configuration values: |
label | String | The name of the storage component. |
host | String | The URL of the storage component back-end host domain. |
https | Boolean | true for HTTPS connection to back-end system, false for HTTP. |
port | 32-bit integer | HTTP port to back-end system. |
bucket | String | The name of the bucket. |
region | String | The S3 region. |
authType | String | AWS Signature Version, used for authenticating all interactions with Amazon S3:
|
siteAffiliation | UUID | The value of id, a UUID representing the storage component or the user. |
useProxy | Boolean | If true, a proxy server is defined. If false, a proxy server is not defined. |
proxyHost | String | The proxy host, if used; otherwise, null. |
proxyPort | 32-bit integer | The proxy port number, if used; otherwise, null. |
proxyUserName | String | The proxy domain user name, if used; otherwise, null. |
proxyPassword | String | The proxy domain password, if used; otherwise, null). |
proxyDomain | String | The proxy domain, if used; otherwise, null. |
usePathStyleAlways | Boolean | If true, use path-style syntax to send requests to the back-end system; if false, use virtual-hosted style. |
connectionTimeout | 32-bit integer | The amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out. |
socketTimeout | 32-bit integer | The timeout value for reading from a connected socket. |
connectionTTL | 64-bit integer | The connection time to live (TTL) for a request. |
maxConnections | 32-bit integer | The maximum number of open HTTP connections to a storage component. |
userAgentPrefix | String | The HTTP user agent prefix header, used in requests to a storage component. |
socketSendBufferSizeHint | 32-bit integer | The size hint, in bytes, for the low-level TCP send buffer. |
socketRecvBufferSizeHint | 32-bit integer | The size hint, in bytes, for the low-level TCP receive buffer. |
managementProtocol | String | The communication protocol for HCP S Series Node MAPI requests:
|
managementHost | String | The host managing an HCP S Series Node storage component. |
readOnly | Boolean | If true, the storage component is marked as read-only. If false, the storage component is available for reading and writing data. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The request is missing a valid storage component or parameter. |
401 | Unauthorized | Access was denied because credentials are not valid. |
404 | Not Found | The specified storage component was not found. |
405 | Method Not Allowed | The specified HTTP method is not allowed for a storage component. Resend using POST. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/test
The request body is:
{ "id": "uuid" }
Parameter | Required | Type | Description |
id | Yes | UUID | The ID of the storage component. |
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 | String | The type of storage component:
|
verified | Boolean | If true, the storage component is activated. If false, it has not been verified and is awaiting for an administrative action. |
httpStatus | Integer | The 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. |
errorCode | String | Any error codes associated with the storage component; otherwise, null. |
errorMessage | String | Any error messages associated with the storage component; otherwise, null. |
daysUntilCertificateExpiration | 32-bit integer | The number of days left until the current HTTP certificate expires. |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The request is missing a valid storage component ID. |
401 | Unauthorized | Access was denied because credentials are not valid. |
404 | Not Found | The specified storage component was not found. |
405 | Method Not Allowed | The specified HTTP method is not allowed for a storage component. Resend using POST. |
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.
POST https://host_ip:9099/mapi/v1/storage_component/update
The 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": {true|false} } }
Parameter | Required | Type | Description |
id | Yes | UUID | The ID of the storage component. |
storageType | No | String | The type of storage component:
|
storageComponentConfig | Yes | List | The following storage component configuration values: |
label | No | String | The name of the storage component. |
host | Yes | String | The URL of the storage component back-end host domain. |
https | Yes | Boolean | If true, use an HTTPS connection to the back-end system. If false, use an HTTP connection to the back-end system. Default: false. |
port | No | Integer | The HTTP port of the back-end system. |
bucket | Yes | String | The name of the bucket. The bucket must already exist. |
region | No | String | The S3 region. Default: us-west-2. |
authType | No | String | The AWS Signature Version for authenticating all interactions with Amazon S3:
|
siteAffiliation | Yes | UUID | For id, the UUID representing the storage component or the user. |
accessKey | Yes | The access key of the S3 credentials for access to the bucket. | |
secretKey | Yes | The secret key of the S3 credentials for access to the bucket. | |
useProxy | No | Boolean | If 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. |
proxyHost | No | String | The proxy host, if used. |
proxyPort | No | Integer | The proxy port number, if used. |
proxyUserName | No | String | The proxy domain user name, if used. |
proxyPassword | No | String | The proxy domain password, if used. |
proxyDomain | No | String | The proxy domain. This is not supported. |
usePathStyleAlways | No | Boolean | If true, use path-style syntax to send requests to the back-end system. If false, use virtual-hosted style. Default: true. |
connectionTimeout | No | 32-bit integer | The amount of time, in milliseconds, that the HTTP connection waits to establish a connection before timing out. |
socketTimeout | No | 32-bit integer | The timeout value for reading from a connected socket. |
connectionTTL | No | 64-bit integer | The connection time to live (TTL) for a request. |
maxConnections | No | 32-bit integer | The maximum number of open HTTP connections to a storage component. If not specified, the defaults are:
|
userAgentPrefix | No | String | The HTTP user agent prefix header, used in requests to a storage component. |
socketSendBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP send buffer. If specified, you must also specify socketRecvBufferSizeHint . |
socketRecvBufferSizeHint | No | 32-bit integer | The size hint, in bytes, for the low-level TCP receive buffer. If specified, you must also specify socketSendBufferSizeHint . |
managementProtocol | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. The communication protocol for MAPI requests:
There is no default; if you use the parameter you must specify a value. |
managementHost | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node storage component; do not provide for other storage component types. Type the management system IP address or fully qualified domain name. |
managementUser | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
managementPassword | Yes (for HCP S Series Node) | String | Required for an HCP S Series Node 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. |
readOnly | No | Boolean | If true, objects can be read and removed but writes aren't allowed. If false, writes are allowed. |
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 |
state | Enum | The state of the storage component, indicating its availability to serve requests:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
400 | Bad Request | The 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. |
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" } } ]