Skip to main content

We've Moved!

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

Administrative management methods

The management API includes administrative management methods.

Add license

The method license/add adds a license for the system. You must provide a valid license file for the licensed function to function. The method decrypts, validates, and stores the license file.

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

The request body is:

{
  "value": "license_file"
}
ParameterRequiredTypeDescription
valueYesStringThe file path of your HCP for cloud scale license.
Response structure

Not applicable.

Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials were noit valid.
405 Method Not Allowed The specified HTTP method is not allowed for administrative data. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/license/add

JSON request:

{
  "value": "hcpcs_license.plk"
}

Get serial number

You can retrieve the current serial number of your HCP for cloud scale system.

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

Not applicable.

Response structure

The response body is:

{
  "value": "serial_number"
}

Parameter

Type

Description

value String The serial number of your HCP for cloud scale system.
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 administrative data. Resend using POST.
Example

Request example:

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

JSON response:

{
  "value": "SerialNumber48692"
}

Get system chargeback report

The method chargeback/system/get_report lets a user with system-level permission generate a chargeback report on storage usage for any or all buckets defined in the system.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/chargeback/system/get_report
Request structure

The request structure is:

{
  "userName": "name",
  "startDateTime": "yyyy-mm-ddThh.mm.ssZ",
  "endDateTime": "yyyy-mm-ddThh.mm.ssZ",
  "granularity": "granularity",
  "bucketList": ["string"],
  "header": true|false,
  "reportedFields": [
    "field"
  ]
}
Response structure

The response is a stream in comma-separated value (CSV) format.

Parameter

Required

Type

Description

userNameNoStringReport bucket usage by the specified display name. Either a user name or a bucket list is required.
startDateTimeNoDate-TimeThe starting UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ. Truncated to the beginning of the specified hour.
endDateTimeNoDate-TimeThe ending UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ. Truncated to the beginning of the specified hour. The default is the current hour.
granularity NoEnumThe granularity of detail in the report:
  • HOURLY: Report hourly data
  • DAILY (default): Report daily data
  • MONTHLY: Report monthly data
bucketListNoStringA list of buckets to include in the report. Either a user name or a bucket list is required. The default is all buckets in the specified scope. Limited to the number of buckets allowed per user.
headerNoBooleanIf true, include column headers as the first line of the response. If false, omit the column headers. The default is false.
reportedFieldsNoStringA comma-separated list of available fields to include in the report:
  • BUCKET_OWNER: bucket owner
  • BUCKET_NAME: bucket name
  • STORAGE_CLASS: storage class (STANDARD)
  • CAPACITY_IN_BYTE_HOURS: capacity in byte-hours
  • CAPACITY_IN_GB_MONTHS: capacity in gigabyte-months
  • TOTAL_OBJECTS: object count
  • WRITES: total writes
  • DELETES: total deletionss
  • WRITTEN_MB: bytes written
  • DELETED_MB: bytes deleted

The default is to return all fields.

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 administrative data. Resend using POST.
Examples

The following example returns a daily report for all buckets owned by the user Jimmy for a specific date range in November 2020.

Request example:

POST https://10.10.24.195:9099/mapi/v1/chargeback/system/get_report

JSON request:

{
  "userName": "Jimmy",
  "startDateTime": "2020-11-02T00:00Z",
  "endDateTime": "2020-11-04T00:00Z",
  "granularity": "DAILY",
  "header": true
}

Response:

Bucket Capacity Report for user: Jimmy@example.org; Requested by: admin; Reporting period: 2020-11-02T00:00Z - 2020-11-04T00:00Z; Granularity: daily; System name: hcpcs.company.com
YYYY-MM-DD,Bucket Owner,Bucket Name,Storage Class,Byte-Hour,GB-Month,Total Objects,Writes,Deletes,Written MB,Deleted MB
2020-11-02,Jimmy@example.org,bucket2,Standard,202970940,0,4,28,0,193,0
2020-11-02,Jimmy@example.org,bucket1,Standard,103229940,0,-11916,11927,11917,86,11
2020-11-03,Jimmy@example.org,bucket1,Standard,112383590,0,72,74,0,32,0
2020-11-04,Jimmy@example.org,bucket1,Standard,229915961,0,21,1121,0,3,0

Get system events

The method system/info retrieves the 100 most recent system events.

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

Not applicable.

Response structure

The response body is:

{
  "events": [
    {
      "severity": "INFO|WARNING|SEVERE",
      "subject": "event_subject",
      "message": "event_message",
      "subsystem": "event_subsystem",
      "timestamp": date_time
    },
    .
    .
    .
  ]
}

Parameter

Type

Description

severityString The severity of the event:
  • INFO
  • WARNING
  • SEVERE
subjectStringSummary of the event.
messageStringDetails about the event.
subsystemStringThe event category (for example, User, Bucket, or S3 settings).
timestamp 64-bit integerThe date and time, in milliseconds since 00:00:00 on 1 January 1970 GMT, when the event was generated.
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 administrative data. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/system/info

JSON response:

{
  "events": [
    {
      "severity": "INFO",
      "subject": "User admin@company.com authenticated",
      "message": "User admin@company.com with Id d3c01db4-ac18-4d90-a321-899bb210baf7 authenticated successfully to the Administration App.",
      "subsystem": "User",
      "timestamp": 1559547959735
    },
    {
      "severity": "INFO",
      "subject": "Unexpectedly failed authentication request by user admin@company.com",
      "message": "An authentication request unexpectedly failed for username admin@company.com.",
      "subsystem": "User",
      "timestamp": 1559547646844
    }
  ]
}

