5.7.1 Plug-in processing execution

Description

Executes any functional operation for a plug-in.

Execution permissions

See the section on operating permissions required for system monitoring using the Intelligent Integrated Management Base in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

If you specify _performanceDataGet for the method parameter when JP1/PFM is linked, the Admin or Operator permissions must be granted to the execution user for the resource group of the JP1/PFM agent.

API version

Format

Request line

POST /application/component/apiVersion/actions httpVersions

Request message body

{
    "method": function-name,
    "sid": target-IM-management-node-SID,
    "args": operation-specification
}

Response message body

result-of-the-operation

Parameters

method

Specify the name of the plug-in function to execute. A function name starting with double underscores (__) is not allowed.

The following function is provided by default:

Function name	Plug-in	Operation
`_performanceDataGet`	JP1/PFM plug-in	Getting performance information

sid

Specify the IM management node to be operated with the plug-in, in the SID format of configuration information. Only the IM management node at the end of the system configuration tree can be specified.

For details on the SID, see 7.1 SID.

args

Specify the values to pass to the args.methodArgs argument of the plug-in function to execute. If there is no information to be passed, specify an empty object ({}).

The size of specified values must be less than 10 MB including other parameters.

The following table describes what value is passed to args.methodArgs when the method parameter is set to _performanceDataGet:

No.	Member name	Data type	Optional	Description
1	`recordId`	string	No	Specify the record ID to be retrieved. Only uppercase characters can be used. The prefix of the record ID, `PI_`, `PD_`, or `PL_` can be omitted. For example, if the prefix is `PI_`, you can specify `LOGD` instead of `PI_LOGD`. Note that if another record that has a different prefix but has the same record ID excluding the prefix exists, it is assumed that both records are specified.
2	`fieldIds`	string[]	Yes	Specify the fields you get as an array. Only uppercase characters can be used. If you want to get performance data of specific fields, specify the field IDs^# in array format. # The format is `record-ID_PFM-Manager-name`. For `CPU%` of the `PD_PDI` record, the field ID is `PD_PDI_PCT_PROCESSOR_TIME`. If this member is omitted, all the fields in the specified record are output. If an empty value is specified (that is, `fieldIds:[ ]`), it is assumed that this member is omitted. Note that the data below (key field needed to identify the record) is output even if the field ID is omitted. For details on the key fields, see the manual of each agent. - Historical report (single agent) - `"Date and Time"` field - `ODBC` key field
3	`startTime`	string	No	Specify the start date and time of reporting. Use the ISO8601 extended format (`YYYY-MM-DDThh:mm:ssZ`). The letter `Z` at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of `+hh:mm` or `-hh:mm`.
4	`endTime`	string	No	Specify the end date and time of reporting. Use the ISO8601 extended format (`YYYY-MM-DDThh:mm:ssZ`) for the date and time of the UTC timezone. The letter `Z` at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of `+hh:mm` or `-hh:mm`.
5	`interval`	string	No	Specify the interval of reporting. Use the format below. It is case insensitive. `MIN`: In minutes `HOUR`: In hours `WEEK`: Weekly `DAY`: Daily `MONTH`: Monthly `YEAR`: Yearly The interval is ignored when specified for a PD record.
6	`filter`	object[]	Yes	Specify this member if you want to filter the performance data you get by its field value. Filtering is possible for more than one field. If you specify multiple filter conditions, the system retrieves the performance data that meets all the conditions (AND condition). If an empty value is specified (that is, `filter:[ ]`), it is assumed that this member is omitted.
7	`limit`	number	Yes	Specify the maximum number of records to be retrieved. The possible values are from `1` to `4320`. If this member is omitted, it is assumed that the specified value is `4320`. Specifying a value other than permitted values generates an error, causing the operation to stop.

The following table describes the format of the object you specify for filter:

