Operates configuration hosts against host groups registered with Systemwalker Operation Manager.
The following operations are available.
Endpoint | HTTP | Operation details |
|---|---|---|
/v1/host-groups/{hostgroupname}/contained-hosts/{hostname} | GET | Gets information about the specified configuration host. |
POST | Modifies the attributes of the specified configuration host. | |
DELETE | Removes the specified configuration host from the host group. | |
/v1/contained-hosts | POST | Add the configured hosts to the host group. |
GET | Get a list of configuration host information. |
The fields of the contained-hosts resource object are as below.
If you specify a unique configuration host in the system, specify the host group name and the host name of the configuration host in the SE version. For EE versions, specify the subsystem number and host group, and the host name of the configuration host.
Filed Name | Type | Specification |
|---|---|---|
host | String | Host name of the connection destination |
subsystem | Numeric | Subsystem number |
hostgroupname | String | Host group name |
hostname | String | Host name of the configuration host |
status | List | Configuration host status |
maxexec | Numeric | Maximum configuration host multiplicity |
run | Numeric | Number of jobs running on the configuration host |
Function Description
Get the target configuration host information by sending a GET method request with a contained-hosts resource.
Privilege/Execution Environment Required
If the Systemwalker Operation Manager preference restricts users to the Systemwalker Operation Manager, you must have the privileges of a user belonging to the swadmin group. If you are not restricted to using Systemwalker Operation Manager, you can use it with ordinary user privileges.
Requests
GET
/v1/subsystems/{subsystem}/host-groups/{hostgroupname}/contained-hosts/{hostname}
/v1/host-groups/{hostgroupname}/contained-hosts/{hostname} (If you omit the subsystem number)
Under Path Parameters, specify the following parameters.
Parameter | How to specify | Type | Specification |
|---|---|---|---|
subsystem | Path | Numeric | Specify the subsystem number (from 0 to 9) on which the target configuration host resides. If you omit the subsystem number, the value is 0. |
hostgroupname (*) | Path | String | Specifies the host group in which the target configured host resides. (Note 1) |
hostname(*) | Path | String | Specify the target configuration host name. |
(*):Required Parameters
Path: Path parameters
You can specify a host group that is registered in either queue in the hostgroupname. You can use Web API of the "17.3.4.4 Getting a list of queue information" to get a list of queues resources and verify ook at their hostgroup field values to see the host groups.
Response
Returns the following HTTP status codes.
Code | Specification |
|---|---|
200 | Processing of the request was successful. |
401 | The credential is specified incorrectly. |
403 | Not a user privilege belonging to the swadmin group. |
404 | The target configuration host does not exist.
|
500 | An error occurred on the server while processing the request. |
Returns the object of the contained-hosts resource.
Usage Examples
An example of using the API to get a project with subsystem number 0, host group name "hostgroup1" and configuration host name "host1" is as follows. Note that the response example shows the objects of the contained-hosts resource that are stored in the data field, and the response header and other fields are omitted.
GET /Systemwalker-omgr/api/v1/subsystems/0/host-groups/hostgroup1/contained-hosts/host1 HTTP/1.1 Host: Systemwalker Operation Manager server hostname:9900 Authorization: Basic ********************
{
"host": "Systemwalker Operation Manager server hostname",
"subsystem": 0,
"hostgroupname": "hostgroup1",
"hostname": "host1",
"status": "ACT",
"maxexec": 10,
"run": 0
}Function Description
Temporarily change the definition of the target configuration host by sending a request for the PUT method with the contained-hosts resource.
Privilege/Execution Environment Required
You must have system administrator (user/superuser belonging to the Administrators group) privileges.
Requests
PUT
/v1/subsystems/{subsystem}/host-groups/{hostgroupname}/contained-hosts/{hostname}
/v1/host-groups/{hostgroupname}/contained-hosts/{hostname} (If you omit the subsystem number)
Under Path Parameters and Request Body, specify the following parameters.
Parameter | How to specify | Type | Specification |
|---|---|---|---|
subsystem | Path | Numeric | Specify the subsystem number (from 0 to 9) on which the target configuration host resides. If you omit the subsystem number, the value is 0. |
hostgroupname(*) | Path | String | Specifies the host group in which the target configured host resides. |
hostname(*) | Path | String | Specify the target configuration host name. |
maxexec | Body | Numeric | Specify the multiplicity (maximum number of concurrently executable) jobs on the target configuration host. Range is from 1 to 999. |
(*):Required Parameters
Path: Path parameters
Body: Request bodies
Response
Returns the following HTTP status codes.
Code | Specification |
|---|---|
200 | Processing of the request was successful. |
400 | The request parameter is invalid.
|
401 | The credential is specified incorrectly. |
403 | You are not a system administrator. |
404 | The target configuration host does not exist.
|
500 | An error occurred on the server while processing the request. |
Returns the object of the specified contained-hosts resource.
Cautionary Notes
Changes made by changing the attributes of the configuration host are retained until job execution control is started in initialization mode. When job execution control is started in initialization mode, the settings for distributed execution are changed to those defined in the initialization file.
Usage Examples
The following example shows how to use the API to change the multiplicity (maximum number of concurrently executable) jobs for a configuration host with subsystem number 0, host group name "hostgroup1", and host name "host1" to 2.
PUT /Systemwalker-omgr/api/v1/subsystems/0/host-groups/hostgroup1/contained-hosts/host1 HTTP/1.1
Host: Systemwalker Operation Manager server hostname:9900
Authorization: Basic ********************
Content-Type: application/json
{
"maxexec": 2
}Returns an object from the contained-hosts resource with the multiplicity (maximum number of concurrently executable) of the job changed to 2. Refer to the response example of the "17.3.5.1 Getting Configuration Host Information".
Function Description
Delete the target configuration host from the host group by sending a request for the DELETE method with the contained-hosts resource.
Privilege/Execution Environment Required
You must have system administrator (user/superuser belonging to the Administrators group) privileges.
Requests
DELETE
/v1/subsystems/{subsystem}/host-groups/{hostgroupname}/contained-hosts/{hostname}
/v1/host-groups/{hostgroupname}/contained-hosts/{hostname} (If you omit the subsystem number)
Under Path Parameters, specify the following parameters.
Parameter | How to specify | Type | Specification |
|---|---|---|---|
subsystem | Path | Numeric | Specify the subsystem number (from 0 to 9) on which the target configuration host resides. If you omit the subsystem number, the value is 0. |
hostgroupname(*) | Path | String | Specifies the host group in which the target configured host resides. |
hostname(*) | Path | String | Specify the target configuration host name. |
(*):Required Parameters
Path: Path parameters
Response
Returns the following HTTP status codes.
Code | Specification |
|---|---|
200 | Processing of the request was successful. |
401 | The credential is specified incorrectly. |
403 | You are not a system administrator. |
404 | The target configuration host does not exist.
|
409 | The specified operation cannot be performed on the target configuration host.
|
500 | An error occurred on the server while processing the request. |
Returns an object from a contained-hosts resource with an empty data field.
Cautionary Notes
The minimum number of configured hosts to register in a host group is one. Therefore, if the number of registered configuration hosts in the target host group is 1, the deletion fails because the number of registered configuration hosts becomes 0.
Usage Examples
The following example shows how to use the API to delete a configuration host with a host name of "host1" from a host group with a subsystem number of 0 and a host group name of "hostgroup1".
DELETE /Systemwalker-omgr/api/v1/subsystems/0/host-groups/hostgroup1/contained-hosts/host1 HTTP/1.1 Host: Systemwalker Operation Manager server hostname:9900 Authorization: Basic ********************
{
"next": false,
"total": 0,
"data": []
}Function Description
Adds a configuration host to the target host group by sending a POST method request with configuration host information in the request body.
If the target configuration host already exists, overwrite it.
Privilege/Execution Environment Required
You must have system administrator (user/superuser belonging to the Administrators group) privileges.
Requests
POST
/v1/contained-hosts
In the request body, specify the following parameters.
Parameter | How to specify | Type | Specification |
|---|---|---|---|
subsystem | Body | Numeric | Specify the subsystem number (from 0 to 9) on which the target configuration host resides. If you omit the subsystem number, the value is 0. |
hostgroupname(*) | Body | String | Specify the name of the host group in which the target configured host resides. |
hostname(*) | Body | String | Specify the target configuration host name.
When specifying from the Web API, only half-width alphanumeric characters, "-" (half-width hyphen), "_" (half-width underscore), ":" (half-width colon), "." (half-width dot), and "%" (half-width percent) can be used. |
maxexec | Body | Numeric | Specify the multiplicity (maximum number of concurrently executable) jobs on the target configuration host. |
(*):Required Parameters
Body: Request bodies
Response
Returns the following HTTP status codes.
Code | Specification |
|---|---|
200 | Processing of the request was successful. |
201 | Processing of the request was successful. |
400 | The request parameter is invalid.
|
401 | The credential is specified incorrectly. |
403 | You are not a system administrator. |
409 | Configuration hosts cannot be added to the target host group.
|
500 | An error occurred on the server while processing the request. |
Returns the object of the added contained-hosts resource.
Cautionary Notes
Changes made by changing the attributes of the configuration host are retained until job execution control is started in initialization mode. When job execution control is started in initialization mode, the settings for distributed execution are changed to those defined in the initialization file.
You can register no more than 100 configured hosts in a host group. Therefore, if the number of registered configuration hosts in the target host group is 100, the addition will fail.
Usage Examples
The following is an example of using the API to add a configuration host with a configuration host name of "host2" and the multiplicity (maximum number of concurrently executable) of 4 to a host group with a subsystem number of 0 and a host group name of "hostgroup1".
POST /Systemwalker-omgr/api/v1/contained-hosts HTTP/1.1
Host: Systemwalker Operation Manager server hostname:9900
Authorization: Basic ********************
Content-Type: application/json
{
"subsystem": 0,
"hostgroupname": "hostgroup1",
"hostname": "host2",
"maxexec": 4
}Refer to the response example of the "17.3.5.1 Getting Configuration Host Information".
Function Description
Get a list of contained-hosts resources.
Privilege/Execution Environment Required
If the Systemwalker Operation Manager preference restricts users to the Systemwalker Operation Manager, you must have the privileges of a user belonging to the swadmin group. If you are not restricted to using Systemwalker Operation Manager, you can use it with ordinary user privileges.
Requests
GET
/v1/contained-hosts
Common query parameters are available.
For more information, refer to the "17.2.3.2 Request Format".
Response
Returns the following HTTP status codes.
Code | Specification |
|---|---|
200 | Processing of the request was successful. |
400 | The request parameter is invalid.
|
401 | The credential is specified incorrectly. |
403 | Not a user privilege belonging to the swadmin group. |
500 | An error occurred on the server while processing the request. |
Returns the object of the contained-hosts resource.
Usage Examples
The following example shows how to use the API to get a list of configured hosts that exist in subsystem number 0.
GET /Systemwalker-omgr/api/v1/contained-hosts?subsystem=0 HTTP/1.1 Host: Systemwalker Operation Manager server hostname:9900 Authorization: Basic ********************
Returns an object from the contained-hosts resource as an array of objects in the data field. For information about the contained-hosts resource object, refer to the response example of the "17.3.5.1 Getting Configuration Host Information".