Get user chargeback report

The method chargeback/user/get_report lets a user generate a chargeback report on storage usage for any or all buckets defined in the system that the user owns.

HTTP request syntax (URI)
POST https://host_ip:9099/mapi/v1/chargeback/user/get_report
Request structure

The request structure is:

{
  "startDateTime": "yyyy-mm-ddThh.mm.ssZ",
  "endDateTime": "yyyy-mm-ddThh.mm.ssZ",
  "granularity": "granularity",
  "bucketList": ["string"],
  "header": true|false,
  "reportedFields": [
    "field"
  ]
}
Response structure

The response is a stream in comma-separated value (CSV) format.

Parameter

Required

Type

Description

startDateTimeNoDate-TimeThe starting UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ. Truncated to the beginning of the specified hour.
endDateTimeNoDate-TimeThe ending UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ. Truncated to the beginning of the specified hour. The default is the current hour.
granularity NoEnumThe granularity of detail in the report:
  • HOURLY: Report hourly data
  • DAILY (default): Report daily data
  • MONTHLY: Report monthly data
bucketListNoStringA list of buckets to include in the report. The default is all buckets that the user owns. Limited to the number of buckets allowed per user.
headerNoBooleanIf true, include column headers as the first line of the response. If false, omit the column headers. The default is false.
reportedFieldsNoStringA comma-separated list of available fields to include in the report:
  • BUCKET_OWNER: bucket owner
  • BUCKET_NAME: bucket name
  • STORAGE_CLASS: storage class (STANDARD)
  • CAPACITY_IN_BYTE_HOURS: capacity in byte-hours
  • CAPACITY_IN_GB_MONTHS: capacity in gigabyte-months
  • TOTAL_OBJECTS: object count
  • WRITES: total writes
  • DELETES: total deletions
  • WRITTEN_MB: bytes written
  • DELETED_MB: bytes deleted

The default is to return all fields.

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 administrative data. Resend using POST.
Example

The following example returns a daily report for all buckets owned by the user (Jimmy) for a specific date range in November 2020.

Request example:

POST https://10.10.24.195:9099/mapi/v1/chargeback/system/get_report

JSON request:

{
  "startDateTime": "2020-11-02T00:00Z",
  "endDateTime": "2020-11-04T00:00Z",
  "granularity": "DAILY",
  "header": true
}

Response:

Capacity Report for user: Jimmy@example.org; Reporting period: 2020-11-02T00:00Z - 2020-11-04T00:00Z; Granularity: daily; System name: hcpcs.company.com
YYYY-MM-DD,Bucket Owner,Bucket Name,Storage Class,Byte-Hour,GB-Month,Total Objects,Writes,Deletes,Written MB,Deleted MB
2020-11-02,Jimmy@example.org,bucket2,Standard,202970940,0,4,28,0,193,0
2020-11-02,Jimmy@example.org,bucket1,Standard,103229940,0,-11916,11927,11917,86,11
2020-11-03,Jimmy@example.org,bucket1,Standard,112383590,0,72,74,0,32,0
2020-11-04,Jimmy@example.org,bucket1,Standard,229915961,0,21,1121,0,3,0

List licenses

You can retrieve information about the current licenses for your HCP for cloud scale system.

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

Not applicable.

Response structure

The response body is:

{
  "featureName": "feature",
  "uploadDate": "date_time",
  "expirationDate": "date_time0",
  "valid": {true|false},
  "message": "message"
  }

Parameter

Type

Description

featureName String Name of the licensed feature.
uploadDateThe date and time, in the format Ddd Mmm dd hh:mm:ss TMZ yyyy, when the license was uploaded.
expirationDateThe date and time, in the format Ddd Mmm dd hh:mm:ss TMZ yyyy, when the license expires.
validBooleanIf true, the license is valid. If false, the license is invalid.
messageStringState of the license:
  • License is expired
  • License is valid
  • License not set
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 administrative data. Resend using POST.
Example

Request example:

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

JSON response:

{
  "featureName": "DARE",
  "uploadDate": "Tue Jun 16 00:00:00 GMT 2020",
  "expirationDate": "Sat Oct 24 10:24:54 GMT 2020",
  "valid": true,
  "message": "License is valid"
  }

Refresh client certificates

If your system uses the HTTPS protocol and you change an SSL certificate, you need to update the certificates on storage components.

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

Not applicable.

Response structure

Not applicable.

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 administrative data. Resend using POST.
Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/certificates/refresh

Set serial number

The method serial_number/set sets the serial number of the HCP for cloud scale system. You must provide a valid serial number for the system to function.

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

The request body is:

{
  "value": "serial_number"
}
ParameterRequiredTypeDescription
valueYesStringThe serial number of your HCP for cloud scale system.
Response structure

The response returns the same parameter as the request.

Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials were noit valid.
405 Method Not Allowed The specified HTTP method is not allowed for administrative data. Resend using POST.
Example

Request example:

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

JSON request:

{
  "value": "SerialNumber48692"
}

JSON response:

{
  "value": "SerialNumber48692"
}