Integrating with a Collector
Subscription API enables establishing a communication channel destination for events concerning environmental and operational status of selected assets. It supports AWS IoT Core, Azure Event Hub, and Webhook communication channels.
You can also create a subscription and access your data in the Equinix API. See Stream Colocation Data from the Equinix API for instructions.
Equinix mTLS Certificate
mTLS certificate is used as an extension of the TLS (former SSL) certificate for the server and client to authenticate each other. Equinix requires this trusted signed certificate from clients, similar to that provided by our services. Our subscription services offer you the additional option of connection verification. When a new batch of events is sent with each communication attempt, our subscription services use the certificates provided by the client to validate that the service we're sending the data to is the correct one.
Subscription API doesn't accept self-signed certificates. Use a CA certificate for the mutual authentication.
AWS IoT
Send data to AWS IoT Core by providing the HTTP endpoint when creating your subscription.
To authorize Equinix to send events to an AWS IoT Core destination, you must download the Equinix Certificate and register it in IoT Core console. Refer to the AWS Iot Core documentation for instructions.
Azure Event Hub
Self-service configuration for sending data to Azure Event Hub is not available. To enable sending to data to Azure, please contact support.
Webhooks
If you do not wish to use AWS or Azure as a collector, but you can provide a target URL to which streaming data can be sent, Equinix offers creating a subscription to send data to a generic webhook destination.
Object Formats for Collectors
The message format for the AWS IoT Core and Azure Event Hubs channels makes the messages more readable. Here are some examples of messages that are sent over API Plus subscriptions.
Environmental - temperature
{
"type": "environmental",
"data": {
"ibx": "CH2",
"asset": {
"id": "asset1",
"level": "ZONE"
},
"reading": {
"value": "23.300",
"unit": "CELSIUS"
},
"tag": {
"id": "temperature",
"displayName": "Temperature"
},
"readingTime": "2020-08-24T09:21:00.000Z"
}
}
Environmental - humidity
{
"type": "environmental",
"data": {
"ibx": "CH1",
"asset": {
"id": "asset1",
"level": "ZONE"
},
"reading": {
"value": "66.120",
"unit": "PERCENT"
},
"tag": {
"id": "humidity",
"displayName": "Humidity"
},
"readingTime": "2020-07-28T12:35:14.615Z"
}
}
Power
{
"type": "power",
"data": {
"ibx": "SP2",
"asset": {
"id": "0210:469593",
"type": "CIRCUIT"
},
"cage": "ssxxxxsss",
"cabinet": "SP2:01:021470:0210",
"accountNumber": "1000659151",
"realPower": {
"value": "0.522",
"unit": "kW"
},
"apparentPower": {
"value": "1.070",
"unit": "kVA"
},
"contractualPower": {
"value": "60.000",
"unit": "kVA"
},
"current": {
"value": "1.500",
"unit": "A"
},
"powerFactor": {
"value": "0.48",
"unit": "pf"
},
"soldCurrent": {
"value": "15.000",
"unit": "A"
},
"soldPower": {
"value": "2.880",
"unit": "kVA"
},
"powerConsumptionToContractual": {
"value": "32.151",
"unit": "PERCENT"
},
"cabinetRating": {
"value": "123.300",
"unit": "kVA"
},
"peakLastSevenDays": {
"value": "1.146",
"unit": "kVA"
},
"peakLastSevenDaysRatio": {
"value": "34.424",
"unit": "PERCENT"
},
"peakLastSevenDaysContractualPower": {
"value": "3.329",
"unit": "kVA"
},
"peakLastSevenDaysTime": "2020-07-29T07:00:00.000Z",
"lastUpdated": "2020-07-24T11:46:00.000Z",
"readingTime": "2020-07-24T11:45:00.000Z",
"description": "test description",
"oid": "1.3.6.1.2.1.299.2.10.6846",
"circuitType": "primary",
"customerName": "test customer"
}
}
Metered power - kWh
{
"type": "metered-power",
"data": {
"ibx": "LD9",
"asset": {
"id": "LD9.CBM-PDU-17-99",
"type": "Customer Billing Meter"
},
"cage": "LD9:0G:00Z13Z",
"cageSerialNo": "00Z13B-21010567",
"accountNumber": "1000006212",
"customerName": "ABC Company",
"kilowattHour": {
"value": "304574.323",
"unit": "kWh"
},
"readingTime": "2023-04-24T11:45:00.000Z",
"dataQuality": "Good"
}
}
Note: Metered power readings are available in kWh, kW, kVA, A, and pf (power factor) units.
Tag-point
{
"type": "tag-point",
"data": {
"ibx": "LA1",
"reading": {
"value": "33406.6",
"unit": "l/s"
},
"tag": {
"id": "LA1.Air-Handler-7-4-4:totalsupplyairflow",
"displayName": "Total Supply Air Flow"
},
"readingTime": "2020-08-24T09:21:00.000Z"
}
}
Custom Alert
{
"type": "alert",
"data": {
"ibx": "SG2",
"region": "APAC",
"asset": {
"id": "CH1.Colo.CH1_05_000550_0105",
"type": "ENVIRONMENTAL",
"classification": "Environmental"
},
"tag": {
"id": "temperature"
},
"threshold": {
"unit": "CELSIUS",
"maxValue": "-6.67",
"minValue": "-12.22"
},
"id": "zhe-15603221441540.3171591127612322145",
"triggeredTime": "2019-09-23T23:01:30.655Z",
"type": "environmental",
"typeId": "Absolute",
"conditional": "N",
"eventType": "Out of Range",
"heartbeat": false
}
}
System Alert
{
"type": "system-alert",
"data": {
"ibx": "SG2",
"region": "APAC",
"metro": "SG",
"country": "SG",
"currentValue": {
"unit": "kWh",
"value": "2.650479E7",
"type": "float"
},
"asset": {
"id": "9SG2.ELEC4AUPSR-A10ASBF0",
"type": "Circuit Breaker with Metering",
"classification": "Electrical"
},
"tag": {
"id": "SG2.ELEC5BUPSR-B14UAH2Q:breaker",
"displayName": "Bypass Not Available"
},
"conditionName": "Low",
"status": {
"acknowledged": true,
"acknowledgementTime": "2020-07-28T12:35:14.615Z",
"cleared": false,
"active": false
},
"threshold": {
"unit": "kWh",
"stateLimit": "80",
"message": "Drive not in Auto"
},
"severity": 820,
"triggeredTime": "2020-07-28T12:35:14.615Z",
"processedTime": "2020-07-28T12:35:14.615Z",
"normalProcessedTime": "2020-07-28T12:35:14.615Z",
"normalTriggeredTime": "2020-07-28T12:35:14.615Z",
"type": "Digital",
"heartbeat": false
}
}
Data Quality Indicators
The field dataQuality offers the Data Quality Indicators (DQI) of data points and alerts (system and custom) as part of the data itself. This is used to ensure and inform the API client that the data for DCIM assets is valid and collected reliably. The addition of DQI provides transparency regarding the quality of received data.
Store and Forward Indicators
The field messageRetried as the Store and Forward Indicator (SNFI) is used to communicate if the DCIM data is actually near real-time or delayed and sent at a later time due to a disrupted connection through the NRT channel. If the connection between the subscription client and publisher has an issue, the publisher uses the Store and Forward (SNF) mechanism to store the message on the publisher's side. Once the connection is re-established, these stored messages and NRT events are sent to the client after the established connection time. The data sent later because of the SNFI method, is marked, as they are not NRT data anymore, compared to other normal data.
Your API applications can make business rules and decisions based on both these indicators to improve data transparency and solution efficiency.
{
"messageRetried": true,
"type": "tag-point",
"data": {
"ibx": "SG2",
"reading": {
"value": "54.0",
"unit": "s"
},
"tag": {
"id": "SG2.UPS-5-RM A22-04:batterytimeremaining",
"displayName": "Battery Time Remaining"
},
"readingTime": "2021-03-25T03:48:00.510Z",
"dataQuality": "Good"
}
}