Storage component management resources

Last updated
Save as PDF

This module describes the storage component management resources.

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. You can 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 shown below:

{
    "id": "uuid"
    }

Parameter	Required	Type	Description
id	Yes	UUID	The UUID of the storage component.

Response structure

The response body is shown below:

{
  "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: 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
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: 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.
400	Bad Request	The MAPI metadata ID is invalid.
401	Unauthorized	Access was denied due to invalid credentials.
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.

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 this endpoint to configure settings, then use the endpoint /s3_settings/get to check them.

HTTP request syntax (URI)

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

Request structure

The request body is shown below:

{
  "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. No limit, default: 100 buckets.
maxBulkDeleteRequestSizeBytes	No	Integer	The maximum, total size of objects, in bytes, allowed in a single bulk delete operation. Default: 3 MB.
maxBulkDeleteRequestSizeCount	No	Integer	The maximum, total number of objects allowed in a single bulk delete operation. Default: 1000 objects.

Response structure

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

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

Return codes

Status code	HTTP name	Description
200	OK	The request was executed successfully.
401	Unauthorized	Access was denied due to invalid credentials.
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 shown below:

{
  "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],
    "activateNow": {true|false}
  }
}

Parameter	Required	Type	Description
storageType	Yes	String	The 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
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: `V2` `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.
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`.
activateNow	No	Boolean	If `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 shown below:

[
  {
    "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": ,
      "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: 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.
400	Bad Request	The request is missing a valid storage component or parameter.
401	Unauthorized	Access was denied due to invalid credentials.
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/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": 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": 0,
      "userAgentPrefix": "string",
      "socketSendBufferSizeHint": 0,
      "socketRecvBufferSizeHint": 0,
      "readOnly": true,
      "state": "ACTIVE"
    }
  }
]

Get S3 settings

You can retrieve the current S3 settings. You can use the endpoint /s3_settings/set to configure settings, then use this endpoint to check 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 shown below:

{
  "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. No limit, default: 100 buckets.
maxBulkDeleteRequestSizeBytes	No	Integer	The maximum, total size of objects, in bytes, allowed in a single bulk delete operation. Default: 3 MB.
maxBulkDeleteRequestSizeCount	No	Integer	The maximum, total number of objects allowed in a single bulk delete operation. Default: 1000 objects.

Return codes

Status code	HTTP name	Description
200	OK	The request was executed successfully.
401	Unauthorized	Access was denied due to invalid credentials.
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
}

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. Once 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 shown below:

[
  {
    "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 1 January 1970 GMT, when the alert was generated.
category	String	Alert category: STORAGECOMPONENT
description	String	The 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

You can retrieve 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 shown below:

[
  {
    "id": "",
    "storageType": "type",
    "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,
      "readOnly": true|false,
      "state": "state"
    }
  }
]

Parameter	Type	Description
id	UUID	The ID of the storage component.
storageType	String	The 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
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: V2 V4
siteAffiliation		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.
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: 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 due to invalid credentials.
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/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": null,
      "userAgentPrefix": null,
      "socketSendBufferSizeHint": null,
      "socketRecvBufferSizeHint": null,
      "readOnly": false,
      "state": "ACTIVE"
    }
  }
]

Patch storage component configuration

You can update the configuration of specific storage component settings. Use the endpoint /storage_component/list to check the existing settings or verify changes. Use the endpoint /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 shown below:

{
  "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],
    "readOnly": 
  }
}

Parameter	Required	Type	Description
id	Yes	UUID	The ID of the 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: `V2` `V4`
siteAffiliation	No		For `id`, the UUID representing the storage component or the user.
accessKey	No		Access key of the S3 credentials for access to the bucket.
secretKey	No		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 enter 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`.
readOnly	No	Boolean	If `true`, objects can be read and deleted but write operations aren't allowed. If `false`, write operations are allowed.

Response structure

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

[
  {
    "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": ,
      "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: 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.
400	Bad Request	The request is missing a valid storage component or parameter.
401	Unauthorized	Access was denied due to invalid credentials.
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.

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 shown below:

{
  "id": "uuid",
  "storageComponentState": "{ACTIVE|INACTIVE}"
}

Parameter	Required	Type	Description
id	Yes	UUID	Enter the ID of the storage component.
storageComponentState	Yes	String	Set the storage component state: `ACTIVE`: Available to serve requests. `INACTIVE`: Not available to serve requests (administrative pause).

Response structure

The response body structure is shown below:

[
  {
    "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": ,
      "readOnly": ,
      "state": "state"
    }
  }
]

Parameter	Type	Description
id	UUID	The ID of the storage component.
storageType	String	The 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
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: V2 V4
siteAffiliation		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.
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: 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.
400	Bad Request	The request is missing a valid storage component or parameter.
401	Unauthorized	Access was denied due to invalid credentials.
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.

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,
    "readOnly": false,
    "state": "INACTIVE"
  }
}
]

Test storage component access

You can test 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 shown below:

{
  "id": "uuid"
}

Parameter	Required	Type	Description
id	Yes	UUID	The ID of the storage component.

Response structure

The response body is shown below:

{
  "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: 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
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: 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.
400	Bad Request	The request is missing a valid storage component ID.
401	Unauthorized	Access was denied due to invalid credentials.
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.

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 endpoint /storage_component/list to check the existing settings or to verify changes. Use the endpoint 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 shown below:

{
  "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],
    "readOnly": {true|false}
  }
}

Parameter	Required	Type	Description
id	Yes	UUID	The ID of the 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: `V2` `V4`
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.
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`.
readOnly	No	Boolean	If `true`, objects can be read and deleted but write operations aren't allowed. If `false`, write operations are allowed.

Response structure

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

[
  {
    "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": ,
      "readOnly": true|false,
      "state": "state"
    }
  }
]

Parameter	Type	Description
state	Enum	The 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.
400	Bad Request	The request is missing a valid storage component or parameter.
401	Unauthorized	Access was denied due to invalid credentials.
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": 0,
      "userAgentPrefix": "string",
      "socketSendBufferSizeHint": 0,
      "socketRecvBufferSizeHint": 0,
      "readOnly": false,
      "state": "ACTIVE"
    }
  }
]

We've Moved!

Product Documentation has moved to docs.hitachivantara.com

Activate storage components

Configure S3 settings

Configure storage component

Get S3 settings

List storage component alerts

List storage components

Patch storage component configuration

Set storage component state

Test storage component access

Update storage component configuration

Still Looking?

Quick Links

Activate storage components

Configure S3 settings

Configure storage component

Get S3 settings

List storage component alerts

List storage components

Patch storage component configuration

Set storage component state

Test storage component access

Update storage component configuration