Hitachi

JP1 Version 12 JP1/Operations Analytics REST API Reference Guide


2.5.3 Creating Collector

This API creates a collector. However, it cannot create a collector for a custom application.

Execution permission

Admin

API version

v1

Request format

POST http[s]://host:port/Analytics/version/objects/Collectors

Request body

The structure of the request body and the object attributes are as follows:
{
        "name":"...",
        "collectorType":"...",
        "osType":"...",
        "autoCollectionType":"...",
        "collectorCredentials":[{
            "requireHostAddress":"...",
            "ipAddress":"...",
            "accessTargetIdentification":"...",
            "userId":"...",
            "password":"...",
            "updatePassword":"...",
            "portNumber":"...",
            "optionalInformation1":"...",
            "updateOptionalInformation1":"...",
            "optionalInformation2":"...",
            "updateOptionalInformation2":"...",
            "optionalInformation3":"...",
            "updateOptionalInformation3":"...",
            "useProxy":"...",
            "proxyHostAddr":"...",
            "proxyPort":"...",
            "proxyUser":"...",
            "updateProxyPassword":"...",
            "proxyPassword":"...",
            "hypertextTransferProtocolType":"...",
            "domainName":"...",
            "rootPassword":"...",
            "updateRootPassword":"...",
            "useAdministrativeShares":"...",
            "shareName":"...",
            "sharedFolder":"...",
            "logicalHostName":"...",
            "useLogicalHostName":"..."
        },
        :
        ],
        "plugin":{
            "instanceID":"..."
        }
}

Collector (Type: Collector)

Attribute

Type

Description

name

string

Collector name

collectorType

enum

Collector type.

(For details about the specifiable values, see the table ProtocolType in List of enumerators.)

The specifiable values are as follows:

  • VCENTER
  • AJS
  • PFM
  • IM
  • CUSTOM
  • HTTP

osType

enum

Type of OS. This member is only set when the collectorType is AJS, PFM, or IM.

(For details about the specifiable values, see the table CollectorOsType in List of enumerators.)

autoCollectionType

enum

Settings for periodic executions of the collector.

(For details about the specifiable values, see the table ConnectType in List of enumerators.)

The specifiable values are as follows:

  • AutoConnect
  • NotAutoConnect

collectorCredentials

CollectorCredential[]

Authentication information used for connections to monitoring targets.

plugin

Plugin

Defail information of the plug-in applied to the collector

collectorCredentials (Type: CollectorCredential)

Attribute

Type

Description

requireHostAddress

boolean

A flag that determines if an IP address or host name is required

- true: An IP address is required. An access-target identification key is not required.

- false: An IP address is not required. An access-target identification key is required.

This is used for the HTTP protocol.

ipAddress

string

IP address or host name used for connections to management software.

accessTargetIdentification

string

Access-target identification key (when no IP address is specified)

userId

string

User ID used for connections to management software. Specify a string of 255 or fewer bytes.

password

string

Password used for connections to management software. Encode a string of 255 or fewer bytes in Base64.

updatePassword

boolean

Whether to change the password used for connections to management software.

・true: Password is changed

・false: Password is not changed

If this member is omitted, false is set.

portNumber

int

Port number used for connections to management software.

optionalInformation1

string

Option information for information acquisition that can be used in the plug-in. The value set for the first option. Encode a string in Base64.

updateOptionalInformation1

boolean

To change option 1, set "true". Use this only for updates.

optionalInformation2

string

Option information for information acquisition that can be used in the plug-in. The value set for the second option. Encode a string in Base64.

updateOptionalInformation2

boolean

To change option 2, set "true". Use this only for updates.

optionalInformation3

string

Option information for information acquisition that can be used in the plug-in. The value set for the third option. Encode a string in Base64.

updateOptionalInformation3

boolean

To change option 3, set "true". Use this only for updates.

useProxy

boolean

Specify true when connecting to a custom collector via a proxy.

proxyHostAddr

string

Proxy host address when using a proxy.

proxyPort

int

Proxy port when using a proxy.

proxyUser

string

The authenticated user of the proxy when using the proxy.

updateProxyPassword

boolean

Set true to change the proxy password. Used only when updating.

proxyPassword

string

Proxy authentication password when using a proxy. Encode a string in Base64.

hypertextTransferProtocolType

enum

Whether to use SSL (HTTPS) for connections to management software.

(For details about the specifiable values, see the table HypertextTransferProtocolType in List of enumerators.)

The specifiable values are as follows:

  • HTTP
  • HTTPS

domainName

string

