Chatta subito con l'assistenza
Chat con il supporto

Foglight 7.1.0 - REST API Reference Guide

Rule

The Rule related APIs include the following:

•
Rule — Get all rules’ data
•
Rule — Get rule by id
Rule — Get all rules’ data
•
API Name: Get all rules’ data
•
Description: Get data of all rules.
•
Request type: GET
•
API path: /api/v1/rule/allRules
•
Sample usage: http://<server>:<port>/api/v1/rule/allRules
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Rule — Get rule by id
•
API Name: Get rule by ID
•
Description: Filter out rules by a rule ID.
•
Request type: GET
•
API path: /api/v1/rule/ruleId
•
Sample usage: http://<server>:<port>/api/v1/rule/ruleId
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown

Script

The Script related API includes the following:

•
Script — Run Script
•
Script — Run named scripts
•
Script — Run named scripts
Script — Run Script
•
API Name: Run Script
•
Description: You need be granted both the Administrator and API Access roles to use this API. This API is similar to the script console, but it does not support functionHelper, log, and out variables that are supported in the script console.
Name
Description

script

The script content.

catridgeName

Specifies the name of associated cartridge, and the name is case-sensitive.

scopeObjectId

Specifies the scope object. This item must be set if the scope variable is being used in scripts.

This API is disabled by default after the installation. Refer to the REST_DisabledAPI Registry Variable in Table 2 for more information about how to change this configuration.
•
Request type: POST
•
API path: /api/v1/script/runScript
•
Sample usage:
* 
NOTE: If you use & in your sample codes, make sure to convert it to &amp;.
Generate a post request using the following URL: http://<server>:<port>/api/v1/script/runScript
 
The basic format of request body can be set as below:
 
JSON:
{"script":"System.err.println('Hello World!')"}
 
XML:
<ScriptBean>
<script>System.err.println("Hello World!");</script>
</ScriptBean>
 
The complete format is as below:
 
JSON:
{"script":"#utilization#", "scopeObjectId":"3ebb2158-e5e9-4403-be3c-46fd8020efeb", "cartridgeName":"Infrastructure"}
 
XML:
<ScriptBean>
<script>#utilization#</script>
<cartridgeName>Infrastructure</cartridgeName>
<scopeObjectId>3ebb2158-e5e9-4403-be3c-46fd8020efeb</scopeObjectId>
</ScriptBean>
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json

•
Parameter:
Field
Type
Description

Content-Type

String
•
Data format = JSON, this value is application/json”.
•
Data format = XML, this value is “application/xml”.
•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Script — Run named scripts
•
API Name: Run named scripts
•
Description: Foglight supports embedding named scripts into cartridges by editing the monitoring policy XML. This API is used to call those named scripts.
•
Request type: GET
•
API path: /api/v1/script/runNamedScript?scriptName=<namedScriptName>&param=<script_parameter>
•
Sample usage: Consider for example there is a named script called 'getHostById', this named script requires the host instance id which type is string, then the sample API should be following: http://sever_url:port/api/v1/script/runNamedScript?scriptName=getHostById&param=b1b3ad72-2460-4576-b1ec-3ffd57016deb.
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

•
Parameter:
Field
Type
Description

param

String

This value is optional and depends whether the naming script has parameter. Separate multiple parameters by commas.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Subscribe alarm

The Subscribe related APIs include the following:

•
Subscribe alarm — Disconnect SSE
•
Subscribe alarm — List SSE
•
Subscribe alarm — Subscribe alarms by object ID
•
Subscribe alarm — Subscribe all alarms
Subscribe alarm — Disconnect SSE
•
API Name: Disconnect SSE
•
Description: Disconnect all the active Server-Sent Events (SSE) subscriptions.
•
Request type: GET
•
API path: /api/v1/subscription/disconnect/all/
•
Sample usage: http://<server>:<port>/api/v1/subscription/disconnect/all/
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Subscribe alarm — List SSE
•
API Name: List SSE
•
Description: Filter out all the active SSE subscriptions.
•
Request type: GET
•
API path: /api/v1/subscription/list/
•
Sample usage: http://<server>:<port>/api/v1/subscription/list
•
Header:
Field
Type
Description

