Get Generator and Generator Tag Information over Rest API
Step 1: Authenticate
Submit your Client ID and Client Secret to obtain authorization token.
curl -X
POST 'https://api.equinix.com/oauth2/v1/token'
-H 'content-type: application/json'
-d '{
"grant_type": "client_credentials",
"client_id": "ABCDE12345",
"client_secret": "shhDontTell"
}'
Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret.
Refer to Requesting Access and Refresh tokens for more information on how to authorize your API calls.
If you are unaware of your user credentials for Equinix Smart View, contact your local Equinix Service Desk.
Step 2: Get Asset List
The first step is to get a list of all the assets to which a given customer has visibility. Invoke the Equinix Smart View below by providing your Equinix customer account number, your IBX code, for e.g. CH1 and the classification, such as electrical to obtain a list of all the electrical assets that are visible to you. For example, here we will get a Generator (electrical generator) and some key attributes of the Generator, such as alarmStatus, resiliencyStatus, alarmLastTriggeredTime and alarmLastCleared. All other electrical assets are also returned as part of the response.
Sample curl request
curl -X
GET "https://api.equinix.com/asset/v1/list?accountNo=1&ibx=CH1&classification=Electrical"
-H "content-type: application/json"
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2'
The list of all electrical assets including generators is returned as shown in the partial result below.
{
"payLoad": {
"classification": "Electrical",
"categories": [
{
"templates": [
{
"assets": [
{
"assetId": "CH1.Gen-1",
"ibx": "CH1",
"alarmStatus": "OK",
"resiliencyStatus": "Resiliency as Designed",
"alarmLastTriggeredTime": "Sep 16,2016 04:41 PM",
"alarmLastClearedTime": "Sep 16,2016 04:43 PM"
},
{
"assetId": "CH1.Gen-2",
"ibx": "CH1",
"alarmStatus": "OK",
"resiliencyStatus": "Resiliency as Designed",
"alarmLastTriggeredTime": "Sep 20,2016 04:48 PM",
"alarmLastClearedTime": "Sep 20,2016 04:53 PM"
},
{
"assetId": "CH1.Gen-3",
"ibx": "CH1",
"alarmStatus": "OK",
"resiliencyStatus": "Resiliency as Designed",
"alarmLastTriggeredTime": "Oct 04,2016 07:54 AM",
"alarmLastClearedTime": "Oct 04,2016 08:41 AM"
}
],
"templateId": "Generator"
}
],
"categoryName": "Global"
}
]
},
"status": {
"type": "INFO",
"statuscode": "1000",
"msg": "OK"
}
}
Refer to Get Assets List under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.
Step 3: Get Asset Details
If you pick one of these assets and you want more details on the asset attributes, you can use the asset details API. You can do so by, specifying the account number, IBX code, specific asset ID and its electrical or mechanical classification. Upon invoking the API, you will see for example, for CH1, the asset with type generator is returned along with its three other attributes. Among these attributes; fuelHours is one, the current value of which is the time and unit of measure, in hours. Another attribute is currentAlarmStatus, along with several other attributes such as runningEmergencyServices (yes or no), and voltage (0 volts). You can replace the assetId that was returned from the asset list API call and retrieve the attributes of another asset.
Sample curl request
curl -X
GET "https://api.equinix.com/asset/v1/details?accountNo=1&ibx=CH1&assetId=CH1.Gen-1&classification=Electrical"
-H "content-type: application/json"
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2'
Details of the given generator are returned as shown below.
{
"payLoad": {
"assetId": "CH1.Gen-1",
"assetType": "Generator",
"userPrefTimeZone": "America/Los_Angeles",
"tags": [
{
"value": "78.5",
"tagId": "CH1.Gen-1:fuelhours",
"tagDisplayName": "Fuel Hours",
"uom": "h",
"alarmStatus": "OK",
"readingTime": "20190324023353"
},
{
"value": "0",
"tagId": "CH1.Gen-1:runningemergencyservice",
"tagDisplayName": "Running Emergency Service",
"uom": "",
"alarmStatus": "OK",
"readingTime": "20190324023421"
},
{
"value": "0.0",
"tagId": "CH1.Gen-1:voltage",
"tagDisplayName": "Voltage",
"uom": "V",
"alarmStatus": "OK",
"readingTime": "20190324022309"
},
{
"value": "NORMAL",
"tagId": "CH1.Gen-1:alarm",
"tagDisplayName": "Alarm",
"uom": "",
"alarmStatus": "OK",
"readingTime": "20190324022351"
},
{
"value": "0",
"tagId": "CH1.Gen-1:runningnonemergencyservice",
"tagDisplayName": "Running NonEmergency Service",
"uom": "",
"alarmStatus": "OK",
"readingTime": "20190324023421"
},
{
"value": "READY TO START, AUTO",
"tagId": "CH1.Gen-1:summary",
"tagDisplayName": "Summary",
"uom": "",
"alarmStatus": "OK",
"readingTime": "20190324023421"
}
],
"lastMaintenanceDate": "Mar 17,2019",
"manufacturerName": "CATERPILLAR",
"equipmentModelNumber": "SR-4B",
"equipmentSerialNumber": "5JW00638",
"alarmLastTriggeredTime": null,
"alarmLastProcessedTime": null
},
"status": {
"type": "INFO",
"statuscode": "1000",
"msg": "OK"
}
}
Refer to Get Asset Details under the API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.
Step 4: Get Affected Asset Details
As a next step you may want to get all the affected locations of assets with a given assetId. This call will return all your cages and cabinets in power circuits that are being serviced by the asset. To make the call for affected assets, you will need to provide your customer account number, your IBX code and the assetId which was initially procured via a call to the API which fetches the list of assets. If the classification is electrical, then you will obtain information on the cage, cabinet and power circuits that are being serviced by that particular asset. This offers information on your assets that are impacted by the particular asset, for example, ASTS (Automatic static transfer switch).
Sample curl request
curl -X
GET "https://api.equinix.com/asset/v1/tagpoint/affected-assets?accountNo=1&ibx=CH1&classification=Electrical&assetId=CH1.ASTS-1-2-A"
-H "content-type: application/json"
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2'
The call returns a list of all the location assets that are supported by the assetId above.
{
"payLoad": {
"cages": [
{
"name": "CH1:05:BCM000",
"type": "cage",
"cabinets": [
{
"name": "CH1:05:BCM000:9999",
"type": "cabinet",
"circuits": [
{
"name": "14488436",
"type": "circuit"
},
{
"name": "M10294567",
"type": "circuit"
},
{
"name": "20679430",
"type": "circuit"
}
]
}
],
"circuits": null
},
{
"name": "CH1:05:FE00021",
"type": "cage",
"cabinets": [
{
"name": "CH1:05:FE00021:0101",
"type": "cabinet",
"circuits": [
{
"name": "20744057",
"type": "circuit"
}
]
}
],
"circuits": null
}
]
},
"status": {
"type": "INFO",
"statuscode": "1000",
"msg": "OK"
}
}
Refer to Get affected locations for given assets under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.
Step 5: Get Asset Tag
The next API that we can call is that which fetches the tag for an asset. A tag is an attribute of a specific asset which can have one or more tags. This API accepts the account number, IBX code, and tag ID as inputs to return the current value of that asset attribute or tag. For example, for the generator attribute fuelHours, you can obtain the current value which is a number denoting the number of hours, and the unit of measure in “hours”. The value returned for this attribute would be the last read value. If you need to retrieve more than one attribute, you can use the post flavor of this API.
Sample curl request
curl -X
GET "https://api.equinix.com/asset/v1/tagpoint/current?accountNo=1&ibx=CH1&tagId=CH1.Gen-1:fuelhours"
-H "content-type: application/json"
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2'
This call returns all the tagpoint details for fuelhours as shown below.
{
"payLoad": [
{
"value": "77.9",
"tagId": "CH1.Gen-1:fuelhours",
"tagDisplayName": "Fuel Hours",
"uom": "h",
"readingTime": "20190324033354"
}
],
"status": {
"type": "INFO",
"statuscode": "1000",
"msg": "OK"
}
}
Refer to Get tag point for a given asset under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.
Step 6: Get Trending Data
Finally, the last API in this use case provides insights into the trending data of a tag point. You can call the API by specifying the account number, the IBX code and the point that you're interested in. For example; you can specify fuelHours from Step 2, the interval (for example, 1 hour) and date range for which you want the recording. The data returned for this particular tag ID or attribute will be the various values and their recording time at a one-hour granularity. The API returns the tag ID along with its unit of measure. The interval at which we are returning the recording will be the same as what you provided when calling the API, along with the IBX and account number information with the various readings. This API offers you a snapshot of the data for that attribute.
Sample curl request
curl -X
GET "https://api.equinix.com/asset/v1/tagpoint/trending?accountNo=1&ibx=CH1&tagId=CH1.Gen-5:fuelhours&interval=1h&fromDate=1483244949000&toDate=1493958549001"
-H "content-type: application/json"
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2'
This call returns the tagpoint trending data (partial results) as shown below.
{
"payLoad": {
"accountNumber": "1",
"ibx": "CH1",
"interval": "1h",
"uom": "h",
"tagId": "CH1.Gen-5:fuelhours",
"tagDisplayName": "Fuel Hours",
"dataType": "Float",
"data": [
{
"datetime": "1484355108000",
"value": "81.21"
},
{
"datetime": "1484365910000",
"value": "80.35"
},
{
"datetime": "1484373126000",
"value": "81.23"
},
{
"datetime": "1484383929000",
"value": "82.15"
},
{
"datetime": "1484405555000",
"value": "81.33"
}
]
},
"status": {
"type": "INFO",
"statuscode": "1000",
"msg": "OK"
}
}
Refer to Get tag point trend data for a given asset under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.