Domain name: Used for application linkage when Windows is selected.

rootPassword

string

root password: Used for application linkage when Unix is selected.

updateRootPassword

boolean

To change the password, set true. Use only for updates.

useAdministrativeShares

boolean

To share management, set true.

shareName

string

share Name

sharedFolder

string

shared Folder

logicalHostName

string

Logical Host Name

useLogicalHostName

boolean

To use logical host name, set true.

plugin (Type: Plugin)

Attribute

Type

Description

instanceID

long

ID for identifying instances

Response body

The structure of the response body and the object attributes are as follows:
{
        "instanceID":"...",
        "name":"...",
        "collectorType":"...",
        "osType":"...",
        "autoCollectionType":"...",
        "connectResult":"...",
        "refreshStatus":"...",
        "message":"...",
        "lastRefreshed":"...",
        "refreshDateForInventory":"...",
        "refreshDateForPerformance":"...",
        "refreshDateForState":"...",
        "numOfHypervisors":"...",
        "numOfVms":"...",
        "numOfHosts":"...",
        "numOfApplications":"...",
        "numOfContainers":"...",
        "numOfServices":"...",
        "numOfResources":"...",
        "collectorCredentials":[{
            "requireHostAddress":"...",
            "ipAddress":"...",
            "accessTargetIdentification":"...",
            "userId":"...",
            "portNumber":"...",
            "hypertextTransferProtocolType":"...",
            "domainName":"...",
            "useAdministrativeShares":"...",
            "shareName":"...",
            "sharedFolder":"...",
            "logicalHostName":"...",
            "useLogicalHostName":"..."
        },
        :
        ],
        "productName":"...",
        "providerName":"...",
        "refreshDateForApp":"...",
        "plugin":{
            "instanceID":"...",
            "name":"...",
            "pluginId":"...",
            "protocolType":"...",
            "formatversion":"...",
            "pluginversion":"...",
            "pluginType":"...",
            "numOfRelatedResources":"...",
            "isCollector":"...",
            "status":"..."
        }
}

Collector (Type: Collector)

Attribute

Type

Description

instanceID

long

ID for identifying instances.

name

string

Collector name

collectorType

enum

Collector type.

(For details about the specifiable values, see the table ProtocolType in List of enumerators.)

The specifiable values are as follows:

  • VCENTER
  • AJS
  • PFM
  • IM
  • CUSTOM
  • HTTP

osType

enum

Type of OS. This member is only set when the collectorType is AJS, PFM, or IM.

(For details about the specifiable values, see the table CollectorOsType in List of enumerators.)

autoCollectionType

enum

Settings for periodic executions of the collector.

(For details about the specifiable values, see the table ConnectType in List of enumerators.)

The specifiable values are as follows:

  • AutoConnect
  • NotAutoConnect

connectResult

enum

Last execution result of the collector.

(For details about the specifiable values, see the table ConnectStatusType in List of enumerators.)

The specifiable values are as follows:

  • NoConnect
  • Succeeded
  • Failed

refreshStatus

enum

Execution status of the collector.

(For details about the specifiable values, see the table ConnectStatusType in List of enumerators.)

The specifiable values are as follows:

  • NoConnect
  • InProgress

message

string

Message of the execution result of the collector

lastRefreshed

dateTime

The date and time when information for the following was last updated:

・refreshDateForInventory

・refreshDateForPerformance

・refreshDateForState

refreshDateForInventory

dateTime

Refresh date and time for the configuration information

refreshDateForPerformance

dateTime

Refresh date and time for the performance information

refreshDateForState

dateTime

Date and time when the state information is to be refreshed. This value can be obtained when all of the following conditions are met:

・The type of collector is VCENTER.

・The collection interval settings of "Status Monitoring (VM/Hypervisor)" are enabled.

numOfHypervisors

int

Number of hypervisors found by the collector

numOfVms

int

Number of virtual machines found by the collector

numOfHosts

int

Number of virtual machines found by the collector

numOfApplications

int

Number of applications found by the collector.

numOfContainers

int

Number of container nodes found by the collector.

numOfServices

int

Number of service resources found by the collector.

numOfResources

int

Number of management resources found by the collector.

collectorCredentials

CollectorCredential[]

Authentication information used for connections to monitoring targets.

productName

string

Collected-product name. This value can be obtained when the collectorType is CUSTOM_APP.

providerName

string

Provider name. This value can be obtained when the collectorType is CUSTOM_APP.

refreshDateForApp

dateTime

Date definition was applied. This value can be obtained when the collectorType is CUSTOM_APP.