No.	Member name	Data type	Optional	Description
1	`fieldId`	string	No	Specify the filter ID of the field to be filtered. Only uppercase characters can be used.
2	`operator`	string	Yes	Specify the filter condition for performance data you get. Select one of the following values: `=`: The value of the field is equal to `value`. `<>`: The value of the field is not equal to `value`. `<`: The value of the field is less than `value`. `<=`: The value of the field is less than or equal to `value`. `>`: The value of the field is greater than `value`. `>=`: The value of the field is greater than or equal to `value`. If this member is omitted, it is assumed that `=` is specified.
3	`value`	string	No	Specify the value according to the field format described in the manuals for JP1/PFM - Agent or JP1/PFM - RM. Note the following description for the ranges: - Character The specified value is applied as it is. However, `*` is handled as a wildcard character. - Integer An integer must be within the acceptable range of the data type for the field, which is from -2,147,483,648 to 2,147,483,647. However, the check range of the ulong (unsigned long) data type can be extended by specifying the `condExpValueUlongExtension` parameter in `config.xml` for JP1/PFM - Web Console. For details on the `config.xml` parameter, see the manual JP1/Performance Management Reference. - Decimal number Specify a value within the acceptable range of the data type for the field. If the format of the target field is float or double, and the field value has four decimal places or more, the value is rounded off to the third decimal place. If the format of the target field is utime and the field value has seven decimal places or more, the value is rounded off to the sixth decimal place. For details on the format of the field, see the description of each field in the manuals for JP1/PFM - Agent or JP1/PFM - RM. - Date Specify the date and time in ISO8601 extended format (`YYYY-MM-DDThh:mm:ssZ`). The letter `Z` at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of `+hh:mm` or `-hh:mm`. (The time always uses the `HH:mm:ss` format.) Note that an error occurs if any of control characters, `(`, `)`, `[`, `]`, `<`, `>`, `=`, and `"` is contained in the value. The acceptable number of bytes is a maximum of 2,048 bytes.

No.

Member name

Data type

Optional

Description

fieldId

string

Specify the filter ID of the field to be filtered. Only uppercase characters can be used.

operator

string

Yes

Specify the filter condition for performance data you get. Select one of the following values:

=: The value of the field is equal to value.
<>: The value of the field is not equal to value.
<: The value of the field is less than value.
<=: The value of the field is less than or equal to value.
>: The value of the field is greater than value.
>=: The value of the field is greater than or equal to value.

If this member is omitted, it is assumed that = is specified.

value

string

Specify the value according to the field format described in the manuals for JP1/PFM - Agent or JP1/PFM - RM. Note the following description for the ranges:

- Character

The specified value is applied as it is. However, * is handled as a wildcard character.

- Integer

An integer must be within the acceptable range of the data type for the field, which is from -2,147,483,648 to 2,147,483,647.

However, the check range of the ulong (unsigned long) data type can be extended by specifying the condExpValueUlongExtension parameter in config.xml for JP1/PFM - Web Console.

For details on the config.xml parameter, see the manual JP1/Performance Management Reference.

- Decimal number

Specify a value within the acceptable range of the data type for the field.

If the format of the target field is float or double, and the field value has four decimal places or more, the value is rounded off to the third decimal place.

If the format of the target field is utime and the field value has seven decimal places or more, the value is rounded off to the sixth decimal place.

For details on the format of the field, see the description of each field in the manuals for JP1/PFM - Agent or JP1/PFM - RM.

- Date

Specify the date and time in ISO8601 extended format (YYYY-MM-DDThh:mm:ssZ). The letter Z at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of +hh:mm or -hh:mm. (The time always uses the HH:mm:ss format.)

Note that an error occurs if any of control characters, (, ), [, ], <, >, =, and " is contained in the value. The acceptable number of bytes is a maximum of 2,048 bytes.

Status codes

The following table describes the status codes that are returned as a response to the request:

Status code	Message	Description
`200`	None	Plug-in execution succeeded.
`400`	KAJY22003-E	The request has a parameter with an invalid format.
`403`	KAJY22004-E	There is no permission to access the specified IM management node.
`500`	KAJY22005-E	An error occurred during the plug-in processing.

For details on the messages, see the manual JP1/Integrated Management 2 - Manager Messages.

Return values

No.	Member name	Data type	Description
1	--	object	The object in which the execution result of the plug-in processing is stored. The return value of the plug-in function is assigned to the object.

The following table describes the return value when the method parameter is set to _performanceDataGet:

No.	Member name	Data type	Description
1	`component`	string	Component name This is always set to `HITACHI/JP1/PFM/CONFINFO`.
2	`productId`	string	Product ID of the agent whose performance data is to be retrieved
3	`dataModelVersion`	string	Data model version of the agent whose performance data is to be retrieved
4	`rc`	number	Return code `0`: Data was retrieved successfully. `1`: Data was retrieved successfully but some records were not retrieved due to `limit`. `2`: There is no data in the specified period.
5	`fields`	object[]	Array of field information objects
6	`data`	string[][]	Two dimensional array of performance data, in [row data][column data] format. The output order of the column data guarantees the output order of the field information. The data and time data is returned as the data and time in the UTC timezone in ISO8601 extended format (`YYYY-MM-DDThh:mm:ssZ`). Any timezone other than UTC is not supported. In addition, if `dataType` of the output data is one of `FOLAT`, `DOUBLE`, or `SECTIMEDOUBLE` and its value is less than 10 to the negative third power or greater than or equal to 10 to the seventh power, the value is output in floating point format (such as `1.01E10`).

The following table describes the format of the field information object:

No.	Member name	Data type	Description
1	`id`	string	Field ID
2	`displayName`	string	Display name of the field
3	`dataType`	string	Data type of the field: `STR`: String `SHORT`: 16-bit integer `INT`: 32-bit integer `LONG`: 64-bit integer `FLOAT`: 32-bit single-precision floating-point number `DOUBLE`: 64-bit double-precision floating-point number `SECTIMELONG`: Long value that indicates the time (in seconds) since a particular point in time^#1 `SECTIMEDOUBLE`: Double value that indicates the time (in seconds) since a particular point in time^#1 `MILLTIME`: Long value that indicates the time (in milliseconds) since a particular point in time^#1 `DATE`: Data that represents only the year, month, and day (`yyyy-MM-DDThh:mm:ssZ`) `DATETIME`: Data that represents the year, month, day, and time (hour, minute, and second) (`yyyy-MM-DDThh:mm:ssZ`) `TIME`: Data that represents only the time (`yyyy-MM-DDThh:mm:ssZ`, only the time is output as the information.)
4	`keyType`	string	Key attribute of the field needed for identifying data (record)^#2 `DATE` It must be specified in one field of all fields, and indicates that the field is a key to identifying the time. `INST` It is specified in zero or more fields of all fields, and indicates that the field is a key specific to data (record). `NONE` It indicates that the field is not a key.

#1: The point in time serving as a reference depends on the fields. See each field (field in utime format) of JP1/PFM - Agent or JP1/PFM - RM.
#2: The following table lists the combination of key attributes required to identify the data (record):

Report type	Record type	Combination of attributes required for data identification
Historical report (Single agent)	Single row record	`DATE`
Multi-row record	`DATE` `INST`

Report type

Record type

Combination of attributes required for data identification

Historical report

(Single agent)

Single row record

DATE

Multi-row record

DATE
INST

Examples

The example below uses the API in the following scenario:

The functionality to use: JP1/PFM plug-in for getting performance information
JP1/PFM manager host name: mgrhost1
JP1/PFM agent host name: agenthost1
Target IM management node: JP1/Performance Management - Agent Option for Platform (For Windows)
The monitoring item to be retrieved: CPU usage
Output start time: April 1, 2017 00:00:00 JST
Output end time: April 1, 2017 01:00:00 JST

Request:

POST /im/api/v1/actions HTTP/1.1
Authorization:Bearer xxxx
Accept-Language: ja
Content-Type: application/json
Accept: application/json
{
    "method": "_performanceDataGet",
    "sid": "_JP1PFM-M_MGRHOST1/_JP1PFM-AHOST_AGENTHOST1/_HOST_AGENTHOST1/_JP1PFM-A_TA1agenthost1",
    "args": {
        "recordId": "PI",
        "fieldIds": ["PI_PCT_TOTAL_PROCESSOR_TIME"],
        "startTime": "2017-04-01T00:00:00+09:00",
        "endTime": "2017-04-01T01:00:00+09:00",
        "interval":"HOUR"
    }
}

Response:

{
    "component": "/HITACHI/JP1/PFM/CONFINFO",
    "productId": "T",
    "dataModelVersion": "8.4",
    "rc": 0,
    "fields": [
    {
        "id": "PI_DATETIME",
        "displayName": "Date and Time",
        "dataType": "DATETIME",
        "keyType": "DATE"
    },
    {
        "id": "PI_PCT_TOTAL_PROCESSOR_TIME",
        "displayName": "CPU %",
        "dataType": "FLOAT",
        "keyType": "NONE"
    }
    ],
    "data": [
        [
            "2017-03-31T15:00:00Z",
            "14.04"
        ],
        [
            "2017-03-31T16:00:00Z","13.55"
        ]
    ]
}

To Page Top