Access-Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Subscribe alarm — Subscribe alarms by object ID
•
API Name: Subscribe alarms by object ID
•
Description: Watch the topology object by its topologyId, and subscribe to alarm-generated events through SSE. When the client is disconnected, there is no retry mechanism to send an event to the client. For more information, visit Server-Sent Events (SSE) Support and Server-Sent Events.
* 
NOTE: If the version of your Foglight Management Server is lower than 5.7.5.7, open the server.xml file under <fms_home>/server/tomcat/, then add asyncSupported="true" to all value items (for example, <Valve className="com.quest.nitro.web.tomcat.HttpsRedirectValve" asyncSupported="true"/>).
•
Request type: GET
•
API path: /api/v1/subscription/alarm/subscribe/topologyId
•
Sample usage:
<script>
if(typeof(EventSource) !== "undefined")
{var source = new EventSource("http://<server>:<port>/api/v1/subscription/alarm/subscribe
/67beea68-fa6f-4cd3-b122-dcb20db50360?Accept=application/json&Access-Token=sanpqvi54h9a59n03u6illuahj", {withCredentials: true});source.onmessage = function(event)
{
document.getElementById("result").innerHTML += event.data + "<br>";
};
} else {
document.getElementById("result").innerHTML = "Sorry, your browser does not support server-sent events...";
}
</script>
•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Subscribe alarm — Subscribe all alarms
•
API Name: Subscribe to all alarms
•
Description: Subscribe to alarm-generated events through SSE. When the client is disconnected, there is no retry mechanism to send an event to the client. For more information, visit Server-Sent Events (SSE) Support and Server-Sent Events.
* 
NOTE: If the version of your Foglight Management Server is lower than 5.7.5.7, open the server.xml file under <fms_home>/server/tomcat/, then add asyncSupported="true" to all value items (for example, <Valve className="com.quest.nitro.web.tomcat.HttpsRedirectValve" asyncSupported="true"/>).
•
Request type: GET
•
API path: /api/v1/subscription/alarm/subscribe
•
Sample usage:
<script>
if(typeof(EventSource) !== "undefined") {
var source = new EventSource("http://<server>:<port>/api/v1/subscription/alarm/subscribe?Accept=appl ication/json&Access-Token=5vr9jmptoskrpheaj2e31vvna6", {withCredentials: true});
source.onmessage = function(event) {
document.getElementById("result").innerHTML += event.data + "<br>";
};
} else {
document.getElementById("result").innerHTML = "Sorry, your browser does not support server-sent events...";
}
</script>
•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology

The Topology related APIs include the following:

•
Topology — Get properties’ value
•
Topology — Get property value
•
Topology — Get topology object by id
•
Topology — Get topology object by ids
•
Topology — Observations query
•
Topology — TopologyObject query
•
Topology — Push data
Topology — Get properties’ value
•
API Name: Get properties’ value
•
Description: Get properties of one topology object based on path. This topology object is specified by uniqueId.
•
Request type: GET
•
API path: /api/v1/topology/topologyId/paths
•
Sample usage: http://<server>:<port>/api/v1/topology/3546fa55-11b6-4943-b7cb-84ddcf350bc5/paths?path=name&path=uniqueId&path=utilization
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Parameter:
Field
Type
Description

path

String

The property path. This may include multiple paths.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — Get property value
•
API Name: Get property value
•
Description: Get property values by the path defined based on the given topology ID. The result may be DataObject, Primitive Object, Observation, or else.
•
Request type: GET
•
API path: /api/v1/topology/topologyId/path
•
Sample usage: http://<server>:<port>/api/v1/topology/abc94b3d-f599-4766-a979-f32d372ff47d/cpus/utilization
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — Get topology object by id
•
API Name: Get topology object by IDs
•
Description: Filter out topology objects by an object ID.
•
Request type: GET
•
API path: /api/v1/topology/topologyObjectId
•
Sample usage: http://<server>:<port>/api/v1/topology/1f478dec-f920-4da9-a8d2-b9ba0dcd4394
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — Get topology object by ids
•
API Name: Get topology object by ids
•
Description: Filter out topology objects by multiple IDs.
•
Request type: GET
•
API path: /api/v1/topology/topologyIds
•
Sample usage: http://<server>:<port>/api/v1/topology/topologyIds?Id=3546fa55-11b6-4943-b7cb-84ddcf350bc5&Id=67beea68-fa6f-4cd3-b122-dcb20db50360
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Parameter:
Field
Type
Description

Id

String

The topology object ID. This may include multiple IDs.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — Observations query
•
API Name: Observations query
•
Description: Filter out observations value by a batch query. The following lists the retrievalType:
Name
Description

RAW

Retrieve the raw data of an observation based on the time range.

AGGREGATE

Retrieve the aggregate data of an observation based on the time range.

AGGREGATE_AND_LAST

Retrieve the aggregate and last data of an observation based on the time range.

LAST_N

Retrieve the last N data of the observation based on the time range. If retrievalType is set to LAST_N, you need configure the value of numberOfValue that defines the letter N of LAST_N.

•
Request type: POST
•
API path: /api/v1/topology/batchQuery
•
Sample usage:
Generate a post request using the following url:
"http://<server>:<port>/api/v1/topology/batchQuery"
 
The basic format of request body can be set as below:
{"includes":[{"ids":["ca83d1a2-f04b-483d-b224-055967777e72"],"observationName":"utilization"}],
"endTime":1477987660722}
 
The following is the complete format of request body:
JSON:
{
"includes":[{"ids":["ca83d1a2-f04b-483d-b224-055967777e72"],"observationName":"utilization"},
{"ids":["f58f36ef-88ef-4264-9b8a-91df79fd37e9"],
"observationName":"utilization"},
{"ids":["f3df86e1-0718-4ccf-ae05-c25414b53db9",
"7910afd1-0247-4309-bae4-05f9419ab719",
"4ed2b409-cf18-4c14-a6ab-fdc19cff006e"],
"observationName":"percentMemory"}],
"startTime":1477984060722,
"endTime":1477987660722,
"granularity":3600000,
"numberOfValue":1,
"retrievalType":"AGGREGATE_AND_LAST"
}
 
XML:
<observationQueryParamBean>
<endTime>1477988816209</endTime>
<granularity>3600000</granularity>
<includes>
<ids>ca83d1a2-f04b-483d-b224-055967777e72</ids>
<observationName>utilization</observationName>
</includes>
<includes>
<ids>f58f36ef-88ef-4264-9b8a-91df79fd37e9</ids>
<observationName>utilization</observationName>
</includes>
<includes>
<ids>f3df86e1-0718-4ccf-ae05-c25414b53db9</ids>
<ids>7910afd1-0247-4309-bae4-05f9419ab719</ids>
<ids>4ed2b409-cf18-4c14-a6ab-fdc19cff006e</ids>
<observationName>percentMemory</observationName>
</includes>
<numberOfValue>1</numberOfValue>
<retrievalType>AGGREGATE_AND_LAST</retrievalType>
<startTime>1477985216208</startTime>
</observationQueryParamBean>
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Parameter:
Field
Type
Description

Content-Type

String
•
Data format = JSON, this value is “application/json”.
•
Data format = XML, this value is “application/xml”.
•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — TopologyObject query
•
API Name: TopologyObject query
•
Description: Filter out topology objects by a batch query.
•
Request type: POST
•
API path: /api/v1/topology/query
•
Sample usage:
Generate a post request using the following url:
http://<server>:<port>/api/v1/topology/query
 
The basic format of request body can be set as below:
{"queryText":"!Host"}
 
The following is the complete format of request body:
JSON:
{
"queryText":"!Host",
"caseSensitive":true,
"freshnessFactor":3600000.0,
"params":[{"name":"name","value":"nameofHost"},
{"name":"domainName" ,"value":"nameofDomain"}],
"queryTopologyObjects":true,
"requiresCoherentResults":true,
"scopingTopologyObjectId":"4f888425-a734-4bee-a5a7-4e24cd3c83cd",
"transactionTimestampMillis":3600000,
"ti meRangeStartTime":1477984060722,
"timeRangeEndTime":1477987094482,
"timeRangeGranularity":3600000,
"timeRangeMaxPoints":500
}
 
XML:
<queryParamBean>
<caseSensitive>true</caseSensitive>
<freshnessFactor>3600000.0</freshnessFactor>
<params>
<name>name</name>
<value>nameofHost</value>
</params>
<params>
<name>domainName</name>
<value>nameofDomain</value>
</params>
<queryText>!Host</queryText>
<queryTopologyObjects>true</queryTopologyObjects>
<requiresCoherentResults>true</requiresCoherentResults>
<scopingTopologyObjectId>4f888425-a734-4bee-a5a7- 4e24cd3c83cd</scopingTopologyObjectId>
<transactionTimestampMillis>3600000</transactionTimestampMillis>
<timeRangeStartTime>1477984060722</timeRangeStartTime>
<timeRangeEndTime>1477987094482</timeRangeEndTime>
<timeRangeGranularity>3600000</timeRangeGranularity>
<timeRangeMaxPoints>500</timeRangeMaxPoints>
</queryParamBean>
•
Header:
Field
Type
Description

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

Accept

String

Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•
Parameter:
Field
Type
Description

Content-Type

String
•
Data format = JSON, this value is “application/json”.
•
Data format = XML, this value is “application/xml”.
•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

Topology — Push data
•
API Name: Push data
•
Description: Push data to an existing topology object. The request body should be RAW data and the basic format can be set as below:
{
"data":[{
"typeName": "TypeName",
"properties": {
"simplePropertyName": "TestData1",
"MetricPropertyName": 11234,
"ObservationPropertyName": {
"simplePropertyNameOne": "testObservation1",
"simplePropertyNameTwo": 1495447993592,
"simplePropertyNameThree": 1495447993592
}
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}
Name
Description

data

Mandatory. Specifies the detailed data of an object.

typeName

Mandatory. Specifies the data type, and this field must be either of TopologyObject or its sub type.

properties

Mandatory. Specifies the property value of the type.

startTime

Mandatory. Specifies the data start time.

endTime

Mandatory. Specifies the data end time.

agentName

Mandatory. Specifies the value (in the string format) which identifies the client running this API.

When invoking this API, note the following:
•
Ensure that the data type (typeName) already exists in the server; otherwise this operation will fail.
If the data type is a new type, import this type by selecting Dashboards > Administrator > Data > Add Topology Type. Click the Help tab in the Add Topology Type dashboard to understand details of this new type.
•
All topology objects have the identity property (properties). The Management Server, based on this identity property, decides to merge the object with an existing object or to create a new object.
To find the identity property of a type, select Dashboards > Development Tools > Schema Browser (ensure that you have the Cartridge Developer role). If the identity property is a topology object, you can use the object unique ID as its reference. Fore more information, refer to the following Sample usage section.
The identity of Host type (hostId) is generate by some fields, so set the name and hostId properties at least if you want to create a host.
•
For the Observation type (including Metric) data, the data start time and end time use startTime and endTime in the request body.
•
If you see the message like “The rest agent cache queue is full...” in the log file, increase the value of the REST_AgentSubmitInfoQueueSize Registry Variable, and then run the following script in the Run Script dialog box. To run the following script, ensure that the value of Choose an Associated Cartridge (Optional) is set to Forge-RestAPI in the Administration > Tooling > Script Console > Scripts > Add > Run Script dialog box.
import com.quest.forge.rest.service.impl.RestAgentManagerImpl;
RestAgentManagerImpl.updateConfig();
•
Request type: POST
•
API path: /api/v1/topology/pushData
•
Header:
Field
Type
Description

Access-Token

String

The token is retrieved after successfully logging in to the Management Server.

Content-Type

String

Data format = JSON, this value is “application/json”.

•
Returned value:
Field
Type
Description

status

String

The response status.

data

String

Either the response data format (JSON/XML) or exception message.

error

String

Error code if some exception occurs; otherwise this field is not shown.

•
Sample usage:
•
Case 1: Create a general topology type instance. Consider for example we create an FSMAgentBlackout type instance. Find the identity of type FSMAgentBlackout is name in the Schema Browser dashboard. Use the following request body to create the FSMAgentBlackout type instance.
{
"data":[{
"typeName": "FSMAgentBlackout",
"properties": {
"name" : "Test-FSMAgentBlackout"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}
•
Case 2: Create a Host instance. If you want to submit Host type data, the name property is mandatory while vmId and systemId properites are optional. You can set both optional properties if you know their values. hostId is automatically generated based upon values of name, systemId, and vmId, so it is not required to set manually.
{
"data":[{
"typeName": "Host",
"properties": {
"hostId" : "Test-Host",
"name" : "Test-Host"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}
•
Case 3: Create a type instance which identity property is a topology object. Consider for example we create a HostProcess type instance. In the Schema Browser dashboard, find the identity properties of type HostProcess are name and os. The name property is a string, while the os property is OperatingSystem which is a topology type. Use the uniqueId of OperatingSystem as the reference, then create the HostProcess type instance as follows.
{
"data":[{
"name": "HostProcess",
"properties": {
"os" : "e197ee1a-a60d-4627-8313-72d6bd49ce61",
"name" : "Test-HostProcess"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}
•
Case 4: Create a custom type instance. Consider for example we have imported the below type definition in the Add Topology Type dashboard.
<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
</type>
The identity property is name in the above type definition. Use the following request body to create the custom type instance:
{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "Test-PushDataTest"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}
•
Case 5: Consider for example we have the following type definition.
<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
<property name='testMetric' type='Metric' is-containment='true'
unit-name='count' />
</type>
Use the following request body to push metrics.
{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "Test-PushDataTest",
"testMetric" : 100
}
}],
"startTime": 1499830726959,
"endTime": 1499830786959,
"agentName": "sampleagent"
}
If you still see your metrics after the metrics push, check the server log to see if you see any “Discarded value” warning.
•
Case 6: Consider for example we have the following type definition.
<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
<property name='testMetric' type='Metric' is-containment='true' unit- name='count' />
<property name='testObservation' type='TestObservation' is- containment='true' unit-name='count' />
</type>
<type name='TestObservation' extends='ComplexObservation'>
<property name='current' type='TestObservationValue' is-many='false' is- containment='true' />
<property name='latest' type='TestObservationValue' is-many='false' is- containment='true' />
<property name='history' type='TestObservationValue' is-many='true' is- containment='true' />
</type>
<type name='TestObservationValue' extends='ObservedValue'>
<property name='value' type='TestObject' is-containment='true'/>
</type>
<type name='TestObject' extends='DataObject'>
<property name='testName' type='String' />
<property name='createDate' type='Date' />
<property name='createTime' type='Double' />
</type>
Use the following request body to push observations.
{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "PushDataTest",
"testMetric": 112233,
"testObservation": {
"testName" : "testObservation",
"createDate": 1495447993592,
"createTime": 1495447993592
}
}
}],
"startTime": 1499839494614,
"endTime": 1499839554614,
"agentName": "sampleagent"
}
Related Documents

The document was helpful.

Seleziona valutazione

I easily found the information I needed.

Seleziona valutazione