plugin

Plugin

Defail information of the plug-in applied to the collector

collectorCredentials (Type: CollectorCredential)

Attribute

Type

Description

requireHostAddress

boolean

A flag that determines if an IP address or host name is required

- true: An IP address is required. An access-target identification key is not required.

- false: An IP address is not required. An access-target identification key is required.

This is used for the HTTP protocol.

ipAddress

string

IP address or host name used for connections to management software.

accessTargetIdentification

string

Access-target identification key (when no IP address is specified)

userId

string

User ID used for connections to management software. Specify a string of 255 or fewer bytes.

portNumber

int

Port number used for connections to management software.

hypertextTransferProtocolType

enum

Whether to use SSL (HTTPS) for connections to management software.

(For details about the specifiable values, see the table HypertextTransferProtocolType in List of enumerators.)

The specifiable values are as follows:

  • HTTP
  • HTTPS

domainName

string

Domain name: Used for application linkage when Windows is selected.

useAdministrativeShares

boolean

To share management, set true.

shareName

string

share Name

sharedFolder

string

shared Folder

logicalHostName

string

Logical Host Name

useLogicalHostName

boolean

To use logical host name, set true.

plugin (Type: Plugin)

Attribute

Type

Description

instanceID

long

ID for identifying instances

name

string

Name of the plug-in

pluginId

string

ID for identifying the plug-in

protocolType

enum

Protocol used for connections to monitoring targets

(For details about the specifiable values, see the table ProtocolType in List of enumerators.)

The specifiable values are as follows:

  • SNMP

formatversion

string

Format version of the plug-in

pluginversion

string

Version of the plug-in

pluginType

enum

Type of the plug-in

(For details about the specifiable values, see the table PluginType in List of enumerators.)

The specifiable values are as follows:

  • NODE_PLUGIN

numOfRelatedResources

int

Number of resources found by using the plug-in

isCollector

boolean

Whether it is Collector

status

enum

Status of the plug-in

(For details about the specifiable values, see the table PluginStatusType in List of enumerators.)

Status codes

Status code

Reason phrase

Description

201

Created

Success.

400

Bad Request

- A format of request body is invalid

- A request is invalid.

401

Unauthorized

No login privilege.

403

Forbidden

No create privilege.

409

Conflict

A resource with the same name exists.

412

Precondition Failed

The server is not available.

500

Internal Server Error

Server processing error.

Example code

[Request Header]
POST /Analytics/v1/objects/Collectors HTTP/1.1
Authorization: Basic c3lzdGVtOm1hbmFnZXI=
User-Agent: curl/7.33.0
Host: localhost:22015
Accept: application/json
Content-Type: application/json
Accept-Language: ja
Content-Length: 236

[Request Body]
{
  "name": "test Collector",
  "autoCollectionType": "AutoConnect",
  "collectorType": "VCENTER",
  "collectorCredentials": [
    {
      "ipAddress": "172.17.17.113",
      "userId": "test",
      "password": "dGVzdA==",
      "portNumber": 443,
      "hypertextTransferProtocolType": "HTTPS"
    }
  ]
}

[Response Header]
HTTP/1.1 201 Created
Date: Fri, 27 Nov 2015 08:23:46 GMT
Server: Cosminexus HTTP Server
Cache-Control: no-cache
WWW-Authenticate: HSSO bfb7bb1ac5122d4e95bddc86cfb215f4c04715_WVlGcHsLfg5ffg0I_V0810
Location: http://localhost:22015/Analytics/v1/objects/Collectors/13
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
Content-Type: application/json


[Response Body]
{
  "instanceID" : 13,
  "name" : "vCenter_71",
  "collectorType" : "VCENTER",
  "autoCollectionType" : "AutoConnect",
  "connectResult" : "Succeeded",
  "refreshStatus" : "NoConnect",
  "lastRefreshed" : "2016-11-21T17:17:59.926+09:00",
  "refreshDateForInventory" : "2016-11-21T16:52:03.271+09:00",
  "refreshDateForPerformance" : "2016-11-21T17:17:59.926+09:00",
  "numOfHypervisors" : 3,
  "numOfVms" : 33,
  "numOfApplications" : 0,
  "numOfContainers": 0,
  "numOfServices": 0,
  "numOfResources" 0,
  "collectorCredentials" : [ {
    "ipAddress" : "172.25.73.71",
    "userId" : "administrator@vsphere.local",
    "portNumber" : 443,
    "hypertextTransferProtocolType" : "HTTPS"
  } ]
}